thumbgate 1.29.2 → 1.31.0

package/scripts/parallel-workflow-orchestrator.js

@@ -1,18 +1,41 @@
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
 const { getFeedbackPaths } = require('./feedback-loop');
 const { ensureDir } = require('./fs-utils');
 const { loadOptionalModule } = require('./private-core-boundary');
 
+const RUNNER_SCRIPT_PATH = path.join(__dirname, 'async-job-runner.js');
+
+function launchPublicManagedJob(jobSpec, options = {}) {
+  const publicRunner = require('./async-job-runner');
+  const jobId = options.jobId || jobSpec.id || `job_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+  const { jobDir } = publicRunner.getJobRuntimePaths(jobId);
+  ensureDir(jobDir);
+  const jobFilePath = path.join(jobDir, 'job.json');
+  const finalSpec = { ...jobSpec, id: jobId };
+  fs.writeFileSync(jobFilePath, `${JSON.stringify(finalSpec, null, 2)}\n`, 'utf8');
+  publicRunner.queueJob({ ...finalSpec, jobFilePath });
+  const child = spawn(process.execPath, [RUNNER_SCRIPT_PATH, `--run-file=${jobFilePath}`], {
+    cwd: options.cwd || process.cwd(),
+    env: process.env,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return {
+    jobId,
+    jobFilePath,
+    launchMode: 'public-background',
+    pid: child.pid || null,
+  };
+}
+
 const launcher = loadOptionalModule(path.join(__dirname, 'hosted-job-launcher'), () => ({
-  launchManagedJob: () => {
-    throw new Error('Managed jobs require ThumbGate-Core.');
-  },
-  resumeHostedJob: () => {
-    throw new Error('Resuming hosted jobs requires ThumbGate-Core.');
-  },
+  launchManagedJob: launchPublicManagedJob,
 }));
 
 const runner = loadOptionalModule(path.join(__dirname, 'async-job-runner'), () => ({
@@ -20,8 +43,8 @@ const runner = loadOptionalModule(path.join(__dirname, 'async-job-runner'), () =
   listJobStates: () => [],
 }));
 
-const { launchManagedJob, resumeHostedJob } = launcher;
-const { readJobState, listJobStates } = runner;
+const { launchManagedJob } = launcher;
+const { readJobState } = runner;
 
 const DEFAULT_CONCURRENCY = 3;
 const POLL_INTERVAL_MS = 200;
@@ -45,7 +68,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'secret_scan',
-          command: 'node scripts/secret-scanner.js --json || true',
+          command: 'node scripts/secret-scanner.js --json',
         }
       ]
     });
@@ -55,7 +78,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'npm_audit',
-          command: 'npm audit --json || true',
+          command: 'npm audit --json',
         }
       ]
     });
@@ -65,7 +88,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'credential_gate_check',
-          command: 'node scripts/single-use-credential-gate.js plan || true',
+          command: 'node scripts/single-use-credential-gate.js plan',
         }
       ]
     });
@@ -76,7 +99,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'run_bench',
-          command: 'npx thumbgate bench --json --min-score=90 || true',
+          command: 'npx thumbgate bench --json --min-score=90',
         }
       ]
     });
@@ -86,7 +109,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'budget_status',
-          command: 'node scripts/budget-guard.js --status || true',
+          command: 'node scripts/budget-guard.js --status',
         }
       ]
     });
@@ -98,7 +121,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'search_fs',
-          command: 'node scripts/filesystem-search.js --query="pretool" --limit=5 || true',
+          command: 'node scripts/filesystem-search.js --query="pretool" --limit=5',
         }
       ]
     });
@@ -108,7 +131,7 @@ function planWorkflow(objective) {
       stages: [
         {
           name: 'ops_integrity',
-          command: 'node scripts/operational-integrity.js --ci || true',
+          command: 'node scripts/operational-integrity.js --ci',
         }
       ]
     });
@@ -119,7 +142,7 @@ function planWorkflow(objective) {
     plannedAt: nowIso(),
     subtasks: subtasks.map((task, idx) => ({
       ...task,
-      id: `subtask_${Date.now()}_${idx}_${Math.random().toString(36).slice(2, 6)}`,
+      id: `subtask_${Date.now()}_${idx}_${crypto.randomBytes(3).toString('hex')}`,
       autoImprove: false,
       verificationMode: 'none',
       recordFeedback: false,
@@ -132,12 +155,14 @@ function planWorkflow(objective) {
  * Polls active jobs until all complete, then consolidates the results.
  */
 async function executeWorkflow(objective, options = {}) {
-  const plan = planWorkflow(objective);
+  const plan = options.plan || planWorkflow(objective);
   const concurrency = Number(options.concurrency) || DEFAULT_CONCURRENCY;
   const timeoutMs = Number(options.timeoutMs) || 60000; // 60s timeout safety
+  const launchJob = options.launchManagedJob || launchManagedJob;
+  const getJobState = options.readJobState || readJobState;
 
   const { FEEDBACK_DIR } = getFeedbackPaths();
-  const workflowId = `wf_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const workflowId = `wf_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
   const workflowDir = path.join(FEEDBACK_DIR, 'workflows', workflowId);
   ensureDir(workflowDir);
 
@@ -145,17 +170,33 @@ async function executeWorkflow(objective, options = {}) {
   const queue = [...plan.subtasks];
   const results = [];
   const start = Date.now();
+  const statePath = path.join(workflowDir, 'state.json');
+
+  const persistState = (status) => {
+    fs.writeFileSync(statePath, `${JSON.stringify({
+      workflowId,
+      objective,
+      status,
+      updatedAt: nowIso(),
+      queue: queue.map((task) => ({ id: task.id, name: task.name })),
+      activeJobs: [...activeJobs.entries()].map(([taskId, info]) => ({ taskId, ...info })),
+      results,
+    }, null, 2)}\n`, 'utf8');
+  };
 
   const runNext = () => {
     while (activeJobs.size < concurrency && queue.length > 0) {
       const task = queue.shift();
-      const launched = launchManagedJob(task, { cwd: options.cwd });
+      const launched = launchJob(task, { cwd: options.cwd });
       activeJobs.set(task.id, {
         jobId: launched.jobId,
         taskName: task.name,
         launchedAt: Date.now(),
+        pid: launched.pid || null,
+        launchMode: launched.launchMode || 'managed',
       });
     }
+    persistState('running');
   };
 
   runNext();
@@ -166,7 +207,7 @@ async function executeWorkflow(objective, options = {}) {
       let allDone = true;
 
       for (const [taskId, info] of activeJobs.entries()) {
-        const jobState = readJobState(info.jobId);
+        const jobState = getJobState(info.jobId);
         if (!jobState) {
           allDone = false;
           continue;
@@ -193,11 +234,21 @@ async function executeWorkflow(objective, options = {}) {
       const elapsed = Date.now() - start;
       if (allDone && queue.length === 0) {
         clearInterval(interval);
+        persistState(results.every((result) => result.status === 'completed')
+          ? 'completed'
+          : 'completed_with_failures');
         resolve();
       } else if (elapsed >= timeoutMs) {
         clearInterval(interval);
         // Timeout remaining active tasks
         for (const [taskId, info] of activeJobs.entries()) {
+          if (info.pid) {
+            try {
+              process.kill(process.platform === 'win32' ? info.pid : -info.pid, 'SIGTERM');
+            } catch {
+              // The worker may have exited between the last poll and timeout.
+            }
+          }
           results.push({
             taskId,
             taskName: info.taskName,
@@ -206,6 +257,17 @@ async function executeWorkflow(objective, options = {}) {
             lastError: { message: `Subtask timed out after ${timeoutMs}ms`, code: 'TIMEOUT' },
           });
         }
+        for (const task of queue.splice(0)) {
+          results.push({
+            taskId: task.id,
+            taskName: task.name,
+            jobId: null,
+            status: 'timeout',
+            lastError: { message: `Subtask was not launched before ${timeoutMs}ms`, code: 'TIMEOUT' },
+          });
+        }
+        activeJobs.clear();
+        persistState('timed_out');
         resolve();
       }
     }, POLL_INTERVAL_MS);
@@ -234,6 +296,7 @@ async function executeWorkflow(objective, options = {}) {
     durationMs,
     reportPath,
     results,
+    statePath,
   };
 }
 
@@ -290,4 +353,5 @@ module.exports = {
   planWorkflow,
   executeWorkflow,
   compileWorkflowReport,
+  launchPublicManagedJob,
 };

package/scripts/pragmatic-hybrid-search.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pragmatic multi-stage hybrid retrieval (inspired by turbopuffer + Pragmatic Engineer playbook).
+ *
+ * We do NOT call turbopuffer SaaS. We steal the architecture patterns:
+ *   1) Multi-query first stage: lexical/BM25-ish list ⊕ dense list (when embedder exists)
+ *   2) Rank fusion (RRF) — ranks, not raw scores
+ *   3) Attribute-aware first-stage boosts (recency Decay, occurrence Saturate)
+ *   4) Field-weighted BM25 second-stage rerank
+ *   5) Diversification (limit-per domain/tool) so one theme does not monopolize top-K
+ *   6) Dual features on candidates (lexicalRank, denseRank, rrfScore, attributeBoost)
+ *   7) Continuous recall sampling hook for offline monitoring
+ *
+ * Application search logic stays here; indexes stay local (JSONL + optional LanceDB).
+ *
+ * @see https://turbopuffer.com/docs/hybrid
+ * @see https://turbopuffer.com/blog/rank-by-attribute
+ * @see https://turbopuffer.com/blog/continuous-recall
+ */
+
+const path = require('path');
+const fs = require('fs');
+const crypto = require('node:crypto');
+
+const DEFAULT_RRF_K = 60;
+const DEFAULT_POOL = 50;
+const DEFAULT_TOP_K = 10;
+
+/**
+ * Saturate(x) = x^e / (x^e + midpoint^e) ∈ [0, 1)
+ * Used for "higher is better" attributes (occurrence count, engagement).
+ */
+function saturate(value, midpoint = 3, exponent = 1) {
+  const x = Math.max(0, Number(value) || 0);
+  const m = Math.max(1e-9, Number(midpoint) || 1);
+  const e = Math.max(0.1, Number(exponent) || 1);
+  const xe = Math.pow(x, e);
+  const me = Math.pow(m, e);
+  return xe / (xe + me);
+}
+
+/**
+ * Decay(x) = midpoint^e / (x^e + midpoint^e) ∈ (0, 1]
+ * Used for distances (age in days). Recent → ~1, old → ~0.
+ */
+function decay(value, midpoint = 30, exponent = 1) {
+  const x = Math.max(0, Number(value) || 0);
+  const m = Math.max(1e-9, Number(midpoint) || 1);
+  const e = Math.max(0.1, Number(exponent) || 1);
+  const me = Math.pow(m, e);
+  return me / (Math.pow(x, e) + me);
+}
+
+function ageDays(timestamp) {
+  if (!timestamp) return null;
+  const t = new Date(timestamp).getTime();
+  if (!Number.isFinite(t)) return null;
+  return Math.max(0, (Date.now() - t) / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * Attribute boost comparable in scale to a weak BM25 term (~0–1.5).
+ * turbopuffer: Sum(BM25, Product(w, Decay/Saturate(attr)))
+ */
+function attributeBoost(doc, options = {}) {
+  const recencyMidpointDays = options.recencyMidpointDays ?? 30;
+  const recencyWeight = options.recencyWeight ?? 0.35;
+  const occurrenceMidpoint = options.occurrenceMidpoint ?? 3;
+  const occurrenceWeight = options.occurrenceWeight ?? 0.25;
+  const negativeSignalWeight = options.negativeSignalWeight ?? 0.15;
+
+  let boost = 0;
+  const age = ageDays(doc.timestamp || doc.metadata?.timestamp);
+  if (age != null) {
+    boost += recencyWeight * decay(age, recencyMidpointDays, 1);
+  }
+
+  const occurrences = Number(
+    doc.metadata?.occurrences
+    ?? doc.occurrences
+    ?? doc.metadata?.count
+    ?? 0,
+  );
+  if (occurrences > 0) {
+    boost += occurrenceWeight * saturate(occurrences, occurrenceMidpoint, 1);
+  }
+
+  const signal = String(doc.signal || '').toLowerCase();
+  if (signal === 'negative' || signal === 'down' || (doc.tags || []).includes('negative')) {
+    boost += negativeSignalWeight;
+  }
+
+  return boost;
+}
+
+/**
+ * RRF over ranked id lists. Optional per-list weights (default 1).
+ * score = Σ weight_i / (k + rank_i)
+ */
+function reciprocalRankFusion(rankedLists, options = {}) {
+  const k = Math.max(1, Number(options.k) || DEFAULT_RRF_K);
+  const weights = options.weights || rankedLists.map(() => 1);
+  const scores = new Map();
+
+  rankedLists.forEach((list, listIndex) => {
+    const w = Number(weights[listIndex]) || 1;
+    const ids = (list || []).map((item) => (typeof item === 'string' ? item : item.id)).filter(Boolean);
+    ids.forEach((id, rank) => {
+      const add = w / (k + rank + 1);
+      scores.set(id, (scores.get(id) || 0) + add);
+    });
+  });
+
+  return [...scores.entries()]
+    .map(([id, score]) => ({ id, score }))
+    .sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Diversify top-K: at most `perLimit` docs share the same key (domain or primary tool).
+ * turbopuffer limit.per pattern.
+ */
+function diversifyByAttribute(rankedDocs, options = {}) {
+  const total = options.total || DEFAULT_TOP_K;
+  const perLimit = options.perLimit || 3;
+  const keyFn = options.keyFn || ((doc) => {
+    const domain = doc.metadata?.domain || doc.tags?.[0] || 'general';
+    const tool = (doc.metadata?.toolsUsed || [])[0] || 'any';
+    return `${domain}::${tool}`;
+  });
+
+  const counts = new Map();
+  const out = [];
+  for (const doc of rankedDocs || []) {
+    const key = keyFn(doc);
+    const n = counts.get(key) || 0;
+    if (n >= perLimit) continue;
+    counts.set(key, n + 1);
+    out.push(doc);
+    if (out.length >= total) break;
+  }
+  // If diversification emptied the list too aggressively, pad with remainder
+  if (out.length < total) {
+    const seen = new Set(out.map((d) => d.id));
+    for (const doc of rankedDocs || []) {
+      if (seen.has(doc.id)) continue;
+      out.push(doc);
+      if (out.length >= total) break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build multi-query lists + fuse + attribute boost + BM25 rerank.
+ *
+ * @param {object} params
+ * @param {Array<object>} params.corpus - memory-shaped docs with id
+ * @param {string} params.query
+ * @param {string} [params.toolName]
+ * @param {object} [params.options]
+ */
+function pragmaticHybridSearch(params = {}) {
+  const {
+    corpus = [],
+    query = '',
+    toolName = 'Bash',
+    options = {},
+  } = params;
+
+  const {
+    scoreRelevance,
+    buildActionSignature,
+    reciprocalRankFusion: rrfFromLesson,
+  } = require('./lesson-retrieval');
+  const { rerankLessons } = require('./lesson-reranker');
+
+  const topK = options.topK || DEFAULT_TOP_K;
+  const pool = options.pool || DEFAULT_POOL;
+  const rrfK = options.rrfK || DEFAULT_RRF_K;
+  const diversify = options.diversify !== false;
+  const denseRankedIds = options.denseRankedIds || []; // precomputed dense order (optional)
+  const queryVariants = [...new Set(
+    [query, ...(options.queryVariants || [])]
+      .map((value) => String(value || '').trim())
+      .filter(Boolean),
+  )].slice(0, 4);
+
+  // --- Query 1: lexical / sparse (always) ---
+  // Attribute boost reorders candidates that already have lexical signal (or will
+  // enter via dense multi-query). It must NOT alone promote zero-overlap docs —
+  // that would break the lexical-vs-hybrid paraphrase contract and flood top-K
+  // with recent-but-unrelated mistakes (turbopuffer: attr is another clause, not
+  // a substitute for matching).
+  const denseIdSet = new Set((denseRankedIds || []).slice(0, pool));
+  const lexicalLists = [];
+  const bestLexicalById = new Map();
+  for (const variant of queryVariants) {
+    const actionSig = buildActionSignature(toolName, variant);
+    const scoredForVariant = corpus.map((mem) => {
+      const base = scoreRelevance(mem, toolName, variant, actionSig);
+      const attr = attributeBoost(mem, options.attribute);
+      const inDense = denseIdSet.has(mem.id);
+      const relevanceScore = (base > 0.1 || inDense) ? (base + attr) : 0;
+      return {
+        ...mem,
+        lexicalScore: base,
+        attributeBoost: attr,
+        relevanceScore,
+      };
+    })
+      .filter((memory) => memory.relevanceScore > 0.05)
+      .sort((left, right) => right.relevanceScore - left.relevanceScore);
+    lexicalLists.push(scoredForVariant.slice(0, pool).map((memory) => memory.id));
+    for (const memory of scoredForVariant) {
+      const previous = bestLexicalById.get(memory.id);
+      if (!previous || memory.relevanceScore > previous.relevanceScore) {
+        bestLexicalById.set(memory.id, memory);
+      }
+    }
+  }
+
+  const lexicalScored = [...bestLexicalById.values()]
+    .sort((left, right) => right.relevanceScore - left.relevanceScore);
+  /*
+   * The best score carries candidate metadata; each query variant keeps its
+   * own ranked list for RRF so expansion cannot overwrite the original query.
+   */
+  const lexicalRanked = lexicalLists[0] || [];
+
+  // --- Query 2: dense (optional; caller supplies ids when embedder ran) ---
+  const denseRanked = (denseRankedIds || []).slice(0, pool);
+  const denseWeight = Math.max(0.1, Number(options.denseWeight) || 1.5);
+
+  // --- Fuse multi-query ranks (RRF) ---
+  const lists = denseRanked.length > 0
+    ? [...lexicalLists, denseRanked]
+    : lexicalLists;
+  const weights = denseRanked.length > 0
+    ? [...lexicalLists.map(() => 1), denseWeight]
+    : lexicalLists.map(() => 1);
+  const fuse = typeof rrfFromLesson === 'function'
+    ? rrfFromLesson(lists, { k: rrfK, weights })
+    : reciprocalRankFusion(lists, { k: rrfK, weights });
+
+  const byId = new Map(corpus.map((m) => [m.id, m]));
+  const lexMeta = new Map(lexicalScored.map((m, i) => [m.id, {
+    lexicalRank: i + 1,
+    lexicalScore: m.lexicalScore,
+    attributeBoost: m.attributeBoost,
+    relevanceScore: m.relevanceScore,
+  }]));
+  const denseRankMap = new Map(denseRanked.map((id, i) => [id, i + 1]));
+
+  const maxFusionScore = fuse[0]?.score || 1;
+  const candidates = fuse.slice(0, pool).map((entry) => {
+    const mem = byId.get(entry.id);
+    if (!mem) return null;
+    const meta = lexMeta.get(entry.id) || {};
+    return {
+      ...mem,
+      relevanceScore: meta.relevanceScore ?? entry.score,
+      rrfScore: entry.score,
+      lexicalRank: meta.lexicalRank || null,
+      denseRank: denseRankMap.get(entry.id) || null,
+      fusionScoreNormalized: entry.score / maxFusionScore,
+      lexicalScore: meta.lexicalScore ?? 0,
+      attributeBoost: meta.attributeBoost ?? 0,
+      hybridFeatures: {
+        rrfScore: entry.score,
+        lexicalRank: meta.lexicalRank || null,
+        denseRank: denseRankMap.get(entry.id) || null,
+        attributeBoost: meta.attributeBoost ?? 0,
+        fusionScoreNormalized: entry.score / maxFusionScore,
+      },
+    };
+  }).filter(Boolean);
+
+  if (candidates.length === 0) {
+    return {
+      results: [],
+      meta: {
+        strategy: denseRanked.length ? 'hybrid-rrf' : 'lexical-attribute',
+        lexicalPool: lexicalRanked.length,
+        densePool: denseRanked.length,
+        fused: 0,
+        rerankApplied: false,
+        queryVariants,
+      },
+    };
+  }
+
+  // --- Second stage: field-weighted BM25F rerank ---
+  let reranked = rerankLessons(query, candidates, { topK: pool, toolName });
+
+  // Light blend of attribute boost into reranked score (keeps recency after BM25)
+  reranked = reranked.map((doc) => {
+    const attr = doc.attributeBoost ?? attributeBoost(doc, options.attribute);
+    const base = doc.rerankedScore ?? doc.relevanceScore ?? 0;
+    const fusionWeight = denseRanked.length > 0
+      ? Math.max(0, Math.min(1, Number(options.fusionWeight) || 0.7))
+      : 0;
+    return {
+      ...doc,
+      attributeBoost: attr,
+      rerankedScore: (
+        (1 - fusionWeight) * base
+        + fusionWeight * (doc.fusionScoreNormalized || 0)
+        + 0.05 * attr
+      ),
+    };
+  }).sort((a, b) => (b.rerankedScore || 0) - (a.rerankedScore || 0));
+
+  const diversified = diversify
+    ? diversifyByAttribute(reranked, {
+      total: topK,
+      perLimit: options.perLimit || 3,
+    })
+    : reranked.slice(0, topK);
+
+  return {
+    results: diversified,
+    meta: {
+      strategy: denseRanked.length ? 'hybrid-rrf+attr+rerank' : 'lexical-attr+rerank',
+      lexicalPool: lexicalRanked.length,
+      densePool: denseRanked.length,
+      fused: fuse.length,
+      diversified: diversify,
+      rrfK,
+      denseWeight,
+      queryVariants,
+      rerankApplied: true,
+    },
+  };
+}
+
+/**
+ * Continuous recall sampling (turbopuffer spirit): append a sample of retrieval
+ * outcomes for offline monitoring. Never throws; never blocks the hot path.
+ */
+function sampleRetrievalRecall(event, options = {}) {
+  try {
+    if (options.enabled === false) return { sampled: false };
+    const rate = Number(options.sampleRate ?? process.env.THUMBGATE_RETRIEVAL_RECALL_SAMPLE_RATE ?? 0.02);
+    // crypto PRNG — not security-critical sampling, but avoid Math.random for Sonar S2245
+    const roll = crypto.randomInt(0, 1_000_000) / 1_000_000;
+    if (!(rate > 0) || roll > rate) return { sampled: false };
+
+    const feedbackDir = options.feedbackDir
+      || process.env.THUMBGATE_FEEDBACK_DIR
+      || path.join(process.cwd(), '.thumbgate');
+    const outDir = path.join(feedbackDir, 'retrieval-recall-samples');
+    fs.mkdirSync(outDir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      ...event,
+    });
+    fs.appendFileSync(path.join(outDir, 'samples.jsonl'), `${line}\n`, 'utf8');
+    return { sampled: true };
+  } catch {
+    return { sampled: false, error: true };
+  }
+}
+
+module.exports = {
+  saturate,
+  decay,
+  ageDays,
+  attributeBoost,
+  reciprocalRankFusion,
+  diversifyByAttribute,
+  pragmaticHybridSearch,
+  sampleRetrievalRecall,
+  DEFAULT_RRF_K,
+  DEFAULT_POOL,
+  DEFAULT_TOP_K,
+};

package/scripts/published-cli.js

@@ -13,6 +13,14 @@ function runtimePrefixDir(prefixDir) {
   return prefixDir || path.join(os.homedir(), '.thumbgate', 'runtime');
 }
 
+// For GENERATED SHELL COMMANDS only. Shell command strings land in shared, committed config
+// (.mcp.json entries, hook command lines), so expanding os.homedir() at generation time bakes
+// the generating machine's home into files other machines execute — /Users/alice/.thumbgate
+// fails with a permission error on bob's machine. shellQuote uses double quotes, so a literal
+// $HOME expands at RUNTIME on whichever machine runs the command. Non-shell consumers
+// (execFileSync paths) must keep using runtimePrefixDir, which returns a real filesystem path.
+const SHELL_RUNTIME_PREFIX = '$HOME/.thumbgate/runtime';
+
 function installedRuntimeBin(prefixDir) {
   return path.join(runtimePrefixDir(prefixDir), 'node_modules', '.bin', 'thumbgate');
 }
@@ -32,7 +40,9 @@ function publishedCliArgs(pkgVersion, commandArgs = [], options = {}) {
 }
 
 function publishedCliShellCommand(pkgVersion, commandArgs = [], options = {}) {
-  const prefixDir = runtimePrefixDir(options.prefixDir);
+  // Default to the runtime-expanded $HOME form; an explicit options.prefixDir (tests,
+  // throwaway prefixes) is honoured verbatim.
+  const prefixDir = options.prefixDir || SHELL_RUNTIME_PREFIX;
   const runtimeBin = installedRuntimeBin(prefixDir);
   const escapedArgs = commandArgs.map(shellQuote).join(' ');
   const fastPath = `[ -x ${shellQuote(runtimeBin)} ] && exec ${shellQuote(runtimeBin)}${escapedArgs ? ` ${escapedArgs}` : ''}`;