openhermes 1.13.1 → 2.5.0

package/lib/ohc/state.mjs

@@ -2,31 +2,262 @@ import fs from "node:fs"
 import path from "node:path"
 import os from "node:os"
 
-const STATE_DIR = path.join(os.homedir(), ".local", "share", "opencode")
-const STATE_FILE = path.join(STATE_DIR, "ohc-state.json")
+const STATE_DIR = path.join(os.homedir(), ".local", "share", "opencode", "ohc")
+const LEGACY_FILE = path.join(os.homedir(), ".local", "share", "opencode", "ohc-state.json")
 
-function readAll() {
-  try {
-    return JSON.parse(fs.readFileSync(STATE_FILE, "utf8"))
-  } catch {
-    return {}
-  }
+function sessionPath(sessionId) {
+  const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_")
+  return path.join(STATE_DIR, `${safe}.json`)
 }
 
-function writeAll(data) {
+function ensureDir() {
   fs.mkdirSync(STATE_DIR, { recursive: true })
-  fs.writeFileSync(STATE_FILE, JSON.stringify(data, null, 2), "utf8")
 }
 
+function migrateLegacy() {
+  try {
+    if (!fs.existsSync(LEGACY_FILE)) return
+    const raw = JSON.parse(fs.readFileSync(LEGACY_FILE, "utf8"))
+    if (typeof raw !== "object") return
+    ensureDir()
+    for (const [sid, data] of Object.entries(raw)) {
+      const sp = sessionPath(sid)
+      if (!fs.existsSync(sp)) {
+        fs.writeFileSync(sp, JSON.stringify({ ...data, migratedFrom: "legacy" }, null, 2), "utf8")
+      }
+    }
+    fs.renameSync(LEGACY_FILE, LEGACY_FILE + ".bak")
+  } catch {}
+}
+
+migrateLegacy()
+
 export function loadOhcState(sessionId) {
   if (!sessionId) return null
-  const all = readAll()
-  return all[sessionId] || null
+  try {
+    return JSON.parse(fs.readFileSync(sessionPath(sessionId), "utf8"))
+  } catch {
+    return null
+  }
 }
 
 export function saveOhcState(sessionId, data) {
   if (!sessionId) return
-  const all = readAll()
-  all[sessionId] = { ...data, updatedAt: new Date().toISOString() }
-  writeAll(all)
+  ensureDir()
+  fs.writeFileSync(sessionPath(sessionId), JSON.stringify({ ...data, updatedAt: new Date().toISOString() }, null, 2), "utf8")
+}
+
+
+export function createSessionState() {
+  return {
+    sessionId: null,
+    isSubAgent: false,
+    manualMode: false,
+    pendingManualTrigger: null,
+    prune: {
+      tools: new Map(),
+      messages: {
+        byMessageId: new Map(),
+        blocksById: new Map(),
+        activeBlockIds: new Set(),
+        activeByAnchorMessageId: new Map(),
+        nextBlockId: 1,
+        nextRunId: 1,
+      },
+    },
+    nudges: {
+      contextLimitAnchors: new Set(),
+      turnNudgeAnchors: new Set(),
+      iterationNudgeAnchors: new Set(),
+    },
+    stats: {
+      pruneTokenCounter: 0,
+      totalPruneTokens: 0,
+    },
+    toolParameters: new Map(),
+    toolIdList: [],
+    messageIds: { byRawId: new Map(), byRef: new Map(), nextRef: 1 },
+    lastCompaction: 0,
+    currentTurn: 0,
+    modelContextLimit: undefined,
+    systemPromptTokens: undefined,
+    protectedTurns: { enabled: false, turns: 0 },
+    compressionTiming: { starts: new Map(), pendingByCallId: new Map(), lastDurationMs: 0, totalDurationMs: 0 },
+    lastNudgePct: 0,
+    lastAutoPruneAt: null,
+    prunedIds: new Set(),
+    summary: null,
+    anchorMessageId: null,
+    totalTokensSaved: 0,
+    blockCount: 0,
+  }
+}
+
+function pruneMapToObj(map) {
+  return Object.fromEntries(map)
+}
+
+function pruneMapFromObj(obj) {
+  if (!obj || typeof obj !== "object") return new Map()
+  return new Map(Object.entries(obj))
+}
+
+function setToArr(s) {
+  return [...s]
+}
+
+function setFromArr(a) {
+  return new Set(Array.isArray(a) ? a : [])
+}
+
+export function serializeState(state) {
+  return {
+    sessionId: state.sessionId,
+    manualMode: state.manualMode,
+    lastCompaction: state.lastCompaction,
+    currentTurn: state.currentTurn,
+    modelContextLimit: state.modelContextLimit,
+    systemPromptTokens: state.systemPromptTokens,
+    stats: { ...state.stats },
+    nudges: {
+      contextLimitAnchors: setToArr(state.nudges.contextLimitAnchors),
+      turnNudgeAnchors: setToArr(state.nudges.turnNudgeAnchors),
+      iterationNudgeAnchors: setToArr(state.nudges.iterationNudgeAnchors),
+    },
+    prune: {
+      tools: pruneMapToObj(state.prune.tools),
+      messages: {
+        nextBlockId: state.prune?.messages?.nextBlockId || 1,
+        nextRunId: state.prune?.messages?.nextRunId || 1,
+        blocksById: pruneMapToObj(state.prune?.messages?.blocksById),
+        byMessageId: pruneMapToObj(state.prune?.messages?.byMessageId),
+        activeBlockIds: setToArr(state.prune?.messages?.activeBlockIds),
+      },
+    },
+    lastAutoPruneAt: state.lastAutoPruneAt,
+    totalTokensSaved: state.totalTokensSaved,
+    blockCount: state.blockCount,
+    summary: state.summary,
+    anchorMessageId: state.anchorMessageId,
+    prunedIds: setToArr(state.prunedIds),
+    isSubAgent: state.isSubAgent || false,
+    messageIds: {
+      byRawId: pruneMapToObj(state.messageIds?.byRawId),
+      byRef: pruneMapToObj(state.messageIds?.byRef),
+      nextRef: state.messageIds?.nextRef || 1,
+    },
+    compressionTiming: {
+      starts: Object.fromEntries(state.compressionTiming?.starts || new Map()),
+      lastDurationMs: state.compressionTiming?.lastDurationMs || 0,
+      totalDurationMs: state.compressionTiming?.totalDurationMs || 0,
+    },
+  }
+}
+
+export function deserializeState(saved) {
+  const state = createSessionState()
+  if (!saved) return state
+  state.sessionId = saved.sessionId || null
+  state.manualMode = saved.manualMode || false
+  state.lastCompaction = saved.lastCompaction || 0
+  state.currentTurn = saved.currentTurn || 0
+  state.modelContextLimit = saved.modelContextLimit
+  state.systemPromptTokens = saved.systemPromptTokens
+  if (saved.stats) Object.assign(state.stats, saved.stats)
+  if (saved.nudges) {
+    state.nudges.contextLimitAnchors = setFromArr(saved.nudges.contextLimitAnchors)
+    state.nudges.turnNudgeAnchors = setFromArr(saved.nudges.turnNudgeAnchors)
+    state.nudges.iterationNudgeAnchors = setFromArr(saved.nudges.iterationNudgeAnchors)
+  }
+  if (saved.prune?.tools) state.prune.tools = pruneMapFromObj(saved.prune.tools)
+  if (saved.prune?.messages) {
+    const pm = saved.prune.messages
+    state.prune.messages.nextBlockId = pm.nextBlockId || 1
+    state.prune.messages.nextRunId = pm.nextRunId || 1
+    state.prune.messages.blocksById = pruneMapFromObj(pm.blocksById)
+    state.prune.messages.byMessageId = pruneMapFromObj(pm.byMessageId)
+    state.prune.messages.activeBlockIds = setFromArr(pm.activeBlockIds)
+  }
+  state.lastAutoPruneAt = saved.lastAutoPruneAt || null
+  state.totalTokensSaved = saved.totalTokensSaved || 0
+  state.blockCount = saved.blockCount || 0
+  state.summary = saved.summary || null
+  state.anchorMessageId = saved.anchorMessageId || null
+    state.prunedIds = setFromArr(saved.prunedIds)
+  if (saved.compressionTiming) {
+    state.compressionTiming.starts = pruneMapFromObj(saved.compressionTiming.starts)
+    state.compressionTiming.lastDurationMs = saved.compressionTiming.lastDurationMs || 0
+    state.compressionTiming.totalDurationMs = saved.compressionTiming.totalDurationMs || 0
+  }
+  if (saved.messageIds) {
+    state.messageIds.byRawId = pruneMapFromObj(saved.messageIds.byRawId)
+    state.messageIds.byRef = pruneMapFromObj(saved.messageIds.byRef)
+    state.messageIds.nextRef = saved.messageIds.nextRef || 1
+  }
+  if (saved.isSubAgent !== undefined) state.isSubAgent = saved.isSubAgent
+  return state
+}
+
+export function buildToolIdList(state, messages) {
+  const ids = []
+  for (const msg of messages) {
+    if (!Array.isArray(msg.parts)) continue
+    for (const part of msg.parts) {
+      if (part.type === "tool" && part.callID) {
+        ids.push(part.callID)
+      }
+    }
+  }
+  state.toolIdList = ids
+  return ids
+}
+
+export function syncToolCache(state, messages) {
+  let maxTurn = 0
+  for (const msg of messages) {
+    if (msg.info?.role === "user") {
+      const lastUser = state.toolIdList.length > 0
+      if (lastUser) maxTurn++
+    }
+    if (!Array.isArray(msg.parts)) continue
+    for (const part of msg.parts) {
+      if (part.type !== "tool" || !part.callID) continue
+      const existing = state.toolParameters.get(part.callID)
+      if (existing) {
+        existing.status = part.state?.status || existing.status
+        continue
+      }
+      state.toolParameters.set(part.callID, {
+        tool: part.tool || "unknown",
+        parameters: part.state?.input || {},
+        status: part.state?.status || "pending",
+        turn: maxTurn,
+        tokenCount: estimateToolTokens(part),
+        lastSeen: Date.now(),
+      })
+    }
+  }
+  state.currentTurn = Math.max(state.currentTurn, maxTurn)
+}
+
+function estimateToolTokens(part) {
+  if (!part.state) return 0
+  let t = 0
+  if (part.state.input) t += JSON.stringify(part.state.input).length / 4
+  if (part.state.output) {
+    t += (typeof part.state.output === "string" ? part.state.output : JSON.stringify(part.state.output ?? "")).length / 4
+  }
+  return Math.ceil(t)
+}
+
+export function countTurns(state, messages) {
+  let userCount = 0
+  for (const msg of messages) {
+    if (msg.info?.role === "user") {
+      const parts = Array.isArray(msg.parts) ? msg.parts : []
+      const hasText = parts.some(p => p.type === "text" && p.text?.trim())
+      if (hasText) userCount++
+    }
+  }
+  return userCount
 }

package/lib/ohc/strategies/deduplication.mjs

@@ -0,0 +1,72 @@
+import { isToolNameProtected, getFilePathsFromParameters, isFilePathProtected } from "../protected-patterns.mjs"
+import { getTotalToolTokens } from "../token-utils.mjs"
+
+export function deduplicate(state, config, messages) {
+  if (state.manualMode && !config.manualMode?.automaticStrategies) return
+
+  if (!config.strategies?.deduplication?.enabled) return
+
+  const allIds = state.toolIdList
+  if (!allIds?.length) return
+
+  const unprunedIds = allIds.filter(id => !state.prune.tools.has(id))
+  if (!unprunedIds.length) return
+
+  const protectedTools = config.strategies.deduplication.protectedTools || []
+
+  const sigMap = new Map()
+
+  for (const id of unprunedIds) {
+    const meta = state.toolParameters.get(id)
+    if (!meta) continue
+
+    if (isToolNameProtected(meta.tool, protectedTools)) continue
+
+    const fps = getFilePathsFromParameters(meta.tool, meta.parameters)
+    if (isFilePathProtected(fps, config.protectedFilePatterns)) continue
+
+    const sig = createToolSignature(meta.tool, meta.parameters)
+    if (!sigMap.has(sig)) sigMap.set(sig, [])
+    sigMap.get(sig).push(id)
+  }
+
+  const toPrune = []
+  for (const ids of sigMap.values()) {
+    if (ids.length > 1) {
+      toPrune.push(...ids.slice(0, -1))
+    }
+  }
+
+  if (!toPrune.length) return
+
+  state.stats.totalPruneTokens += getTotalToolTokens(state, toPrune)
+  for (const id of toPrune) {
+    const entry = state.toolParameters.get(id)
+    state.prune.tools.set(id, entry?.tokenCount ?? 0)
+  }
+}
+
+function createToolSignature(tool, params) {
+  if (!params) return tool
+  const norm = normalizeParams(params)
+  const sorted = sortKeys(norm)
+  return `${tool}::${JSON.stringify(sorted)}`
+}
+
+function normalizeParams(p) {
+  if (typeof p !== "object" || p === null) return p
+  if (Array.isArray(p)) return p
+  const n = {}
+  for (const [k, v] of Object.entries(p)) {
+    if (v !== undefined && v !== null) n[k] = v
+  }
+  return n
+}
+
+function sortKeys(o) {
+  if (typeof o !== "object" || o === null) return o
+  if (Array.isArray(o)) return o.map(sortKeys)
+  const s = {}
+  for (const k of Object.keys(o).sort()) s[k] = sortKeys(o[k])
+  return s
+}

package/lib/ohc/strategies/index.mjs

@@ -0,0 +1,2 @@
+export { deduplicate } from "./deduplication.mjs"
+export { purgeErrors } from "./purge-errors.mjs"

package/lib/ohc/strategies/purge-errors.mjs

@@ -0,0 +1,43 @@
+import { isToolNameProtected, getFilePathsFromParameters, isFilePathProtected } from "../protected-patterns.mjs"
+import { getTotalToolTokens } from "../token-utils.mjs"
+
+export function purgeErrors(state, config, messages) {
+  if (state.manualMode && !config.manualMode?.automaticStrategies) return
+
+  if (!config.strategies?.purgeErrors?.enabled) return
+
+  const allIds = state.toolIdList
+  if (!allIds?.length) return
+
+  const unprunedIds = allIds.filter(id => !state.prune.tools.has(id))
+  if (!unprunedIds.length) return
+
+  const protectedTools = config.strategies.purgeErrors.protectedTools || []
+  const threshold = Math.max(1, config.strategies.purgeErrors.turns ?? 4)
+
+  const toPrune = []
+  for (const id of unprunedIds) {
+    const meta = state.toolParameters.get(id)
+    if (!meta) continue
+
+    if (isToolNameProtected(meta.tool, protectedTools)) continue
+
+    const fps = getFilePathsFromParameters(meta.tool, meta.parameters)
+    if (isFilePathProtected(fps, config.protectedFilePatterns)) continue
+
+    if (meta.status !== "error") continue
+
+    const turnAge = state.currentTurn - meta.turn
+    if (turnAge >= threshold) {
+      toPrune.push(id)
+    }
+  }
+
+  if (!toPrune.length) return
+
+  state.stats.totalPruneTokens += getTotalToolTokens(state, toPrune)
+  for (const id of toPrune) {
+    const entry = state.toolParameters.get(id)
+    state.prune.tools.set(id, entry?.tokenCount ?? 0)
+  }
+}

package/lib/ohc/token-utils.mjs

@@ -0,0 +1,26 @@
+import { totalTokens } from "./reaper.mjs"
+
+export { totalTokens }
+
+export function countTokens(value) {
+  if (typeof value === "string") return Math.ceil(value.length / 4)
+  if (typeof value === "object" && value !== null) return Math.ceil(JSON.stringify(value).length / 4)
+  return 0
+}
+
+export function getTotalToolTokens(state, toolIds) {
+  let total = 0
+  for (const id of toolIds) {
+    const entry = state.toolParameters.get(id)
+    if (entry?.tokenCount) total += entry.tokenCount
+  }
+  return total
+}
+
+function estimateToolTokenCost(part) {
+  if (part.type !== "tool") return 0
+  let t = 0
+  if (part.state?.input) t += countTokens(part.state.input)
+  if (part.state?.output) t += countTokens(part.state.output)
+  return t
+}

package/lib/ohc/updater.mjs

@@ -3,7 +3,10 @@ import path from "node:path"
 import os from "node:os"
 
 const CONFIG_PATH = path.join(os.homedir(), ".config", "opencode", "opencode.json")
-const CACHE_ROOT = path.join(os.homedir(), ".cache", "opencode", "packages")
+const CACHE_ROOTS = [
+  path.join(os.homedir(), ".cache", "opencode", "packages"),
+  path.join(os.homedir(), ".cache", "opencode", "node_modules"),
+]
 
 function detectInstallMethod() {
   let raw = {}
@@ -33,18 +36,37 @@ function detectInstallMethod() {
   return { method: "unknown", entry: null, reason: "openhermes not found in plugin config" }
 }
 
-function findCacheDirs() {
-  const results = []
-  if (!fs.existsSync(CACHE_ROOT)) return results
+function walkCacheDirs(root, results) {
+  if (!fs.existsSync(root)) return
+  if (path.basename(root).startsWith("openhermes")) {
+    results.push({ name: path.basename(root), path: root })
+  }
+  let entries = []
   try {
-    for (const e of fs.readdirSync(CACHE_ROOT)) {
-      const full = path.join(CACHE_ROOT, e)
-      if (e.startsWith("openhermes") && fs.statSync(full).isDirectory()) {
-        results.push({ name: e, path: full })
-      }
+    entries = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const full = path.join(root, entry.name)
+    if (entry.name.startsWith("openhermes")) {
+      results.push({ name: entry.name, path: full })
     }
-  } catch {}
-  return results
+    walkCacheDirs(full, results)
+  }
+}
+
+export function findCacheDirs({ cacheRoots = CACHE_ROOTS } = {}) {
+  const results = []
+  for (const root of cacheRoots) walkCacheDirs(root, results)
+  const seen = new Set()
+  return results.filter(dir => {
+    if (seen.has(dir.path)) return false
+    seen.add(dir.path)
+    return true
+  })
 }
 
 async function handleUpdateMe(ctx, input, output) {
@@ -65,7 +87,8 @@ async function handleUpdateMe(ctx, input, output) {
     output.parts.length = 0
     output.parts.push({
       type: "text",
-      text: `[Update-Me] No cached version found. Already at the latest (method: ${info.method}). Restart OpenCode if you suspect a stale install.`,
+      text: `[Update-Me] No OpenHermes cache found under OpenCode package/node_modules caches.
+Restart OpenCode to redownload from ${info.method === "git" ? "git HEAD" : "npm registry"}.`,
     })
     return
   }
@@ -92,7 +115,7 @@ async function handleUpdateMe(ctx, input, output) {
   if (failed.length > 0) {
     msg += `\n⚠ Could not remove (file may be locked):\n`
     for (const f of failed) msg += `  ✗ ${f.name} — ${f.error}\n`
-    msg += `Try deleting manually:\n  ${CACHE_ROOT}\n`
+    msg += `Try deleting manually:\n  ${CACHE_ROOTS.join("\n  ")}\n`
   }
 
   msg += `\nRestart OpenCode to load the latest OpenHermes from ${info.method === "git" ? "git HEAD" : "npm registry"}.`

package/lib/paths.mjs

@@ -16,9 +16,6 @@ function resolveRoot(envVar, fallback) {
   return fallback
 }
 
-export function getConfigRoot() {
-  return null // legacy — no longer used
-}
 
 export function getDataRoot() {
   return resolveRoot("OPENCODE_ALLOW_PROJECT_HARNESS", DATA_ROOT)

package/lib/search.mjs

@@ -0,0 +1,48 @@
+export function scoreRelevance(r, query, project) {
+  const q = query.toLowerCase()
+  const tokens = q.split(/\s+/).filter(t => t.length > 2)
+  let score = 0
+
+  const primaryFields = [r.summary, r.description, r.mission, r.current_state, r.failure, r.root_cause, r.fix, r.prevention, r.id].filter(Boolean)
+  const secondaryFields = [r.command, r.project, r.scope].filter(Boolean)
+  const listFields = [...(Array.isArray(r.tags) ? r.tags : []), ...(Array.isArray(r.next_actions) ? r.next_actions : []), ...(Array.isArray(r.refs) ? r.refs : [])].filter(Boolean)
+
+  for (const f of primaryFields) {
+    const str = String(f).toLowerCase()
+    let idx = 0; let count = 0
+    while ((idx = str.indexOf(q, idx)) !== -1) { count++; idx += q.length }
+    score += count * 15
+    if (str.startsWith(q)) score += 10
+    if (str.includes(q)) score += 4
+    for (const token of tokens) {
+      if (str.includes(token)) score += 4
+      if (str.startsWith(token)) score += 2
+    }
+  }
+
+  for (const f of secondaryFields) {
+    const str = String(f).toLowerCase()
+    if (str.includes(q)) score += 8
+    for (const token of tokens) {
+      if (str.includes(token)) score += 3
+    }
+  }
+
+  for (const f of listFields) {
+    const str = String(f).toLowerCase()
+    if (str.includes(q)) score += 5
+    for (const token of tokens) {
+      if (str.includes(token)) score += 2
+    }
+  }
+
+  if (r.project && r.project.toLowerCase() === (project || "").toLowerCase()) score += 25
+  if (r.project && project && r.project.toLowerCase().includes(project.toLowerCase())) score += 12
+
+  const age = Date.now() - Date.parse(r.updated_at || r.created_at || 0)
+  if (!Number.isNaN(age)) score += Math.max(0, 10 - age / 604800000)
+  if (r.status === "active") score += 4
+  if (r.status === "closed") score -= 3
+
+  return score
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openhermes",
-  "version": "1.13.1",
+  "version": "2.5.0",
   "description": "OpenHermes plugin suite for OpenCode — autonomous checkpointing, native memory tools, subagent routing, slash commands, and skill-candidate detection.",
   "type": "module",
   "license": "MIT",

package/schemas/audit.schema.json

@@ -20,7 +20,9 @@
         "task_id": { "type": "string" },
         "db_refs": { "type": "array", "items": { "type": "string" } },
         "file_refs": { "type": "array", "items": { "type": "string" } },
-        "log_refs": { "type": "array", "items": { "type": "string" } }
+        "log_refs": { "type": "array", "items": { "type": "string" } },
+        "harness_root": { "type": "string" },
+        "project_root": { "type": "string" }
       }
     },
     "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" },
@@ -56,6 +58,25 @@
         "provenance_ok": { "type": "boolean", "description": "All objects have valid provenance" },
         "duplicates_ok": { "type": "boolean", "description": "No duplicate IDs found" }
       }
+    },
+    "description": { "type": "string", "description": "Optional description" },
+    "environment_fingerprint": {
+      "type": "object",
+      "description": "System fingerprint at creation time",
+      "properties": {
+        "cwd": { "type": "string" },
+        "harness_root": { "type": "string" },
+        "project_root": { "type": "string" },
+        "project": { "type": "string" },
+        "session_id": { "type": "string" },
+        "os": { "type": "string" },
+        "release": { "type": "string" },
+        "arch": { "type": "string" },
+        "shell": { "type": "string" },
+        "provider": { "type": "string" },
+        "model": { "type": "string" },
+        "sha256": { "type": "string" }
+      }
     }
   }
 }

package/schemas/backlog.schema.json

@@ -20,7 +20,9 @@
         "task_id": { "type": "string" },
         "db_refs": { "type": "array", "items": { "type": "string" } },
         "file_refs": { "type": "array", "items": { "type": "string" } },
-        "log_refs": { "type": "array", "items": { "type": "string" } }
+        "log_refs": { "type": "array", "items": { "type": "string" } },
+        "harness_root": { "type": "string" },
+        "project_root": { "type": "string" }
       }
     },
     "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" },
@@ -37,6 +39,25 @@
     "priority": { "type": "string", "enum": ["low", "medium", "high", "critical", "P0", "P1", "P2", "P3", "P4"], "description": "Priority level (low/medium/high/critical or P0-P4)" },
     "trigger": { "type": "string", "enum": ["audit", "mistake", "drift", "user", "manual"], "description": "What triggered creation of this item" },
     "evidence_refs": { "type": "array", "items": { "type": "string" }, "description": "References to evidence (audit IDs, mistake IDs, file paths)" },
-    "done_when": { "type": "array", "items": { "type": "string" }, "description": "Acceptance criteria — concrete conditions for closure" }
+    "done_when": { "type": "array", "items": { "type": "string" }, "description": "Acceptance criteria — concrete conditions for closure" },
+    "description": { "type": "string", "description": "Optional description" },
+    "environment_fingerprint": {
+      "type": "object",
+      "description": "System fingerprint at creation time",
+      "properties": {
+        "cwd": { "type": "string" },
+        "harness_root": { "type": "string" },
+        "project_root": { "type": "string" },
+        "project": { "type": "string" },
+        "session_id": { "type": "string" },
+        "os": { "type": "string" },
+        "release": { "type": "string" },
+        "arch": { "type": "string" },
+        "shell": { "type": "string" },
+        "provider": { "type": "string" },
+        "model": { "type": "string" },
+        "sha256": { "type": "string" }
+      }
+    }
   }
 }