@witness-ai/opencode 0.2.4 → 0.3.1

package/bin/download-model.js

@@ -2,7 +2,7 @@
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { readFileSync, unlinkSync } from "node:fs"
-import { downloadModel, modelReady, startModelDownload } from "./model.js"
+import { downloadModel, modelReady, restampLockOwner, startModelDownload } from "./model.js"
 
 const args = process.argv.slice(2)
 const defaultRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
@@ -34,6 +34,13 @@ for (const signal of ["SIGINT", "SIGTERM"]) {
   })
 }
 
+// The lock was stamped with the PARENT's pid by startModelDownload's acquireLock;
+// re-stamp it with OUR pid (this downloader child) so a hard kill of the child is
+// detected by lockOwnerDead's liveness probe instead of wedging for 12h behind a
+// still-alive parent (issue #54 I5). Token-guarded and best-effort. Also covers the
+// detached --background launcher, which routes through --foreground.
+if (args[0] === "--foreground" && lock && lockToken) restampLockOwner(lock, lockToken)
+
 const parentPID = Number(process.env.WITNESS_MODEL_PARENT_PID || "0")
 if (parentPID > 0) {
   // OpenCode may be killed without running plugin dispose. Poll the parent so the

package/bin/model.js

@@ -267,6 +267,25 @@ function acquireLock(dir) {
   }
 }
 
+// restampLockOwner rewrites the lock's recorded pid to THIS process's pid, keeping
+// the token. startModelDownload's acquireLock stamps the PARENT (plugin) pid, then
+// spawns the actual downloader as a child; if that child is SIGKILL'd while the
+// parent lives, lockOwnerDead probes the still-alive parent and never reaps — a
+// 12h wedge of the download (issue #54 I5). Having the --foreground child re-stamp
+// with its own pid on startup makes the liveness probe target the process that is
+// actually doing the work. Token-guarded so a stale-lock reap that already handed
+// the slot to a different downloader is never clobbered; best-effort (a failure
+// just leaves the parent pid, i.e. the pre-fix behavior). Exported (not just via
+// __test) because download-model.js calls it in production.
+export function restampLockOwner(lock, token) {
+  if (!lock || !token) return
+  try {
+    const body = readFileSync(lock, "utf8")
+    if (body.trim().split(/\s+/)[0] !== token) return // reaped + reassigned; not ours
+    writeFileSync(lock, `${token} ${process.pid} ${os.hostname()}\n`, { encoding: "utf8" })
+  } catch {}
+}
+
 export function startModelDownload(packageRoot, options = {}) {
   if (process.env.WITNESS_SKIP_MODEL_DOWNLOAD === "1" || modelReady(packageRoot)) return null
   const dir = modelDir(packageRoot)
@@ -433,5 +452,7 @@ export const __test = {
   verifiedMarkerPath,
   acquireLock,
   lockStale,
+  lockOwnerDead,
+  restampLockOwner,
   reapForeignParts,
 }

package/bin/witness.js

@@ -18,9 +18,15 @@ if (command === "install" || command === "uninstall") {
 }
 
 const packageName = platformPackage()
-const bin = platformWitnessBin()
-
-if (!bin || !existsSync(bin)) {
+// Honor an explicit WITNESS_BIN override, just like the plugin (witness.js) does —
+// used verbatim (no existsSync gate) so it can point at a dev build or a binary the
+// platform-package probe can't resolve. Without this the CLI ignored the very
+// override the plugin honored, so `WITNESS_BIN=... witness doctor` was inconsistent
+// with what the plugin runs (issue #54 minor).
+const override = process.env.WITNESS_BIN
+const bin = override || platformWitnessBin()
+
+if (!bin || (!override && !existsSync(bin))) {
   const reason = packageName ? `optional package ${packageName} is not installed` : `unsupported platform ${process.platform}/${process.arch}`
   console.error(`witness: ${reason}; supported platforms: ${supportedPlatforms()}`)
   process.exit(1)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@witness-ai/opencode",
-  "version": "0.2.4",
-  "description": "OpenCode plugin for witness session capture and background distillation.",
+  "version": "0.3.1",
+  "description": "MCP memory / second brain for Claude Code & OpenCode — captures your coding sessions and distills how your knowledge and habits evolve over time, queryable by your agent.",
   "type": "module",
   "main": "./witness.js",
   "exports": "./witness.js",
@@ -20,13 +20,27 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "@witness-ai/opencode-darwin-arm64": "0.2.4",
-    "@witness-ai/opencode-linux-x64": "0.2.4"
+    "@witness-ai/opencode-darwin-arm64": "0.3.1",
+    "@witness-ai/opencode-linux-x64": "0.3.1"
   },
   "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude-code",
     "opencode",
-    "plugin",
-    "witness"
+    "memory",
+    "ai-memory",
+    "self-improvement",
+    "reflection",
+    "second-brain",
+    "personal-knowledge-management",
+    "knowledge-distillation",
+    "temporal",
+    "provenance",
+    "growth",
+    "llm",
+    "coding-agent"
   ],
   "license": "MIT",
   "repository": {

package/prompts/SCHEMA.md

@@ -51,10 +51,16 @@ Every observation/facet carries a `lens` tag.
 
 - **`default`** — global, runs on every session, cross-domain. This is the thing no single-domain
   tracker can be.
-- **registered lenses** (e.g. `math`) — registered centrally (`witness lens register <name> <file>`)
+- **registered lenses** (e.g. `math`) — registered centrally (`witness lens register <name> <dir>`)
   and enabled globally (`witness lens enable <name>`); an enabled lens runs on every session.
-  Definitions live in the central registry (`<root>/lenses/<name>/lens.md`), shared across all
-  sessions — never read from a repo.
+  Definitions live in the central registry (`<root>/lenses/<name>/`), shared across all sessions —
+  never read from a repo.
+
+A lens is a **directory** of `lens.json` (settings: `name`, `dimensions`, optional per-lens models)
+plus `extract.md` and `review.md` (each whole file is the prompt for its pass). See
+`prompts/lens/example/`. Mining uses the default model by default, but a lens may pin its own via
+`witness lens set <name> --extract-model <m>` / `--review-model <m>` (written to its `lens.json`),
+so a rare heavy lens can run a stronger model without paying for it on every session.
 
 The profile is **collect-only / pull-only**: witness captures and distills everywhere, but never
 injects into a session. Agents read it on demand via the MCP tools (`get_facets`, `get_profile`,

package/prompts/default/lens.json

@@ -0,0 +1,4 @@
+{
+  "name": "default",
+  "dimensions": ["thinking", "workstyle", "habits", "traits", "biases", "state", "goals", "feedback"]
+}

package/prompts/lens/example/README.md

@@ -0,0 +1,23 @@
+# Example lens — a "math learner" lens
+
+A complete, ready-to-register example lens. A lens is a **directory** of three files:
+
+    lens.json     structured settings: name, dimensions, optional per-lens models
+    extract.md    the mining (L0→L1) prompt — the whole file is the prompt
+    review.md     the review (L1→L2) prompt — the whole file is the prompt
+
+Copy this directory, rewrite the dimensions and the two prompts for your domain, then:
+
+    witness lens register math ./example/      # copies the directory into the registry
+    witness lens enable   math                 # runs it on every session
+
+The two prompts are passed VERBATIM as the system prompt for their pass — they fully
+REPLACE the built-in `default` prompts, they don't extend them — so each must be
+self-contained, INCLUDING its output JSON schema. The tool appends the transcript
+(extract) or the accumulated observations (review) as the user message; it injects no
+schema for you.
+
+A lens is runner-agnostic: by default it rides the default model. To pin a stronger
+model just for this lens (without paying for it on every session), add an optional
+`"extract_model"` / `"review_model"` to `lens.json`, or run
+`witness lens set math --extract-model <model>` (empty value clears it).

package/prompts/lens/example/extract.md

@@ -0,0 +1,32 @@
+You are observing one study/work session between a person and an AI, through a
+MATH-LEARNING lens. Notice things about *the person as a mathematician* — how they
+reason, where they get stuck, and how they climb out — not the math facts themselves.
+
+Tag each observation with exactly one dimension:
+- speed — how fast they move; when they deliberately slow down vs. rush past a gap.
+- independence — do they attempt before asking; how much scaffolding they need.
+- proof_rigor — care with quantifiers, edge cases, and "why is this actually true?"
+- abstraction — comfort moving between concrete instances and general statements.
+- confusion_tolerance — how they sit with not-understanding before resolving it.
+
+What makes a GOOD observation:
+- Atomic — one noticed thing, one sentence.
+- Evidence-anchored — cite a short quote or paraphrase of the exact moment. No anchor, don't write it.
+- About the PERSON and durable-ish — "checked the base case unprompted" counts; "solved problem 3" is a task-fact, skip it.
+- Honest — note struggles, shortcuts, and regressions as readily as wins. Never invent failings or wins.
+
+Score poignancy 1-10 — how much a future reviewer should weight it for growth.
+Most are 3-6; reserve 7+ for a genuine mindset shift or a precise self-diagnosis.
+
+If the session was routine and nothing person-relevant happened, return `[]`.
+Do not manufacture observations to fill space.
+
+Return ONLY a JSON array, no prose around it. Each element:
+[
+  {
+    "dimension": "proof_rigor",
+    "observation": "Stopped to verify the base case unprompted after a hand-wavy induction.",
+    "evidence": "\"wait — does n=0 actually hold here?\" before moving on",
+    "poignancy": 6
+  }
+]

package/prompts/lens/example/lens.json

@@ -0,0 +1,4 @@
+{
+  "name": "math",
+  "dimensions": ["speed", "independence", "proof_rigor", "abstraction", "confusion_tolerance"]
+}

package/prompts/lens/example/review.md

@@ -0,0 +1,31 @@
+You are the reviewer for the MATH lens of a long-term, person-centric growth
+archive. You read the accumulated observations plus the current facets, and you
+assert what is true NOW, flagging genuine, sustained CHANGE over time.
+
+How to synthesize:
+- Group related observations into few, sharp, falsifiable facets within the dimensions above.
+- Name facet keys in snake_case, emergent from the evidence; reuse an existing key when updating it.
+- Every facet must cite the supporting observation IDs in `because_of`. No citation → no facet.
+- Prefer "attempts an approach before asking for help" (falsifiable) over "is good at math" (not).
+
+The change rule (most important):
+- Set `contradicts_prior: true` ONLY for a sustained, repeated pattern that
+  conflicts with the stored current value. One off-pattern session is noise, not
+  a reversal.
+- A time-bound `state`-like facet that has clearly passed can also flip.
+- Mere absence of recent evidence is NOT change. Never invent a "used to do X,
+  stopped" arc — if you can't cite observation IDs for the NEW value, it isn't a change.
+
+Confidence 0-1: 0.3-0.5 emerging; 0.6-0.8 well-supported across sessions; 0.9+ pervasive.
+
+Return ONLY a JSON array, no surrounding prose. Each element:
+[
+  {
+    "dimension": "independence",
+    "key": "attempts_before_asking",
+    "value": "Sketches an approach and tests it before reaching for help; a few months ago asked first.",
+    "confidence": 0.7,
+    "because_of": ["obs_8f2a3c", "obs_3c1190"],
+    "contradicts_prior": true
+  }
+]

package/witness.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 import { modelDir, modelReady, promptsDir, startModelDownload } from "./bin/model.js"
-import { platformWitnessBin } from "./bin/platform.js"
+import { platformPackage, platformWitnessBin, supportedPlatforms } from "./bin/platform.js"
 
 const PACKAGE_ROOT = fileURLToPath(new URL(".", import.meta.url))
 const DOWNLOAD_RETRY_MAX = 6
@@ -12,6 +12,25 @@ const IMPORT_GRACE_MS = 5000
 const platformBin = platformWitnessBin()
 const WITNESS_BIN = globalThis.WITNESS_SHIM || process.env.WITNESS_BIN || (existsSync(platformBin) ? platformBin : "")
 
+// Warn ONCE, non-throwing, when the plugin is genuinely inert: no witness binary
+// resolved for this platform/arch. Every hook below early-returns on an empty
+// WITNESS_BIN, so without this a user on darwin-x64 / linux-arm64 / win32 (no
+// matching optional package) sees the plugin load with zero diagnostic and
+// believes witness is capturing when nothing runs (issue #54 I4). Mirrors the
+// clear message the CLI (bin/witness.js) already prints. Suppressed inside the
+// worker subprocess (WITNESS_WORKER=1) so the recursion guard stays quiet, and a
+// warn must never throw — capture/plugin code must never break an OpenCode session.
+function warnIfInert() {
+  if (WITNESS_BIN || process.env.WITNESS_WORKER === "1") return
+  try {
+    const pkg = platformPackage()
+    const reason = pkg ? `optional package ${pkg} is not installed` : `unsupported platform ${process.platform}/${process.arch}`
+    console.warn(`witness: plugin inactive — ${reason}; nothing is being captured. Supported platforms: ${supportedPlatforms()}`)
+  } catch {
+    // Never let a diagnostic break the session.
+  }
+}
+
 function spawnWitness(args, payload) {
   if (!WITNESS_BIN || process.env.WITNESS_WORKER === "1") return
   try {
@@ -54,6 +73,7 @@ function waitForExit(child) {
 }
 
 const plugin = async () => {
+  warnIfInert()
   let disposed = false
   let disposing = false
   let disposePromise = null

package/prompts/lens/example.md

@@ -1,86 +0,0 @@
-# name: math
-# dimensions: speed, independence, proof_rigor, abstraction, confusion_tolerance
-
-<!--
-  A complete, ready-to-register example lens (a "math learner" lens).
-
-  Copy it, rewrite the dimensions and the two prompts for your domain, then:
-      witness lens register math ./this-file.md
-      witness lens enable  math
-
-  The `# name:` / `# dimensions:` lines above are real lens directives (the loader
-  parses them). The two sections below are passed VERBATIM as the system prompt for
-  their pass — they fully REPLACE the built-in `default` prompts, they don't extend
-  them — so each must be self-contained, INCLUDING its output JSON schema. The tool
-  appends the transcript (EXTRACT) or the accumulated observations (REVIEW) as the
-  user message; it injects no schema for you. Anything outside the two `##` sections
-  (like this comment) is ignored by the loader.
--->
-
-
-## EXTRACT
-You are observing one study/work session between a person and an AI, through a
-MATH-LEARNING lens. Notice things about *the person as a mathematician* — how they
-reason, where they get stuck, and how they climb out — not the math facts themselves.
-
-Tag each observation with exactly one dimension:
-- speed — how fast they move; when they deliberately slow down vs. rush past a gap.
-- independence — do they attempt before asking; how much scaffolding they need.
-- proof_rigor — care with quantifiers, edge cases, and "why is this actually true?"
-- abstraction — comfort moving between concrete instances and general statements.
-- confusion_tolerance — how they sit with not-understanding before resolving it.
-
-What makes a GOOD observation:
-- Atomic — one noticed thing, one sentence.
-- Evidence-anchored — cite a short quote or paraphrase of the exact moment. No anchor, don't write it.
-- About the PERSON and durable-ish — "checked the base case unprompted" counts; "solved problem 3" is a task-fact, skip it.
-- Honest — note struggles, shortcuts, and regressions as readily as wins. Never invent failings or wins.
-
-Score poignancy 1-10 — how much a future reviewer should weight it for growth.
-Most are 3-6; reserve 7+ for a genuine mindset shift or a precise self-diagnosis.
-
-If the session was routine and nothing person-relevant happened, return `[]`.
-Do not manufacture observations to fill space.
-
-Return ONLY a JSON array, no prose around it. Each element:
-[
-  {
-    "dimension": "proof_rigor",
-    "observation": "Stopped to verify the base case unprompted after a hand-wavy induction.",
-    "evidence": "\"wait — does n=0 actually hold here?\" before moving on",
-    "poignancy": 6
-  }
-]
-
-## REVIEW
-You are the reviewer for the MATH lens of a long-term, person-centric growth
-archive. You read the accumulated observations plus the current facets, and you
-assert what is true NOW, flagging genuine, sustained CHANGE over time.
-
-How to synthesize:
-- Group related observations into few, sharp, falsifiable facets within the dimensions above.
-- Name facet keys in snake_case, emergent from the evidence; reuse an existing key when updating it.
-- Every facet must cite the supporting observation IDs in `because_of`. No citation → no facet.
-- Prefer "attempts an approach before asking for help" (falsifiable) over "is good at math" (not).
-
-The change rule (most important):
-- Set `contradicts_prior: true` ONLY for a sustained, repeated pattern that
-  conflicts with the stored current value. One off-pattern session is noise, not
-  a reversal.
-- A time-bound `state`-like facet that has clearly passed can also flip.
-- Mere absence of recent evidence is NOT change. Never invent a "used to do X,
-  stopped" arc — if you can't cite observation IDs for the NEW value, it isn't a change.
-
-Confidence 0-1: 0.3-0.5 emerging; 0.6-0.8 well-supported across sessions; 0.9+ pervasive.
-
-Return ONLY a JSON array, no surrounding prose. Each element:
-[
-  {
-    "dimension": "independence",
-    "key": "attempts_before_asking",
-    "value": "Sketches an approach and tests it before reaching for help; a few months ago asked first.",
-    "confidence": 0.7,
-    "because_of": ["obs_8f2a3c", "obs_3c1190"],
-    "contradicts_prior": true
-  }
-]

package/prompts/lens/opencode.md

@@ -1,69 +0,0 @@
-# name: opencode
-# dimensions: agent_collaboration, tool_discipline, verification, context_management, autonomy_calibration, opencode_usage_preference
-
-<!--
-  A ready-to-register lens for OpenCode sessions:
-
-      witness lens register opencode prompts/lens/opencode.md
-      witness lens enable  opencode
-
-  It observes how a person collaborates with agentic coding tools, especially
-  OpenCode: what they delegate, how they steer, how they verify, and where their
-  workflow is becoming more or less disciplined.
--->
-
-## EXTRACT
-
-You are observing one work session between a person and an AI coding agent through an OPENCODE-WORKFLOW lens. Notice things about the person as an operator of agentic coding tools: how they frame work, delegate, inspect evidence, correct course, use tools, verify outcomes, and calibrate autonomy.
-
-Focus on person-centric growth/change, not on the task result. Good observations are anchored in concrete moments and reveal a reusable pattern in how the person works with agents.
-
-Dimensions:
-
-- agent_collaboration: how the person frames goals, constraints, feedback, and division of labor with the agent.
-- tool_discipline: how they choose, sequence, or constrain tools and data access.
-- verification: how they ask for, design, or interpret verification evidence.
-- context_management: how they preserve, recover, or compress project/session context.
-- autonomy_calibration: when they let the agent proceed, when they intervene, and how they handle uncertainty or risk.
-- opencode_usage_preference: what they prefer OpenCode for, which OpenCode workflows/models/data sources they trust, and when they choose OpenCode-specific affordances over Claude Code or generic agent workflows.
-
-Rules:
-
-- Evidence-anchored only. Every observation must cite a short concrete phrase or event from the session.
-- Person-centric only. Do not write observations like "implemented X" unless it reveals how the person works.
-- Prefer specific behavioral patterns over generic praise.
-- If the session is routine or contains no person-relevant signal, return `[]`.
-- Return 0-8 observations.
-
-Return ONLY a JSON array. Each element must be:
-
-[{ "dimension": "agent_collaboration", "observation": "one concise person-centric observation", "evidence": "short quote or paraphrase from the session", "poignancy": 1 }]
-
-Poignancy is 1-10: 1-3 minor signal, 4-6 useful recurring-pattern signal, 7-10 unusually clear change/risk/breakthrough.
-
-## REVIEW
-
-You are the reviewer for the OPENCODE-WORKFLOW lens of a long-term person-centric growth archive. You are given atomic observations about how the person works with agentic coding tools and the current stored facets for this lens.
-
-Synthesize observations into a small set of stable, falsifiable facets about the person's agentic workflow. Each facet should name a durable pattern, not a one-off event. Preserve change over time: only mark `contradicts_prior: true` when the observations show a sustained new pattern that genuinely conflicts with the current value.
-
-Facet guidance:
-
-- agent_collaboration facets can describe goal framing, feedback style, delegation boundaries, or how the person corrects the agent.
-- tool_discipline facets can describe how they inspect sources, avoid unsafe operations, or prefer evidence over assumptions.
-- verification facets can describe test selection, acceptance criteria, and how much proof they require.
-- context_management facets can describe how they use local memory, docs, databases, handoffs, or summaries.
-- autonomy_calibration facets can describe when they push for autonomous execution versus pausing for decisions.
-- opencode_usage_preference facets can describe when the person prefers OpenCode, which OpenCode-native evidence or models they ask for, and how they evaluate OpenCode-specific workflows compared with Claude Code.
-
-Rules:
-
-- Keep facets few and sharp. Avoid duplicating the same pattern under multiple names.
-- Ground every facet in observation IDs from `because_of`.
-- Do not infer personality, identity, or private facts beyond the evidence.
-- Absence of evidence is not contradiction.
-- Confidence 0-1: 0.3-0.5 emerging, 0.6-0.8 recurring, 0.9+ pervasive across sessions.
-
-Return ONLY a JSON array. Each element must be:
-
-[{ "dimension": "verification", "key": "diagnosis_before_action", "value": "The person increasingly asks the agent to inspect source evidence and verify with targeted commands before claiming completion.", "confidence": 0.7, "because_of": ["obs_abc123"], "contradicts_prior": false }]