@krtclcdy/tersio 2.25.6 → 2.25.7

package/extensions/pstack/skills/why/references/sources/sentry.md

@@ -0,0 +1,66 @@
+# Sentry Error History
+
+## How to search it
+
+Use the Sentry MCP.
+
+1. **Orient.** If you don't know the project slug and organization:
+
+   ```
+   find_organizations
+   find_projects
+   ```
+
+2. **Search for issues related to the target.**
+
+   ```
+   search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile")
+   ```
+
+   Build queries from the exception class names the target handles, its function or class name, the error message strings it checks for, and its file path.
+
+3. **Narrow by release and time window.**
+
+   ```
+   search_issue_events (filter by release, time, environment, trace ID, tags)
+   get_issue_tag_values (for an issue, see distribution across versions, users, environments)
+   ```
+
+   For a suspected issue, check **first seen** and **last seen** (does the stop line up with the target's ship date?), the **affected releases** (which saw it, and which was the fix?), and the **frequency trajectory** (did it spike, then get resolved?).
+
+4. **Pull the full event for context.**
+
+   ```
+   get_sentry_resource (pass a Sentry URL or type+ID)
+   ```
+
+   Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against?
+
+5. **Check releases that landed near the target.**
+
+   ```
+   find_releases (around the commit date of the target)
+   ```
+
+   Cross-reference release version with the PR's merge date.
+
+6. **Use Seer sparingly.**
+
+   ```
+   analyze_issue_with_seer
+   ```
+
+   Seer's AI root-cause analyses are a hypothesis generator. Treat them as inference, not authoritative. The actual events and stack traces are the primary evidence.
+
+## What to return
+
+For each relevant issue:
+- Issue ID and title
+- Project and organization
+- First seen / last seen timestamps
+- Event count (and sampling rate if known)
+- Affected releases
+- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary)
+- First/last-seen correlation with the target's ship date
+- Link to the issue
+- Any author comments or resolution notes

package/extensions/pstack/skills/why/references/sources/slack.md

@@ -0,0 +1,17 @@
+# Slack Conversations
+
+## How to search it
+
+Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap.
+
+1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold.
+3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`).
+4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface.
+
+## Common pitfalls
+
+- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
+- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
+- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
+- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.

package/extensions/pstack/skills/why/references/synthesizer-prompt.md

@@ -0,0 +1,129 @@
+# Synthesizer Prompt Template
+
+Fill in the placeholders.
+
+---
+
+You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't.
+
+## The Question
+
+> {QUESTION}
+
+## The Code Anchor
+
+**Target files:** {FILES_WITH_LINE_RANGES}
+
+**Key symbols:** {SYMBOLS}
+
+## Investigator Findings
+
+{ALL_INVESTIGATOR_FINDINGS}
+
+## Sources That Weren't Searched
+
+{SKIPPED_SOURCES_WITH_REASONS}
+
+## Epistemics Framework
+
+You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules:
+
+1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing.
+2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
+3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
+4. Never cite code as evidence for its own intent.
+5. Document gaps. Don't fill them with plausible-sounding guesses.
+6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently.
+
+## Instructions
+
+1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions.
+2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference.
+3. **Surface contradictions.** When two items disagree, show both. Don't pick one.
+4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps.
+5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state.
+6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess.
+
+## Output Format
+
+Write for the user, in this exact structure:
+
+---
+
+### The Question
+
+Restate the user's question in one or two sentences.
+
+### The Code in Question
+
+File paths, line ranges, key symbols. Two or three lines to orient a cold reader.
+
+### What We Found
+
+Claims with textual evidence, each quoted or paraphrased and cited precisely:
+
+- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
+- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
+
+`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion.
+
+### What We Can Reasonably Infer
+
+Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"):
+
+- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
+
+Skip this section if there's nothing to infer.
+
+### Competing Hypotheses
+
+If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis:
+
+- **Hypothesis:** {one-sentence statement}
+- **Evidence for:** {specific items}
+- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
+
+Skip this section if there's a single clear answer.
+
+### What We Don't Know
+
+Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include:
+
+- Questions that went unanswered
+- Searches that returned nothing
+- Sources that were unavailable, and why (such as a missing real-time team chat MCP)
+- People who would likely know but whom you can't ask
+
+### Sources Consulted
+
+What was actually searched, so the user can judge coverage and redirect:
+
+- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
+- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
+- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
+- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
+- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
+- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
+- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
+
+### Confidence Summary
+
+One or two sentences on overall confidence, e.g.:
+
+> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
+
+---
+
+## Quality Check Before Returning
+
+Revise if any item fails:
+
+1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses."
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
+3. Did you surface every contradiction you noticed, or quietly pick one?
+4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
+5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it?
+6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation.
+7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent.
+
+The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive.

package/extensions/rtk/session.ts

@@ -23,8 +23,11 @@ function setRtkProcessEnabled(enabled: boolean): void {
   else process.env.RTK_DISABLED = '1';
 }
 
-// rtk's contract: name the rewritten surface, never the binary — a hand-typed `rtk` fights the rewrite.
-const RTK_PROMPT = `RTK guidance active. What you run is condensed automatically: searches (grep, rg), listings (ls, find, cat as read), package and test runs (bun, npm run, pnpm run), version control (git), and type and lint checks (tsc, eslint). Every signal kept, costly noise dropped. Treat a condensed result as complete. Re-run something unfiltered only when its result is empty, garbled, or contradicts its exit code. A command with no condensed form passes through unchanged.`;
+// rtk's contract: name the rewritten surface first and the binary second — a hand-typed `rtk` in front of a
+// rewritten command fights the rewrite, and the direct calls cover only what the rewrite cannot express.
+const RTK_PROMPT = `RTK guidance active. What you run is condensed automatically, in the host's own rewritten form: searches (grep, rg, ast-grep), listings (ls, find, tree), reads (cat), package and test runs (bun, npm, pnpm, npx, cargo, go, pytest, vitest, jest, ctest, tsc), version control and forges (git, gh, glab), containers and clusters (docker, kubectl), cloud and platform CLIs (aws, oc, dotnet), PHP tooling (phpunit, pest, phpstan, pint, ecs), lint and format (eslint, ruff, mypy, prettier, sqlfluff, playwright, prisma, next), and data tools (jq, curl, wget, psql, wc, make, tail, docker logs). The runner's own subcommand, such as \`rtk bun run test\`, keeps the failing test name, the assertion, and the file and line. Every signal kept, costly noise dropped. Treat a condensed result as complete. Re-run something unfiltered only when its result is empty, garbled, or contradicts its exit code.
+
+Call rtk directly for what the rewrite cannot express: \`rtk read <file> --level aggressive\` for an overview, \`--max-lines N\` for a preview, \`rtk smart <file>\` for a two-line summary, \`rtk summary <cmd>\` for a heuristic one, \`rtk err <cmd>\` for errors only, \`rtk log <file>\` to dedupe logs, \`rtk json <file>\` with \`--keys-only\` for shape, plus \`rtk deps\`, \`rtk diff\`, \`rtk env\`, \`rtk ast-grep\`, and \`rtk test <cmd>\` for a runner without its own form. A command with no condensed form passes through unchanged, so wrap it: \`rtk err node build.js\`, and \`rtk find -name '*.ts'\` in place of fd. Never type \`rtk\` in front of a command listed above.`;
 
 export default function rtkSessionExtension(pi: ExtensionApi): void {
   let enabled = DEFAULT_ENABLED;
@@ -73,27 +76,32 @@ export default function rtkSessionExtension(pi: ExtensionApi): void {
   pi.registerTool?.({
     name: 'rtk_run',
     label: 'RTK Run',
-    description: 'Run the installed `rtk` binary for compact command output when RTK mode is enabled.',
+    description: 'Run a shell command through the installed `rtk` binary when RTK mode is on, and run it plainly when RTK mode is off.',
     parameters: stringArrayToolParams(pi, 'args', {
       minItems: 1,
       description: "Arguments passed to rtk, e.g. ['git','status'] or ['read','src/index.ts']",
     }),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       // A subagent's own flag sits at its start-up default, so honour shared state too.
-      if (!(enabled || getSharedComboState().rtk === 'on')) return fail('RTK mode is off. Run /rtk on for this session, or use bash explicitly.');
+      const rtkOn = enabled || getSharedComboState().rtk === 'on';
       if (typeof pi.exec !== 'function') return fail('This host cannot run rtk.');
-      onUpdate?.({ content: [{ type: 'text', text: `rtk ${params.args.join(' ')}` }], details: { phase: 'start' } });
+      // RTK off: run the command as given rather than answering "mode is off". The tool is the only one left under --no-tools, and a refusal there made the model spend turns re-calling it. rtk is the condenser, never the command.
+      const cwd = ctx?.cwd || pi.cwd;
+      const bin = rtkOn ? resolveRtkBinary() : null;
+      if (rtkOn && bin === null) return fail('RTK mode is on but the rtk binary is not installed. Run: tersio update');
+      const argv = params.args;
+      onUpdate?.({ content: [{ type: 'text', text: `${bin === null ? '' : 'rtk '}${argv.join(' ')}` }], details: { phase: 'start' } });
       try {
         // A GUI-launched host may lack ~/.bun/bin on PATH, so prefer the resolved path.
-        const result = await pi.exec(resolveRtkBinary() ?? 'rtk', params.args, { signal, cwd: ctx?.cwd || pi.cwd });
+        const result = await pi.exec(bin ?? argv[0], argv, { signal, cwd });
         const text = [result.stdout, result.stderr].filter(Boolean).join('\n');
         return {
           isError: result.code !== 0,
-          content: [{ type: 'text', text: text || `rtk exited ${result.code}` }],
-          details: { code: result.code, killed: result.killed, enabled },
+          content: [{ type: 'text', text: text || `exited ${result.code}` }],
+          details: { code: result.code, killed: result.killed, enabled, condensed: bin !== null },
         };
       } catch (e) {
-        return fail(`rtk could not run: ${e instanceof Error ? e.message : String(e)}`);
+        return fail(`${bin === null ? argv[0] : 'rtk'} could not run: ${e instanceof Error ? e.message : String(e)}`);
       }
     },
   });

package/extensions/shared/rtk-eligible.ts

@@ -0,0 +1,83 @@
+// Eligible command heads, taken from rtk's own contract rather than a hardcoded guess.
+// `rtk rewrite <probe>` prints a rewrite and exits 0 or 3 when rtk handles the command,
+// and exits 1 when no equivalent exists. Each probe below is a representative workload
+// command, because subcommand-scoped tools such as `gh` rewrite `gh pr list` but not `gh`.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeRtkVersion, tersioDataPath } from './utils.ts';
+
+/** Verified against rtk 1.0.1; the drift test fails when rtk's set moves. */
+export const FALLBACK_ELIGIBLE_HEADS: readonly string[] = [
+  'rtk', 'git', 'gh', 'glab', 'docker', 'kubectl', 'psql', 'aws', 'bunx', 'npx',
+  'pytest', 'mypy', 'cat', 'grep', 'rg', 'find', 'tree', 'diff', 'ls', 'ast-grep',
+  'wget', 'prettier', 'playwright', 'prisma', 'jest', 'vitest', 'ctest', 'lint',
+  'wc', 'tsc', 'curl', 'cargo', 'npm', 'pnpm', 'bun', 'go', 'ruff', 'next',
+  'dotnet', 'oc', 'jq', 'make',
+];
+
+const PROBES: Record<string, string> = {
+  git: 'git log', gh: 'gh pr list', glab: 'glab mr list', docker: 'docker ps',
+  kubectl: 'kubectl get pods', psql: 'psql --version', aws: 'aws --version',
+  bunx: 'bunx --version', npx: 'npx --version', pytest: 'pytest --version',
+  mypy: 'mypy --version', cat: 'cat README.md', grep: 'grep rtk README.md',
+  rg: 'rg rtk README.md', find: 'find . -name x', tree: 'tree .', diff: 'diff a b',
+  ls: 'ls -la', 'ast-grep': 'ast-grep --version', wget: 'wget --version',
+  prettier: 'prettier --version', playwright: 'playwright --version', prisma: 'prisma --version',
+  jest: 'jest --version', vitest: 'vitest --version', ctest: 'ctest --version',
+  lint: 'lint .', wc: 'wc -l x', tsc: 'tsc --version', curl: 'curl --version',
+  cargo: 'cargo test', npm: 'npm run build', pnpm: 'pnpm run build', bun: 'bun run test',
+  go: 'go test ./...', ruff: 'ruff check .', next: 'next build', dotnet: 'dotnet build',
+  oc: 'oc get pods', jq: 'jq . x', make: 'make',
+};
+
+function probe(bin: string, command: string): boolean {
+  try {
+    const out = execFileSync(bin, ['rewrite', command], { encoding: 'utf8', timeout: 5000, windowsHide: true });
+    return out.trim().length > 0;
+  } catch (e) {
+    // Non-zero exit throws; exit 3 still prints a rewrite, exits 1 and 2 do not.
+    const err = e as { status?: number; stdout?: string | Buffer };
+    if (err.status !== 0 && err.status !== 3) return false;
+    return String(err.stdout ?? '').trim().length > 0;
+  }
+}
+
+/** One set of heads for this rtk build, read straight from its rewrite contract. */
+export function deriveEligibleHeads(bin: string): Set<string> {
+  const heads = new Set<string>(['rtk']);
+  for (const [head, command] of Object.entries(PROBES)) {
+    if (probe(bin, command)) heads.add(head);
+  }
+  return heads;
+}
+
+function rtkVersion(bin: string): string {
+  try {
+    return normalizeRtkVersion(execFileSync(bin, ['--version'], { encoding: 'utf8', timeout: 5000, windowsHide: true }));
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Heads rtk rewrites, cached per binary version so an upgrade re-derives once.
+ * Without a binary, or on any read failure, the verified fallback stands.
+ */
+export function eligibleHeads(bin: string | null): ReadonlySet<string> {
+  if (!bin) return new Set(FALLBACK_ELIGIBLE_HEADS);
+  const version = rtkVersion(bin);
+  const file = tersioDataPath('rtk-eligible.json', 'rtk-eligible.json');
+  try {
+    const cached = JSON.parse(fs.readFileSync(file, 'utf8')) as { version?: unknown; heads?: unknown };
+    if (cached.version === version && Array.isArray(cached.heads) && cached.heads.every((h) => typeof h === 'string')) {
+      return new Set(cached.heads as string[]);
+    }
+  } catch { /* derive below */ }
+  const heads = deriveEligibleHeads(bin);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ version, heads: [...heads] })}\n`, 'utf8');
+  } catch { /* the cache is best-effort */ }
+  return heads;
+}

package/extensions/shared/rtk-gain.ts

@@ -1,4 +1,4 @@
-// Savings read from rtk history, never estimated; modes bench in docs/BENCHMARK.md.
+// Savings read from rtk history, never estimated; modes bench in docs/BENCHMARK_GUIDE.md.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';

package/extensions/shared/sqlite.ts

@@ -1,14 +1,9 @@
-// One place that runs SQL against a database file.
-//
-// Bun and Node 22.5+ carry SQLite in process, so the `sqlite3` binary is a fallback rather than a
-// requirement: hosts without it kept silently reading nothing. Reads come back exactly as the sqlite3
-// CLI printed them -- rows on their own lines, cells joined by tabs, NULL an empty cell, one trailing
-// newline -- because every caller already parses that shape. The engine rungs take one statement per
-// read, so a caller with several queries calls once per query.
-//
-// The write path leaves the journal mode alone. The store's own schema sets WAL so a reader (the
-// dashboard) never blocks a writer, and changing the mode needs exclusive access: with a reader holding
-// the file the pragma fails, which is a failure reported after the caller's rows have already committed.
+// One place that runs SQL against a database file. Bun and Node 22.5+ carry SQLite in process, so the
+// `sqlite3` binary is a fallback: hosts without it kept silently reading nothing. Reads return the sqlite3
+// CLI shape (one row per line, cells tab-joined, NULL an empty cell) because every caller parses that.
+// The write path leaves the journal mode alone: the schema sets WAL so a reader never blocks a writer,
+// and the pragma needs exclusive access, so with a reader holding the file it fails after the caller's
+// rows have already committed (see docs/ERRORS.md).
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
@@ -65,8 +60,7 @@ function engine(): Engine | null {
   } catch { /* not Bun, or no SQLite in this build */ }
   try {
     const { DatabaseSync } = requireOptional('node:sqlite') as { DatabaseSync: new (db: string, opts?: { readOnly?: boolean }) => NodeDatabase };
-    // Rows arrive keyed by column name unless the statement returns arrays. A duplicate name collapses
-    // its key and shifts every later cell, so a Node that cannot return arrays is no engine at all.
+    // Rows arrive keyed by column name unless the statement returns arrays: a duplicate name collapses its key and shifts every later cell, so a Node that cannot return arrays is no engine.
     const probe = new DatabaseSync(':memory:');
     try {
       if (typeof probe.prepare('SELECT 1').setReturnArrays !== 'function') throw new Error('no positional rows');

package/extensions/shared/status.ts

@@ -38,8 +38,7 @@ let remembered: ExtensionCtx | undefined;
 let lastText: string | undefined;
 let lastUi: UiApi | undefined;
 
-// Paint the host footer bar; same text on the same UI is skipped, a new ctx repaints it.
-// One key only: the combo line already names the caveman mode, and a second key renders as a second footer line.
+// Paint the host footer bar; same text on the same UI is skipped. One key only: the combo line already names the caveman mode, and a second key renders as a second footer line.
 export function announceStatus(ctx: ExtensionCtx | undefined): void {
   const state = getSharedComboState();
   const text = formatStatus(state);

package/extensions/shared/usage-ledger.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { homeDir, isPiProcess, piAgentDir, resolveRtkBinary, tersioDataPath } from './utils.ts';
+import { eligibleHeads } from './rtk-eligible.ts';
 import { sqliteRead } from './sqlite.ts';
 
 export type UsageKind = 'command' | 'toggle' | 'install' | 'update' | 'rtk-audit';
@@ -273,6 +274,55 @@ export function dayKey(ts: string | number): string | null {
   const p = (n: number): string => String(n).padStart(2, '0');
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
 }
+
+// OpenCode tool parts carry the command in the message blob; sqliteRead is line-based, so newlines are flattened in SQL.
+const OC_BASH_CMD = "replace(replace(json_extract(j.value,'$.state.input.command'), char(10), ' '), char(13), ' ')";
+const OC_BASH_TOOL = "json_extract(j.value,'$.type')='tool' AND (json_extract(j.value,'$.name')='bash' OR json_extract(j.value,'$.name')='shell')";
+const ocBashLegacy = `SELECT message.id, json_extract(message.data,'$.sessionID'), ${OC_BASH_CMD} FROM message, json_each(message.data,'$.content') j WHERE json_extract(message.data,'$.role')='assistant' AND ${OC_BASH_TOOL}`;
+const ocBashCurrent = `SELECT session_message.id, session_message.session_id, ${OC_BASH_CMD} FROM session_message, json_each(session_message.data,'$.content') j WHERE session_message.type='assistant' AND ${OC_BASH_TOOL}`;
+
+export interface OpencodeBashRow {
+  id: string;
+  sessionId: string;
+  command: string;
+}
+
+/** Every executed bash command in an OpenCode db, v2 first and the legacy table second. */
+export function readOpencodeBashRows(db: string): OpencodeBashRow[] {
+  const rows: OpencodeBashRow[] = [];
+  try {
+    if (!fs.existsSync(db)) return rows;
+    let out = '';
+    try { out += sqliteRead(db, ocBashCurrent); } catch { /* no v2 table */ }
+    try { out += sqliteRead(db, ocBashLegacy); } catch { /* no legacy table */ }
+    for (const line of out.split('\n')) {
+      if (!line.trim()) continue;
+      const [id, sessionId, command] = line.split('\t');
+      if (typeof command !== 'string' || !command.trim()) continue;
+      rows.push({ id: id ?? '', sessionId: sessionId ?? '', command });
+    }
+  } catch { /* an unreadable db is a skip, not a failure */ }
+  return rows;
+}
+
+// Pre-v2 OpenCode stores one message per JSON file; the same tool-part shape holds the command.
+function opencodeFileBash(file: string): { commands: string[]; sessionId: string } {
+  try {
+    const message = JSON.parse(fs.readFileSync(file, 'utf8')) as { sessionID?: unknown; content?: unknown };
+    const parts = Array.isArray(message.content) ? message.content : [];
+    const commands: string[] = [];
+    for (const part of parts) {
+      const p = part as { type?: unknown; name?: unknown; state?: { input?: { command?: unknown } } };
+      if (p?.type !== 'tool') continue;
+      if (p.name !== 'bash' && p.name !== 'shell') continue;
+      const command = p.state?.input?.command;
+      if (typeof command === 'string' && command) commands.push(command);
+    }
+    return { commands, sessionId: typeof message.sessionID === 'string' ? message.sessionID : '' };
+  } catch {
+    return { commands: [], sessionId: '' };
+  }
+}
 export function walkJsonl(dir: string, out: string[], cap: number, ext = '.jsonl'): void {
   let entries: fs.Dirent[];
   try {
@@ -290,11 +340,6 @@ export function walkJsonl(dir: string, out: string[], cap: number, ext = '.jsonl
 // Recent rows are a newest-first window over lifetime history; aggregates keep everything.
 export const RECENT_LIMIT = 2000;
 const FREE_SUFFIX = /(?::free|-free)$/i;
-const RTK_ELIGIBLE_HEADS = new Set([
-  'rtk', 'git', 'grep', 'rg', 'find', 'cat', 'ls', 'tree', 'diff', 'log',
-  'npm', 'npx', 'pnpm', 'bun', 'bunx', 'cargo', 'go', 'python', 'pytest',
-  'ruff', 'mypy', 'docker', 'kubectl', 'psql', 'aws', 'gh', 'glab', 'wc',
-]);
 // Parse buffer shared by live reads and usage.db syncs, so the store is a cache and never a fork.
 export interface SessionAccum {
   byModel: Record<string, TokenBreakdown>;
@@ -650,17 +695,28 @@ export function agentOfSessionText(text: string): string {
   return 'main';
 }
 
-const adoptionFileCache = new Map<string, { size: number; mtimeMs: number; counts: { bashCalls: number; eligibleCalls: number; rtkCalls: number } }>();
+const adoptionFileCache = new Map<string, { size: number; mtimeMs: number; heads: string; counts: BashCounts }>();
 
-function parseAdoptionFile(file: string): { counts: { bashCalls: number; eligibleCalls: number; rtkCalls: number }; sessions: number } {
-  const counts = { bashCalls: 0, eligibleCalls: 0, rtkCalls: 0 };
+interface BashCounts { bashCalls: number; eligibleCalls: number; rtkCalls: number }
+
+function countBashCommands(commands: readonly string[], eligible: ReadonlySet<string>, counts: BashCounts): void {
+  for (const command of commands) {
+    counts.bashCalls += 1;
+    const head = leadBinary(command);
+    if (eligible.has(head)) counts.eligibleCalls += 1;
+    if (head === 'rtk') counts.rtkCalls += 1;
+  }
+}
+
+function parseAdoptionFile(file: string, eligible: ReadonlySet<string>): { counts: BashCounts; sessions: number } {
+  const counts: BashCounts = { bashCalls: 0, eligibleCalls: 0, rtkCalls: 0 };
   let text: string;
   try {
     text = fs.readFileSync(file, 'utf8');
   } catch {
     return { counts, sessions: 0 };
   }
-  let sawBash = false;
+  const commands: string[] = [];
   for (const line of text.split('\n')) {
     if (!line.includes('tool_execution_start')) continue;
     try {
@@ -671,15 +727,11 @@ function parseAdoptionFile(file: string): { counts: { bashCalls: number; eligibl
       };
       if (row.type !== 'custom' || row.customType !== 'tool_execution_start' || row.data?.toolName !== 'bash') continue;
       const command = row.data.args?.command;
-      if (typeof command !== 'string') continue;
-      sawBash = true;
-      counts.bashCalls += 1;
-      const head = leadBinary(command);
-      if (RTK_ELIGIBLE_HEADS.has(head)) counts.eligibleCalls += 1;
-      if (head === 'rtk') counts.rtkCalls += 1;
+      if (typeof command === 'string') commands.push(command);
     } catch { /* skip corrupt line */ }
   }
-  return { counts, sessions: sawBash ? 1 : 0 };
+  countBashCommands(commands, eligible, counts);
+  return { counts, sessions: commands.length > 0 ? 1 : 0 };
 }
 
 export function clearRtkAdoptionCache(): void {
@@ -687,6 +739,10 @@ export function clearRtkAdoptionCache(): void {
 }
 
 export function readRtkAdoption(): RtkAdoption {
+  // The eligible set comes from rtk's rewrite contract, cached per binary version.
+  const eligible = eligibleHeads(resolveRtkBinary());
+  // A cached count is only valid for the head set that produced it.
+  const headsKey = [...eligible].sort().join(',');
   const files: string[] = [];
   for (const dir of sessionsDirs()) walkJsonl(dir, files, 2000);
   const live = new Set(files);
@@ -705,9 +761,9 @@ export function readRtkAdoption(): RtkAdoption {
       continue;
     }
     let entry = adoptionFileCache.get(file);
-    if (!entry || entry.size !== stat.size || entry.mtimeMs !== stat.mtimeMs) {
-      const parsed = parseAdoptionFile(file);
-      entry = { size: stat.size, mtimeMs: stat.mtimeMs, counts: parsed.counts };
+    if (!entry || entry.size !== stat.size || entry.mtimeMs !== stat.mtimeMs || entry.heads !== headsKey) {
+      const parsed = parseAdoptionFile(file, eligible);
+      entry = { size: stat.size, mtimeMs: stat.mtimeMs, heads: headsKey, counts: parsed.counts };
       adoptionFileCache.set(file, entry);
       sessions += parsed.sessions;
     } else if (entry.counts.bashCalls > 0) {
@@ -717,6 +773,28 @@ export function readRtkAdoption(): RtkAdoption {
     eligibleCalls += entry.counts.eligibleCalls;
     rtkCalls += entry.counts.rtkCalls;
   }
+  // OpenCode keeps its own store: a v2 sqlite db, or one JSON file per message before v2.
+  const opencode: BashCounts = { bashCalls: 0, eligibleCalls: 0, rtkCalls: 0 };
+  const opencodeSessions = new Set<string>();
+  if (process.env.TERSIO_SESSIONS_DIR === undefined || process.env.TERSIO_OPENCODE_DB !== undefined) {
+    for (const row of readOpencodeBashRows(opencodeDbPath())) {
+      countBashCommands([row.command], eligible, opencode);
+      if (row.sessionId) opencodeSessions.add(row.sessionId);
+    }
+  }
+  const ocFiles: string[] = [];
+  if (process.env.TERSIO_SESSIONS_DIR === undefined || process.env.TERSIO_OPENCODE_DIR !== undefined) {
+    walkJsonl(opencodeSessionsDir(), ocFiles, 5000, '.json');
+    for (const file of ocFiles) {
+      const parsed = opencodeFileBash(file);
+      countBashCommands(parsed.commands, eligible, opencode);
+      if (parsed.sessionId) opencodeSessions.add(parsed.sessionId);
+    }
+  }
+  bashCalls += opencode.bashCalls;
+  eligibleCalls += opencode.eligibleCalls;
+  rtkCalls += opencode.rtkCalls;
+  sessions += opencodeSessions.size;
   const missedCalls = Math.max(0, eligibleCalls - rtkCalls);
   return { sessions, bashCalls, eligibleCalls, rtkCalls, missedCalls, adoptionPct: eligibleCalls ? (rtkCalls / eligibleCalls) * 100 : 0 };
 }

package/extensions/timing/index.ts

@@ -1,5 +1,4 @@
-// pi records a response's total duration but no first-token latency, so TTFT reads null there.
-// omp writes its own `ttft` and OpenCode records `time.streamed`, so this fills the gap only for pi.
+// pi records total duration but no first-token latency, so TTFT reads null there; omp writes its own `ttft` and OpenCode records `time.streamed`, so this fills the gap only for pi.
 import type { ExtensionApi } from '../shared/types.ts';
 
 interface AssistantMessage {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@krtclcdy/tersio",
-  "version": "2.25.6",
-  "description": "✂️ Token saver and usage tracker for coding agents: terse Caveman replies, compact RTK shell output, lean Ponytail code calls, and a gain dashboard — one-command combo presets over one shared extension tree.",
+  "version": "2.25.7",
+  "description": "✂️ Token saver and usage tracker for coding agents: terse Caveman replies, compact RTK shell output, lean Ponytail code, pstack rigor, and a gain dashboard — one-command combos over one shared extension tree.",
   "keywords": [
     "token-saving",
     "ai-tools",
@@ -128,13 +128,16 @@
     "dashboard/dist/**/*",
     "extensions/**/*.ts",
     "extensions/caveman/rule.md",
+    "extensions/caveman/rule-lite.md",
+    "extensions/caveman/rule-megacave-lite.md",
+    "extensions/caveman/rule-megacave-ultra.md",
     "extensions/caveman/rule-ultra.md",
     "extensions/caveman/rule-megacave.md",
-    "extensions/pstack/rule.md"
+    "extensions/pstack/**/*.md"
   ],
   "scripts": {
     "clean": "rm -rf dist dashboard/dist",
-    "build": "tsc && bun run build:dashboard && cp extensions/caveman/*.md dist/extensions/caveman/ && cp extensions/pstack/*.md dist/extensions/pstack/",
+    "build": "tsc && bun run build:dashboard && cp extensions/caveman/*.md dist/extensions/caveman/ && cp extensions/pstack/*.md dist/extensions/pstack/ && cp -R extensions/pstack/principles extensions/pstack/playbooks extensions/pstack/skills extensions/pstack/references dist/extensions/pstack/",
     "build:dashboard": "bun install --cwd dashboard/app --frozen-lockfile && bun run --cwd dashboard/app build",
     "prepublishOnly": "bun run build",
     "check": "tsc --noEmit",