claude-code-session-manager 0.8.6 → 0.10.0

package/src/main/pluginInstall.cjs

@@ -0,0 +1,129 @@
+/**
+ * Plugin install — hidden pty wrapper around `claude plugin install <slug>`.
+ *
+ * Why pty (not exec/spawn): the CLI emits interactive progress, prompts, and
+ * colored output. A real pty gives the user faithful console output streamed
+ * into the Discover panel. Slow (~5s) but transparent.
+ *
+ * Channels:
+ *   ipcMain.handle('plugins:install', { slug }) -> { ok, exitCode }
+ *   webContents.send('plugins:install-progress', { slug, line })
+ *
+ * Safety:
+ *   - slug must match /^[a-z0-9\-/]+$/ (lowercase, hyphen, slash for owner/name).
+ *   - No shell:true — argv array passed directly to pty.spawn.
+ *   - cwd pinned to os.homedir().
+ *   - Only one install per slug at a time (concurrent calls reject early).
+ */
+
+const { ipcMain } = require('electron');
+const pty = require('node-pty');
+const path = require('node:path');
+const os = require('node:os');
+const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
+const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
+const { schemas } = require('./ipcSchemas.cjs');
+
+const SLUG_RE = /^[a-z0-9\-/]+$/;
+const MAX_LINE_BYTES = 16 * 1024;
+const KILL_AFTER_MS = 5 * 60 * 1000; // 5 min hard ceiling per install
+
+let mainWindow = null;
+const inFlight = new Map(); // slug -> proc
+
+function attachWindow(window) {
+  mainWindow = window;
+}
+
+function send(channel, payload) {
+  sendIfAlive(mainWindow, channel, payload);
+}
+
+function install({ slug }) {
+  if (typeof slug !== 'string' || !SLUG_RE.test(slug) || slug.length > 128) {
+    return Promise.resolve({ ok: false, exitCode: -1, error: 'invalid slug' });
+  }
+  if (inFlight.has(slug)) {
+    return Promise.resolve({ ok: false, exitCode: -1, error: 'install already in progress' });
+  }
+
+  return new Promise((resolve) => {
+    const home = os.homedir();
+    const extraPath = [
+      path.join(home, '.local', 'bin'),
+      path.join(home, '.npm-global', 'bin'),
+      '/usr/local/bin',
+      '/usr/bin',
+      '/bin',
+    ].join(':');
+    const env = cleanChildEnv({
+      PATH: `${extraPath}:${process.env.PATH || ''}`,
+      TERM: 'xterm-256color',
+      FORCE_COLOR: '0', // strip ANSI so the renderer doesn't have to.
+    });
+
+    const claudeBin = resolveClaudeBin();
+    let proc;
+    try {
+      proc = pty.spawn(claudeBin, ['plugin', 'install', slug], {
+        name: 'xterm-256color',
+        cols: 120,
+        rows: 30,
+        cwd: home,
+        env,
+      });
+    } catch (err) {
+      resolve({ ok: false, exitCode: -1, error: `spawn failed: ${err?.message ?? String(err)}` });
+      return;
+    }
+
+    inFlight.set(slug, proc);
+
+    let lineBuf = '';
+    const killTimer = setTimeout(() => {
+      try { proc.kill(); } catch { /* */ }
+    }, KILL_AFTER_MS);
+
+    proc.onData((data) => {
+      lineBuf += data;
+      let nl;
+      while ((nl = lineBuf.indexOf('\n')) >= 0) {
+        const line = lineBuf.slice(0, nl).replace(/\r$/, '');
+        lineBuf = lineBuf.slice(nl + 1);
+        send('plugins:install-progress', { slug, line });
+      }
+      // Guard runaway buffers without newlines.
+      if (lineBuf.length > MAX_LINE_BYTES) {
+        send('plugins:install-progress', { slug, line: lineBuf });
+        lineBuf = '';
+      }
+    });
+
+    proc.onExit(({ exitCode }) => {
+      clearTimeout(killTimer);
+      if (lineBuf.length > 0) {
+        send('plugins:install-progress', { slug, line: lineBuf });
+        lineBuf = '';
+      }
+      inFlight.delete(slug);
+      const code = typeof exitCode === 'number' ? exitCode : -1;
+      resolve({ ok: code === 0, exitCode: code });
+    });
+  });
+}
+
+function registerPluginInstallHandlers() {
+  ipcMain.handle('plugins:install', async (_e, payload) => {
+    // safeParse to preserve the existing `{ ok:false, exitCode:-1, error }`
+    // return shape on invalid input (the renderer expects this shape, not a
+    // thrown promise rejection).
+    const parsed = schemas.pluginsInstall.safeParse(payload);
+    if (!parsed.success) {
+      return { ok: false, exitCode: -1, error: 'invalid slug' };
+    }
+    return install({ slug: parsed.data.slug });
+  });
+}
+
+module.exports = { registerPluginInstallHandlers, attachWindow };

package/src/main/pty.cjs

@@ -5,6 +5,8 @@ const os = require('node:os');
 const fs = require('node:fs');
 const { addAllowedRoot } = require('./config.cjs');
 const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
+const { assertCwdInsideHome } = require('./lib/insideHome.cjs');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 
 /**
  * PtyManager — owns every claude PTY process, keyed by tabId (renderer-generated UUID).
@@ -26,17 +28,9 @@ class PtyManager {
 
     // Validate that cwd is inside homedir before widening the allowed-root set.
     if (cwd) {
-      const home = os.homedir();
-      let realCwd;
-      try {
-        realCwd = fs.realpathSync(cwd);
-      } catch {
-        realCwd = path.resolve(cwd);
-      }
-      if (realCwd !== home && !realCwd.startsWith(home + path.sep)) {
-        throw new Error(`pty cwd outside home directory: ${realCwd}`);
-      }
-      addAllowedRoot(realCwd);
+      const r = assertCwdInsideHome(cwd);
+      if (!r.ok) throw new Error(`pty ${r.error}`);
+      addAllowedRoot(r.realCwd);
     }
 
     // Idempotent reattach: renderer reloads (HMR/Ctrl+R) re-run App.tsx's
@@ -62,9 +56,7 @@ class PtyManager {
       if (existing.proc.exitCode != null) {
         const exitCode = existing.proc.exitCode;
         setImmediate(() => {
-          if (this.window && !this.window.isDestroyed()) {
-            this.window.webContents.send(`pty:exit:${tabId}`, { exitCode, signal: undefined });
-          }
+          sendIfAlive(this.window, `pty:exit:${tabId}`, { exitCode, signal: undefined });
         });
       }
       return { pid: existing.proc.pid, cwd: existing.cwd, reattached: true };
@@ -108,9 +100,7 @@ class PtyManager {
     console.log('[pty] spawned pid=', proc.pid, 'for tabId=', tabId);
 
     proc.onData((data) => {
-      if (this.window && !this.window.isDestroyed()) {
-        this.window.webContents.send(`pty:data:${tabId}`, data);
-      }
+      sendIfAlive(this.window, `pty:data:${tabId}`, data);
     });
 
     proc.onExit(({ exitCode, signal }) => {
@@ -122,9 +112,7 @@ class PtyManager {
         this.sessions.delete(tabId);
         return;
       }
-      if (this.window && !this.window.isDestroyed()) {
-        this.window.webContents.send(`pty:exit:${tabId}`, { exitCode, signal });
-      }
+      sendIfAlive(this.window, `pty:exit:${tabId}`, { exitCode, signal });
       this.sessions.delete(tabId);
     });
 
@@ -137,9 +125,7 @@ class PtyManager {
     if (!s) {
       // Tab was removed or never existed — tell the renderer so it can surface
       // "skipped" feedback rather than silently dropping the write.
-      if (this.window && !this.window.isDestroyed()) {
-        this.window.webContents.send('pty:write-error', { tabId, reason: 'no-pty' });
-      }
+      sendIfAlive(this.window, 'pty:write-error', { tabId, reason: 'no-pty' });
       return;
     }
     try {
@@ -149,12 +135,10 @@ class PtyManager {
       // error that node-pty re-throws) when writing to an exited process.
       // Catch here so the uncaught-exception handler never sees it, and notify
       // the renderer to surface "skipped" feedback.
-      if (this.window && !this.window.isDestroyed()) {
-        this.window.webContents.send('pty:write-error', {
-          tabId,
-          reason: String(err?.message || 'write-failed'),
-        });
-      }
+      sendIfAlive(this.window, 'pty:write-error', {
+        tabId,
+        reason: String(err?.message || 'write-failed'),
+      });
     }
   }
 

package/src/main/queueOps.cjs

@@ -0,0 +1,404 @@
+/**
+ * queueOps.cjs — bulk PRD operations + queue-health linter.
+ *
+ * This module is owned by Bundle D. It registers three IPC handlers:
+ *
+ *   schedule:lint-queue    — scan all PRDs in PRDS_DIR for anti-patterns
+ *   schedule:archive-prd   — move PRDS_DIR/<slug>.md → prds-archived/<ISO>/<slug>.md
+ *   schedule:retag-prd     — rewrite parallelGroup and/or estimateMinutes
+ *                            frontmatter; optionally rename slug to reflect
+ *                            the new NN- prefix
+ *
+ * All file mutations go through tmp + rename for atomicity. Path containment
+ * is enforced against PRDS_DIR via path.resolve() + startsWith() (mirrors
+ * scheduler.cjs's existing pattern).
+ *
+ * The linter rules come from research-04 §1 (queue-health) plus PRD 106's
+ * regex inventory. Rules:
+ *   - `^until ` at the start of a logical line  → fizzpop-style poll hang
+ *   - `^while true` (case insensitive)          → unbounded while loop
+ *   - `for .* in $(seq 1 [5-9][0-9][0-9]+)`     → unbounded large seq
+ *   - missing frontmatter title / cwd / estimateMinutes
+ *   - cwd doesn't exist on disk (fs.accessSync)
+ *   - `--no-verify` or `--no-gpg-sign`          → hook-skip flags
+ *
+ * Severity: 'error' for the loop patterns and missing required frontmatter;
+ * 'warn' for the rest.
+ *
+ * Time complexity: O(F × L) where F = number of PRD files, L = avg line count.
+ * Hot-loop-safe: regex tests are pre-compiled module-level constants.
+ */
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { ipcMain } = require('electron');
+const { SCHEDULE_SLUG_RE: SLUG_RE, schemas } = require('./ipcSchemas.cjs');
+const logs = require('./logs.cjs');
+const config = require('./config.cjs');
+
+const ROOT = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans');
+const PRDS_DIR = path.join(ROOT, 'prds');
+const PRDS_ARCHIVE_DIR = path.join(ROOT, 'prds-archived');
+const RETAG_LOG = path.join(ROOT, 'retag-log.jsonl');
+
+// ────────────────────────────────────────────── lint rules
+
+// Each rule: { id, severity, test: (line) => boolean }
+// O(1) regex test per line. Module-level so the compiled forms don't churn.
+const LINE_RULES = [
+  {
+    id: 'unbounded-until',
+    severity: 'error',
+    re: /^\s*until\s+/,
+    label: '"until" loop — risk of unbounded poll (see PRD 106 §1)',
+  },
+  {
+    id: 'while-true',
+    severity: 'error',
+    re: /^\s*while\s+(?:true|:)/i,
+    label: '"while true" — unbounded loop',
+  },
+  {
+    id: 'unbounded-seq',
+    severity: 'error',
+    // for X in $(seq 1 NNN) where NNN ≥ 500. PRD 106 §1 cites this exact pattern.
+    re: /for\s+\S+\s+in\s+\$\(seq\s+1\s+[5-9][0-9]{2,}/,
+    label: 'unbounded seq — for-loop range ≥500',
+  },
+  {
+    id: 'no-verify',
+    severity: 'warn',
+    re: /--no-verify\b/,
+    label: '--no-verify — skips git hooks',
+  },
+  {
+    id: 'no-gpg-sign',
+    severity: 'warn',
+    re: /--no-gpg-sign\b/,
+    label: '--no-gpg-sign — bypasses signing',
+  },
+];
+
+const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
+
+/**
+ * Lint a single PRD asynchronously. Returns { slug, findings: [...] }.
+ * O(L) per PRD where L is line count of the file. Reads via fsp so kernel
+ * I/O can overlap when called via Promise.all from lintAll().
+ */
+async function lintOneAsync(filePath) {
+  const slug = path.basename(filePath, '.md');
+  let raw;
+  try {
+    raw = await fsp.readFile(filePath, 'utf8');
+  } catch (e) {
+    return {
+      slug,
+      findings: [{ rule: 'read-error', line: 0, snippet: e?.message ?? 'read failed', severity: 'error' }],
+    };
+  }
+  return lintParsed(slug, raw);
+}
+
+function lintParsed(slug, raw) {
+  const findings = [];
+  const { fm, body, fmLineCount } = splitFrontmatter(raw);
+
+  // Required frontmatter keys.
+  if (!fm.title || !fm.title.trim()) {
+    findings.push({ rule: 'missing-title', line: 1, snippet: 'frontmatter "title" is required', severity: 'error' });
+  }
+  if (!fm.cwd || !fm.cwd.trim()) {
+    findings.push({ rule: 'missing-cwd', line: 1, snippet: 'frontmatter "cwd" is required', severity: 'error' });
+  } else {
+    // cwd existence — only if it looks like an absolute path. ~ -> homedir.
+    let candidate = fm.cwd;
+    if (candidate.startsWith('~/')) candidate = path.join(os.homedir(), candidate.slice(2));
+    if (path.isAbsolute(candidate)) {
+      try {
+        fs.accessSync(candidate, fs.constants.F_OK);
+      } catch {
+        findings.push({
+          rule: 'cwd-missing',
+          line: 1,
+          snippet: `cwd does not exist on disk: ${fm.cwd}`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+  if (fm.estimateMinutes === undefined || !String(fm.estimateMinutes).trim()) {
+    findings.push({
+      rule: 'missing-estimate',
+      line: 1,
+      snippet: 'frontmatter "estimateMinutes" is required',
+      severity: 'warn',
+    });
+  } else {
+    const v = Number(fm.estimateMinutes);
+    if (!Number.isInteger(v) || v <= 0) {
+      findings.push({
+        rule: 'bad-estimate',
+        line: 1,
+        snippet: `"estimateMinutes" must be a positive integer (got: ${fm.estimateMinutes})`,
+        severity: 'warn',
+      });
+    }
+  }
+
+  // Body line scan. Line numbers are 1-indexed and reflect the original file
+  // (so fm lines are skipped). O(L).
+  const bodyLines = body.split('\n');
+  for (let i = 0; i < bodyLines.length; i++) {
+    const line = bodyLines[i];
+    if (!line) continue;
+    for (const rule of LINE_RULES) {
+      if (rule.re.test(line)) {
+        findings.push({
+          rule: rule.id,
+          line: fmLineCount + i + 1,
+          snippet: `${rule.label} — ${line.trim().slice(0, 80)}`,
+          severity: rule.severity,
+        });
+      }
+    }
+  }
+
+  return { slug, findings };
+}
+
+/**
+ * Lint all PRDs in PRDS_DIR. Returns { reports: [...], scannedAt }.
+ * O(F × L). F is bounded by the actual prds/ contents (~200 today).
+ *
+ * Reads are issued in parallel via Promise.all so kernel-side I/O can
+ * overlap. Each lintOneAsync is self-isolating (its own try/catch on read),
+ * so Promise.all never rejects under normal use.
+ */
+async function lintAll() {
+  let entries = [];
+  try {
+    entries = await fsp.readdir(PRDS_DIR);
+  } catch {
+    return { reports: [], scannedAt: Date.now() };
+  }
+  const paths = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md') || name.startsWith('.')) continue;
+    paths.push(path.join(PRDS_DIR, name));
+  }
+  const reports = await Promise.all(paths.map(async (filePath) => {
+    try {
+      return await lintOneAsync(filePath);
+    } catch (e) {
+      return {
+        slug: path.basename(filePath, '.md'),
+        findings: [{ rule: 'lint-error', line: 0, snippet: e?.message ?? 'lint failed', severity: 'error' }],
+      };
+    }
+  }));
+  return { reports, scannedAt: Date.now() };
+}
+
+// ────────────────────────────────────────────── archive
+
+/**
+ * Move PRDS_DIR/<slug>.md → PRDS_ARCHIVE_DIR/<ISO>/<slug>.md.
+ * Atomic rename. Path containment checks both source and destination.
+ * Never deletes — always reversible from prds-archived/.
+ */
+async function archiveOne(slug, archiveDir) {
+  if (!SLUG_RE.test(slug)) return { ok: false, slug, error: 'invalid slug' };
+  const src = path.resolve(path.join(PRDS_DIR, `${slug}.md`));
+  if (!src.startsWith(PRDS_DIR + path.sep)) return { ok: false, slug, error: 'path escape (src)' };
+  const dst = path.resolve(path.join(archiveDir, `${slug}.md`));
+  if (!dst.startsWith(PRDS_ARCHIVE_DIR + path.sep)) return { ok: false, slug, error: 'path escape (dst)' };
+  try {
+    await fsp.rename(src, dst);
+    return { ok: true, slug, archivedTo: dst };
+  } catch (e) {
+    return { ok: false, slug, error: e?.message ?? 'rename failed' };
+  }
+}
+
+async function archiveMany(slugs) {
+  if (!Array.isArray(slugs) || slugs.length === 0) {
+    return { ok: true, archived: 0, archivedTo: null, results: [] };
+  }
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const archiveDir = path.join(PRDS_ARCHIVE_DIR, ts);
+  try {
+    await fsp.mkdir(archiveDir, { recursive: true });
+  } catch (e) {
+    logs.writeLine({ level: 'error', scope: 'queueOps', message: 'archiveMany: mkdir failed', meta: { error: e?.message } });
+    return { ok: false, archived: 0, archivedTo: null, results: [], error: e?.message ?? 'mkdir failed' };
+  }
+  const results = [];
+  for (const slug of slugs) {
+    results.push(await archiveOne(slug, archiveDir));
+  }
+  const archived = results.filter((r) => r.ok).length;
+  return { ok: true, archived, archivedTo: archiveDir, results };
+}
+
+// ────────────────────────────────────────────── retag
+
+/**
+ * Re-serialize the frontmatter of one PRD, optionally rewriting parallelGroup
+ * and/or estimateMinutes. If parallelGroup changes AND the slug has an NN-
+ * prefix, the file is renamed to reflect the new prefix (the old NN is
+ * stripped and replaced; if no prefix exists, one is prepended).
+ *
+ * Returns { ok, slug, newSlug, before, after, error? }.
+ *
+ * Mutates only the keys explicitly passed — preserves all other frontmatter
+ * lines verbatim (line-level replace, not a full YAML reparse). Reversible
+ * via retag-log.jsonl.
+ */
+async function retagOne({ slug, parallelGroup, estimateMinutes }) {
+  if (!SLUG_RE.test(slug)) return { ok: false, slug, error: 'invalid slug' };
+  const src = path.resolve(path.join(PRDS_DIR, `${slug}.md`));
+  if (!src.startsWith(PRDS_DIR + path.sep)) return { ok: false, slug, error: 'path escape' };
+
+  let raw;
+  try {
+    raw = await fsp.readFile(src, 'utf8');
+  } catch (e) {
+    return { ok: false, slug, error: `read failed: ${e?.message}` };
+  }
+  if (!raw.startsWith('---\n')) {
+    return { ok: false, slug, error: 'no frontmatter to retag' };
+  }
+  const end = raw.indexOf('\n---', 4);
+  if (end === -1) return { ok: false, slug, error: 'unterminated frontmatter' };
+
+  const fmRaw = raw.slice(4, end);
+  const bodyTail = raw.slice(end); // includes "\n---..."
+  const fmLines = fmRaw.split('\n');
+
+  // Snapshot before-values for the retag log.
+  const before = {};
+  const newFmLines = [];
+  const seen = { parallelGroup: false, estimateMinutes: false };
+  for (const line of fmLines) {
+    const m = line.match(/^([A-Za-z][A-Za-z0-9_]*)\s*:\s*(.*?)\s*$/);
+    if (!m) {
+      newFmLines.push(line);
+      continue;
+    }
+    const key = m[1];
+    if (key === 'parallelGroup' && parallelGroup !== undefined) {
+      before.parallelGroup = m[2];
+      newFmLines.push(`parallelGroup: ${parallelGroup}`);
+      seen.parallelGroup = true;
+    } else if (key === 'estimateMinutes' && estimateMinutes !== undefined) {
+      before.estimateMinutes = m[2];
+      newFmLines.push(`estimateMinutes: ${estimateMinutes}`);
+      seen.estimateMinutes = true;
+    } else {
+      newFmLines.push(line);
+    }
+  }
+  if (parallelGroup !== undefined && !seen.parallelGroup) {
+    newFmLines.push(`parallelGroup: ${parallelGroup}`);
+  }
+  if (estimateMinutes !== undefined && !seen.estimateMinutes) {
+    newFmLines.push(`estimateMinutes: ${estimateMinutes}`);
+  }
+
+  const newRaw = `---\n${newFmLines.join('\n')}${bodyTail}`;
+
+  // Decide whether to rename the file. NN-kebab pattern only.
+  let newSlug = slug;
+  if (parallelGroup !== undefined) {
+    const m = slug.match(/^(\d+)-(.+)$/);
+    if (m) {
+      newSlug = `${parallelGroup}-${m[2]}`;
+    } else {
+      // Slug doesn't have NN- prefix — prepend one.
+      newSlug = `${parallelGroup}-${slug}`;
+    }
+    if (!SLUG_RE.test(newSlug)) return { ok: false, slug, error: 'new slug would be invalid' };
+  }
+  const dst = path.resolve(path.join(PRDS_DIR, `${newSlug}.md`));
+  if (!dst.startsWith(PRDS_DIR + path.sep)) return { ok: false, slug, error: 'new path escape' };
+
+  // Atomic write via shared helper. If slug changed, write at the new path
+  // and unlink the old slug.
+  try {
+    await config.writeTextAtomic(dst, newRaw);
+    if (dst !== src) {
+      try { await fsp.unlink(src); } catch { /* if src is already same as dst (race), fine */ }
+    }
+  } catch (e) {
+    return { ok: false, slug, error: `write failed: ${e?.message}` };
+  }
+
+  const after = {};
+  if (parallelGroup !== undefined) after.parallelGroup = String(parallelGroup);
+  if (estimateMinutes !== undefined) after.estimateMinutes = String(estimateMinutes);
+  if (newSlug !== slug) {
+    before.slug = slug;
+    after.slug = newSlug;
+  }
+  return { ok: true, slug, newSlug, before, after };
+}
+
+async function appendRetagLog(entries) {
+  if (entries.length === 0) return;
+  try {
+    await fsp.mkdir(ROOT, { recursive: true });
+    const lines = entries.map((e) => JSON.stringify({ ts: new Date().toISOString(), ...e }) + '\n').join('');
+    await fsp.appendFile(RETAG_LOG, lines);
+  } catch (e) {
+    logs.writeLine({ level: 'warn', scope: 'queueOps', message: 'retag log append failed', meta: { error: e?.message } });
+  }
+}
+
+async function retagMany(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return { ok: true, retagged: 0, results: [] };
+  }
+  const results = [];
+  for (const item of items) {
+    results.push(await retagOne(item));
+  }
+  await appendRetagLog(results.filter((r) => r.ok));
+  const retagged = results.filter((r) => r.ok).length;
+  return { ok: true, retagged, results };
+}
+
+// ────────────────────────────────────────────── IPC registration
+
+function registerQueueOpsHandlers() {
+  ipcMain.handle('schedule:lint-queue', async () => {
+    return lintAll();
+  });
+
+  ipcMain.handle('schedule:archive-prd', async (_e, payload) => {
+    let parsed;
+    try { parsed = schemas.scheduleArchivePrd.parse(payload); }
+    catch (e) { return { ok: false, error: e?.message ?? 'invalid payload' }; }
+    return archiveMany(parsed.slugs);
+  });
+
+  ipcMain.handle('schedule:retag-prd', async (_e, payload) => {
+    let parsed;
+    try { parsed = schemas.scheduleRetagPrd.parse(payload); }
+    catch (e) { return { ok: false, error: e?.message ?? 'invalid payload' }; }
+    return retagMany(parsed.items);
+  });
+}
+
+module.exports = {
+  registerQueueOpsHandlers,
+  // Exposed for tests / future direct calls.
+  lintAll,
+  lintOneAsync,
+  archiveMany,
+  retagMany,
+  PRDS_DIR,
+  PRDS_ARCHIVE_DIR,
+};