@jeffober/thatch 0.1.48 → 0.2.1

package/src/os-args.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Parses the session id a harness was started to continue from an argument
+ * list (`opencode -s <id>` / `--session <id>` / `--session=<id>`). Pure:
+ * the caller supplies the list (see startupSessionId for where it comes
+ * from). The framework passes no session id to plugins and resuming a
+ * session fires no events, so the command line is the only signal that a
+ * fresh harness is the new home of a continued session.
+ */
+export function startupSessionIdFromArgv(argv: string[]): string | null {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-s" || arg === "--session") return argv[i + 1] ?? null;
+    if (arg.startsWith("--session=")) return arg.slice("--session=".length) || null;
+  }
+  return null;
+}
+
+/**
+ * Whether the harness was started with `-c`/`--continue` (continue the most
+ * recent session). Pure. Yargs-style boolean flags only: `--continue=false`
+ * reads as the negation, everything else as a plain switch. The session id
+ * itself is not on the command line - the harness resolves "most recent
+ * top-level session" at startup, which the plugin replicates via the SDK
+ * (continuesLastSessionId).
+ */
+export function continuesLastSessionFromArgv(argv: string[]): boolean {
+  for (const arg of argv) {
+    if (arg === "-c" || arg === "--continue") return true;
+    if (arg.startsWith("--continue=")) return arg.slice("--continue=".length) !== "false";
+  }
+  return false;
+}
+
+/**
+ * Picks the session `opencode -c` continues: the most recently updated
+ * top-level session. Pure; the caller supplies the session list from
+ * client.session.list() (directory-scoped, like the plugin's own client).
+ * The server's list order is not trusted - the TUI re-sorts by
+ * time.updated before picking, and so does this.
+ */
+export function continuesLastSessionId(
+  sessions: { id: string; parentID?: string; time?: { updated?: number } }[],
+): string | null {
+  return (
+    [...sessions]
+      .sort((a, b) => (b.time?.updated ?? 0) - (a.time?.updated ?? 0))
+      .find((s) => !s.parentID)?.id ?? null
+  );
+}
+
+// The plugin does not run in the process's main thread: opencode's TUI
+// spawns a worker thread (cli/tui/worker.js) to host the server, and worker
+// threads get their own argv (just the worker script) with none of the CLI
+// flags. The thread still shares the process's pid, so the OS-level command
+// line for our own pid is the real `opencode -s ses_...` invocation. Read it
+// from /proc on Linux or via ps on macOS. Returns [] when unavailable;
+// callers treat that as "no session flag". The readers are injectable so
+// tests can drive each branch without a real /proc or ps.
+export interface OsArgsDeps {
+  /** Reads a file as UTF-8, throwing when it does not exist. */
+  readFile: (path: string) => string;
+  /** Runs `ps -p <pid> -o args=`; returns its exit code and stdout. */
+  ps: (pid: number) => { exitCode: number; stdout: string };
+}
+
+const defaultOsArgsDeps: OsArgsDeps = {
+  readFile: (path) => readFileSync(path, "utf8"),
+  ps: (pid) => {
+    const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "args="]);
+    return { exitCode: res.exitCode, stdout: res.stdout.toString() };
+  },
+};
+
+export function osProcessArgs(deps: OsArgsDeps = defaultOsArgsDeps, pid = process.pid): string[] {
+  try {
+    // Linux: cmdline is NUL-separated argv, exact and cheap.
+    return deps.readFile("/proc/self/cmdline").split("\0").filter(Boolean);
+  } catch {
+    // macOS has no /proc; ask ps for this pid's full command. Splitting on
+    // whitespace is safe for our purpose: session ids never contain spaces.
+    try {
+      const res = deps.ps(pid);
+      if (res.exitCode !== 0) return [];
+      return res.stdout.trim().split(/\s+/).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Resolve the session id this harness was launched to resume, if any:
+// prefer the thread-local argv (covers tests and any non-worker host), then
+// fall back to the process's OS-level command line (the real harness path).
+// The caller passes the OS command line in so it is read once per init.
+export function startupSessionId(osArgs: string[]): string | null {
+  return startupSessionIdFromArgv(process.argv) ?? startupSessionIdFromArgv(osArgs);
+}

package/src/prompts.ts

@@ -10,6 +10,29 @@ export function predictionVerb(evidenceCount: number): string {
   return evidenceCount === 0 ? "you may prefer" : "you tend to";
 }
 
+/**
+ * Shared nudge-line formatter for the prediction and behavior surfaces.
+ * The model supplies the matcher and statement text, and both frequently
+ * arrive already carrying the render prefixes: matchers phrased as
+ * "When ..." (a natural situation phrasing, or copied from an earlier
+ * nudge) and statements copied with the evidence verb ("you tend to ...").
+ * The unconditional prefixes doubled that text in every rendered nudge,
+ * so each prefix is skipped when the supplied text already carries it.
+ */
+export function formatWhenLine(
+  confidence: number,
+  evidenceCount: number,
+  matcher: string,
+  statement: string,
+  verb: string,
+): string {
+  const matcherText = /^when\b/i.test(matcher) ? matcher : `When ${matcher}`;
+  const statementText = new RegExp(`^${verb}\b`, "i").test(statement) || /^you (?:tend to|may prefer)\b/i.test(statement)
+    ? statement
+    : `${verb} ${statement}`;
+  return `[${confidence.toFixed(2)} conf, ${evidenceCount} tests] ${matcherText}: ${statementText}`;
+}
+
 /**
  * Cross-session chat section of the opencode system prompt. Omitted when the
  * user disabled chat via config (chat.enabled: false), so a disabled feature
@@ -50,6 +73,72 @@ auto-reply unless the message bears on a task you are already doing; do not
 forward or chain messages reflexively. Name the sender when relaying a
 message to the user, and let the user decide when coordination is ambiguous.`;
 
+// Class-lesson guidance, shared verbatim by both prompt variants (the
+// paragraphs name no tools, so the twins need no per-host spellings). See
+// the LLM-alerts review loop (Sept 2026): class-level lessons go into the
+// memory/behavior/prediction systems with matchers worded for the broadest
+// semantic trigger surface.
+const classLessonPredictionSection = `
+The same class discipline applies to judgment errors: when a review round,
+bug, or incident reveals a class of bad calls (not just one), record the
+pattern as a prediction. Word the matcher for semantic matching - describe
+the situation a future decision will be in - then re-read it against
+everything that ought to trigger it and widen the wording until it does.`;
+
+const classLessonBehaviorSection = `
+When a review round, bug fix, or incident reveals a CLASS of mistake you are
+prone to (rather than a one-off), persist the class so it resurfaces where
+the work happens: save a memory stating the class and how to detect it, and
+codify a behavior whose situation text describes the context a future
+session will be in when that class of trouble starts. Word the situation for
+semantic matching: after writing it, re-read it against everything that
+ought to trigger it and widen the wording to the broadest surface of the
+class - a matcher that only names this incident never fires for the next
+one.`;
+
+/**
+ * The artifact-pointer bullet of the "How to Write" section. Names no
+ * tools, so it is shared verbatim by both prompt variants (the
+ * class-lesson convention above).
+ */
+const artifactPointerBullet = `- Artifact memories should carry their pointers: file paths, ticket IDs,
+  package names. Verification is cheap later only if the memory says where
+  to check. A pointer is provenance for durable knowledge, not knowledge
+  itself - a bare "where X lives" is exactly what the durability test
+  excludes.`;
+
+/**
+ * "Memories are pointers, not truth" instruction body, shared by all three
+ * prompt variants. Takes a ToolNamer because the section names memory tools
+ * (thatch_memory_remember on opencode, bare on MCP hosts, whose
+ * instructions establish the bare-name convention). Staleness is a
+ * property of the claim's relationship to a mutable world, not of the
+ * memory's age.
+ */
+export function memoryPointersSection(tool: ToolNamer): string {
+  return `## Memories Are Pointers, Not Truth
+
+${tool("memory_recall")} surfaces a point-in-time record: a semantic guide
+associating "what I'm looking for" with "where I should look", written when
+the knowledge was current. Memories speed up research - they do not replace
+it, and they are not a source of truth.
+
+- **Policy memories** ("the user always wants X", "check CI after merging")
+  are self-executing: they are the ground truth for behavior.
+- **Artifact memories** ("feature X lives in <file> and uses <technique>")
+  are pointers to checkable claims about code, docs, tickets, or git.
+  Follow the pointer and assert from the source, not from the memory.
+
+Before asserting an artifact claim from memory, re-derive it from the
+current source. Confirming the reference still exists verifies little: the
+file can survive while the behavior changed (scope drift, priority shifts,
+implementation details that proved too complex in practice).
+The source wins. When reality has moved on, correct the record with
+${tool("memory_remember")} (overwrite: true) or ${tool("memory_forget")} -
+silently; memory maintenance is not user-facing. For a deep staleness check
+of a specific memory, load the thatch-memory-verify skill.`;
+}
+
 export function systemPrompt(repo: string, chatEnabled = true): string {
   return `# Persistence
 
@@ -83,13 +172,16 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 
 ## Session Startup
 
-1. thatch_memory_recall "user preferences and personality"
-2. thatch_memory_recall "project architecture and conventions"
-3. If on a non-main branch, thatch_memory_recall with the branch name
+1. thatch_memory_recall({ query: "user preferences and personality" })
+2. thatch_memory_recall({ query: "project architecture and conventions" })
+3. If on a non-main branch, thatch_memory_recall with the branch name as the query
 4. thatch_memory_list and thatch_store_list to see what's available
 
 Before diving into code, thatch_memory_recall with a query relevant to the area
-you're working in. Prior sessions may have already investigated it.
+you're working in. Prior sessions may have already investigated it. All thatch
+tools take a single object argument: never a bare positional string. Call them
+directly, or through the Code Mode execute runtime when the harness only
+exposes tools through code.
 
 ## Skills
 
@@ -111,7 +203,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
-- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
+- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory looks stale or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
 - \`thatch-clear-writing\` - prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Load before drafting any of those.
 
@@ -139,15 +231,7 @@ whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
 
-## Memory Verification
-
-When thatch_memory_show or thatch_memory_recall returns a memory with an old
-updated_at date (more than a few weeks), consider loading the
-thatch-memory-verify skill to fact-check its code-related claims against the
-current codebase before relying on them. This is not mandatory for every old
-memory. Use judgment: a memory about a stable architectural decision may be
-fine for months, while a memory about file locations or function names is
-more likely to drift.
+${memoryPointersSection(opencodeToolName)}
 
 ## Background Task Completions
 
@@ -164,6 +248,12 @@ the same prompt. If the re-dispatch also fails or times out, note the gap and
 move on. Do not retry more than once - repeated failures indicate an
 intractable prompt, not a transient hang.
 
+When the fact-extractor sub-agent completes, its "Extraction complete."
+report is a background-task completion, not an extraction nudge: the buffer
+is drained and nothing follows from it. Never re-dispatch an extractor
+because a completion arrived - a new extraction nudge is the only dispatch
+signal.
+
 ## Watchers
 
 Use thatch_watch_create to watch a GitHub PR for events (comments, review
@@ -225,6 +315,8 @@ reviewing your changes, or asked you to review their changes or another LLM's
 changes. Before creating a new prediction, query for an existing one and
 reinforce or adjust it when possible.
 
+${classLessonPredictionSection}
+
 ## Situational Behaviors
 
 A model of your own operational rules is maintained by the behavior engine.
@@ -245,6 +337,8 @@ way that is about your own operational discipline (not a user preference):
 2. Use thatch_behavior_feedback when surfaced behaviors fire to ham/spam them
 3. Use thatch_behavior_delete to remove a rule created in error
 
+${classLessonBehaviorSection}
+
 Do not codify rules that make you lazier or less thorough. Rules should encode
 discipline, not shortcuts.
 
@@ -277,6 +371,7 @@ config in memory.
 - One topic per memory. Write for a future instance with zero current context.
 - Confidence 1-2: single signal. 5-6: moderate. 9: explicitly stated.
   10: hard constraint.
+${artifactPointerBullet}
 
 ## What NOT to Store
 
@@ -395,13 +490,14 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 
 ## Session Startup
 
-1. \`memory_recall\` "user preferences and personality" (global store)
-2. \`memory_recall\` "project architecture and conventions" (project store)
-3. If on a non-main branch, \`memory_recall\` with the branch name
+1. \`memory_recall\` with \`{"query": "user preferences and personality"}\` (global store)
+2. \`memory_recall\` with \`{"query": "project architecture and conventions"}\` (project store)
+3. If on a non-main branch, \`memory_recall\` with the branch name as the query
 4. \`memory_list\` and \`store_list\` to see what's available
 
 Before diving into code, \`memory_recall\` with a query relevant to the area
-you're working in. Prior sessions may have already investigated it.
+you're working in. Prior sessions may have already investigated it. All thatch
+tools take a single JSON object argument: never a bare positional string.
 
 ## Skills
 
@@ -423,7 +519,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
-- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
+- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory looks stale or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
 - \`thatch-clear-writing\` - prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Load before drafting any of those.
 
@@ -451,14 +547,7 @@ whether you've discovered knowledge worth persisting. Use memory_recall to
 check for duplicates, then memory_remember for new findings. Then deliver
 your response.
 
-## Memory Verification
-
-When memory_show or memory_recall returns a memory with an old updated_at
-date (more than a few weeks), consider loading the thatch-memory-verify skill
-to fact-check its code-related claims against the current codebase before
-relying on them. This is not mandatory for every old memory. Use judgment: a
-memory about a stable architectural decision may be fine for months, while a
-memory about file locations or function names is more likely to drift.
+${memoryPointersSection(bareToolName)}
 
 ## User Decision Model
 
@@ -489,6 +578,8 @@ reviewing your changes, or asked you to review their changes or another LLM's
 changes. Before creating a new prediction, query for an existing one and
 reinforce or adjust it when possible.
 
+${classLessonPredictionSection}
+
 ## Situational Behaviors
 
 A model of your own operational rules is maintained by the behavior engine.
@@ -509,6 +600,8 @@ way that is about your own operational discipline (not a user preference):
 2. Use behavior_feedback when surfaced behaviors fire to ham/spam them
 3. Use behavior_delete to remove a rule created in error
 
+${classLessonBehaviorSection}
+
 Do not codify rules that make you lazier or less thorough. Rules should encode
 discipline, not shortcuts.
 
@@ -540,6 +633,7 @@ hand-editable; do not store thatch config in memory.
 - One topic per memory. Write for a future instance with zero current context.
 - Confidence 1-2: single signal. 5-6: moderate. 9: explicitly stated.
   10: hard constraint.
+${artifactPointerBullet}
 
 ## What NOT to Store
 
@@ -622,6 +716,17 @@ export function versionWarningNudge(message: string): string {
   return `[thatch] ${message} This is a system nudge, not user input. After informing the user, continue with their request.`;
 }
 
+/**
+ * The version-skew message: the on-disk package version is newer than the
+ * running one (the user upgraded but the host kept the old plugin loaded).
+ * Standalone so the wording is testable. Host-specific remedies (v2's
+ * "opencode plugin update", a shim-shape reminder) are planned but not yet
+ * appended by any caller - see docs/dev/features/opencode-plugin.md.
+ */
+export function skewWarningText(onDisk: string, running: string): string {
+  return `thatch was upgraded to v${onDisk} but this session is running v${running}. Restart opencode to apply the update.`;
+}
+
 // ---------------------------------------------------------------------------
 // Prompt cores - behavior instruction bodies shared by nudges and /thatch
 // command files (src/commands.ts). A core is the host-agnostic instruction
@@ -641,6 +746,13 @@ export type ToolNamer = (name: string) => string;
 export const opencodeToolName: ToolNamer = (name) => `thatch_${name}`;
 export const mcpToolName: ToolNamer = (name) => `mcp__thatch__${name}`;
 
+/**
+ * The bare name itself. Used by prompt sections embedded in instructions
+ * that establish the bare-name convention (mcpInstructions and twins): the
+ * model maps bare names to the host spelling at call time.
+ */
+export const bareToolName: ToolNamer = (name) => name;
+
 /**
  * The extraction instruction body. sessionIdArg is either ` with session_id
  * "X"` (the nudge path: the sub-agent's session differs from the parent's)
@@ -676,7 +788,7 @@ export function reflectCore(tool: ToolNamer): string {
 }
 
 /**
- * Extraction nudge with escalation. Both the opencode plugin (src/index.ts)
+ * Extraction nudge with escalation. Both the opencode plugin (src/runtime.ts)
  * and the Claude Code/Cursor CLI (bin/thatch flush-tools) call this with
  * their respective tool name prefix. The missedCount parameter tracks
  * consecutive nudges delivered without any memory_remember call in between,
@@ -824,7 +936,11 @@ function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
   const verb = n === 1 ? "relates" : "relate";
   const labels = matches.slice(0, 2).map((m) => `"${m.label}"`).join(", ");
   const etc = n > 2 ? ", etc." : "";
-  return `[thatch] ${n} ${word} ${verb} to this prompt (${labels}${etc}). Use ${toolName} before responding.`;
+  return (
+    `[thatch] ${n} ${word} ${verb} to this prompt (${labels}${etc}). ` +
+    `Use ${toolName}({ query: "..." }) before responding - the argument is ` +
+    `a single object with a "query" key, never a bare positional string.`
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -837,7 +953,7 @@ function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
 export function predictionNudge(items: PredictionNudgeItem[]): string {
   const lines = items.map((p) => {
     const verb = predictionVerb(p.evidence_count);
-    return `- [${p.confidence.toFixed(2)} conf, ${p.evidence_count} tests] When ${p.matcher_description}: ${verb} ${p.statement}`;
+    return `- ${formatWhenLine(p.confidence, p.evidence_count, p.matcher_description, p.statement, verb)}`;
   });
   return `[thatch] User decision model\n${lines.join("\n")}`;
 }
@@ -851,7 +967,7 @@ export function predictionNudge(items: PredictionNudgeItem[]): string {
 export function behaviorNudge(items: BehaviorNudgeItem[]): string {
   const lines = items.map((b) => {
     const verb = b.evidence_count === 0 ? "consider" : "do";
-    return `- [${b.confidence.toFixed(2)} conf, ${b.evidence_count} tests] When ${b.matcher_description}: ${verb} ${b.statement}`;
+    return `- ${formatWhenLine(b.confidence, b.evidence_count, b.matcher_description, b.statement, verb)}`;
   });
   return `[thatch] Situational behaviors\n${lines.join("\n")}`;
 }
@@ -884,6 +1000,40 @@ ${lines.join("\n")}
 This is a system notification, not user input. Decide whether to act now or keep waiting - the user's instructions from when the watch was created govern how to handle it.${detailHint} This notification is not approval to advance other pending work, with one exception: if this watch was created to gate work the user already greenlit (for example "wait for CI, then merge"), it is the continuation signal for exactly that work - proceed with it.${cadence} If you act, tell the user what you did and why; if not, stop and wait.`;
 }
 
+/**
+ * Watcher re-arm notice for a session resuming after a restart. The session's
+ * own dormant watcher definitions were re-armed into the live registry;
+ * delivered as a synthetic part on the session's first message so the model
+ * knows proactive notifications will resume without a re-registration step.
+ * Expired definitions (TTL passed while the session was away) are reported,
+ * not silently dropped - a watch the user expected to be waiting should be
+ * known to be gone.
+ */
+export function watcherRearmNotice(targets: string[], expiredCount: number, failedCount = 0): string {
+  const list = targets.join(", ");
+  const expired = expiredCount > 0
+    ? `\n${expiredCount} earlier watcher${expiredCount === 1 ? "" : "s"} expired while the session was away and were not re-armed.`
+    : "";
+  const failed = failedCount > 0
+    ? `\n${failedCount} watcher${failedCount === 1 ? "" : "s"} could not be re-armed (the watched target is gone or unreachable) and was dropped.`
+    : "";
+  return `[thatch] ${targets.length} watcher${targets.length === 1 ? "" : "s"} re-armed after the restart: ${list}.${expired}${failed}
+No re-registration is needed; notifications will arrive here as usual. This is a system notice, not user input - carry on with the user's request.`;
+}
+
+/**
+ * Watcher death notice: a dormant watcher's owning session died with its
+ * harness and has not been resumed. Delivered as a synthetic part to a live
+ * session in the same project, so a watch that will never fire is at least
+ * heard about instead of silently vanishing. Pointer-only: target labels,
+ * never event content.
+ */
+export function watcherDeathNotice(targets: string[]): string {
+  const list = targets.join(", ");
+  return `[thatch] ${targets.length} watcher${targets.length === 1 ? " died" : "s died"} with session${targets.length === 1 ? "" : "s"} that are no longer running: ${list}.
+${targets.length === 1 ? "It" : "They"} will re-arm automatically if ${targets.length === 1 ? "that session is" : "those sessions are"} resumed. This is a system notice, not user input - carry on with the user's request.`;
+}
+
 /**
  * Chat wake-up notification for the poller's promptAsync delivery. Injected
  * as a synthetic part that triggers a model turn. Pointer-only like watcher