opencode-agent-skill 7.7.0 → 10.0.0

package/lib/task-engine.mjs

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs"
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs"
 import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
 import { spawnSync } from "node:child_process"
 import { createHash, randomUUID } from "node:crypto"
@@ -7,11 +7,15 @@ import { analyzePlan, taskFiles, validatePlan } from "./task-graph.mjs"
 import { buildContextManifest } from "./context-manifest.mjs"
 import { relevantAcceptedLearnings } from "./learning-engine.mjs"
 import { validateVerificationReceipt } from "./evidence-receipt.mjs"
+import { appendRuntimeEvent, readRuntimeEvents } from "./runtime-events.mjs"
+import { createGateReceipt, validateGateReceipt } from "./gate-receipt.mjs"
+import { classifyEngineeringTask, recoveryPolicyForAttempt } from "./orchestrator-policy.mjs"
 
 const WORK_DIR = ".ues-work"
-const STATE_SCHEMA = 3
+const STATE_SCHEMA = 4
 const LOCK_TIMEOUT_MS = 30_000
 const LOCK_STALE_MS = 120_000
+const LOCK_HEARTBEAT_MS = 15_000
 const DEFAULT_TASK_LEASE_MS = 10 * 60_000
 
 function now() {
@@ -37,6 +41,7 @@ export function workPaths(root, slug) {
     plan: path.join(dir, "PLAN.json"),
     state: path.join(dir, "STATE.json"),
     evidence: path.join(dir, "EVIDENCE.json"),
+    events: path.join(dir, "EVENTS.jsonl"),
     tasks: path.join(dir, "tasks"),
     reports: path.join(dir, "reports"),
     lock: path.join(dir, ".state-lock"),
@@ -67,23 +72,43 @@ async function writeJson(file, value) {
   await atomicWrite(file, JSON.stringify(value, null, 2) + "\n")
 }
 
+async function journal(paths, type, data = {}) {
+  return appendRuntimeEvent(paths.events, type, {
+    slug: path.basename(paths.dir),
+    ...data,
+  })
+}
+
+async function lockOwner(paths) {
+  return readJson(path.join(paths.lock, "owner.json"), null).catch(() => null)
+}
+
 async function acquireWorkLock(paths) {
   const started = Date.now()
   while (true) {
+    const token = randomUUID()
     try {
       await mkdir(paths.lock)
+      const owner = { pid: process.pid, token, at: now(), heartbeatAt: now() }
       await writeFile(
         path.join(paths.lock, "owner.json"),
-        JSON.stringify({ pid: process.pid, at: now() }) + "\n",
+        JSON.stringify(owner) + "\n",
         "utf8",
-      ).catch(() => {})
-      return
+      )
+      return owner
     } catch (error) {
       if (error?.code !== "EEXIST") throw error
-      const info = await stat(paths.lock).catch(() => null)
+      const ownerFile = path.join(paths.lock, "owner.json")
+      const info = await stat(ownerFile).catch(() => stat(paths.lock).catch(() => null))
       if (info && Date.now() - info.mtimeMs > LOCK_STALE_MS) {
-        await rm(paths.lock, { recursive: true, force: true }).catch(() => {})
-        continue
+        const stale = paths.lock + ".stale-" + randomUUID()
+        try {
+          await rename(paths.lock, stale)
+          await rm(stale, { recursive: true, force: true }).catch(() => {})
+          continue
+        } catch {
+          // Another contender refreshed or took over the lock first.
+        }
       }
       if (Date.now() - started >= LOCK_TIMEOUT_MS) {
         throw new Error(`timed out waiting for UES state lock: ${paths.lock}`)
@@ -93,13 +118,36 @@ async function acquireWorkLock(paths) {
   }
 }
 
+async function heartbeatWorkLock(paths, token) {
+  const owner = await lockOwner(paths)
+  if (!owner || owner.token !== token) return false
+  await writeFile(
+    path.join(paths.lock, "owner.json"),
+    JSON.stringify({ ...owner, heartbeatAt: now() }) + "\n",
+    "utf8",
+  )
+  return true
+}
+
+async function releaseWorkLock(paths, token) {
+  const owner = await lockOwner(paths)
+  if (!owner || owner.token !== token) return false
+  await rm(paths.lock, { recursive: true, force: true })
+  return true
+}
+
 async function withWorkLock(root, slug, fn) {
   const paths = workPaths(root, slug)
-  await acquireWorkLock(paths)
+  const owner = await acquireWorkLock(paths)
+  const heartbeat = setInterval(() => {
+    heartbeatWorkLock(paths, owner.token).catch(() => {})
+  }, LOCK_HEARTBEAT_MS)
+  heartbeat.unref?.()
   try {
     return await fn(paths)
   } finally {
-    await rm(paths.lock, { recursive: true, force: true }).catch(() => {})
+    clearInterval(heartbeat)
+    await releaseWorkLock(paths, owner.token).catch(() => {})
   }
 }
 
@@ -115,19 +163,92 @@ function gitCapture(root, args) {
   })
 }
 
+const FINGERPRINT_SKIP_DIRS = new Set([
+  ".git", ".ues-work", ".ues-learning", ".ues-dashboard", ".ues-sandboxes", ".ues-cache", ".ues-traces",
+  "node_modules", ".next", "dist", "build", "coverage", ".venv", "venv",
+  "Pods", "DerivedData", ".gradle", ".cache", ".turbo", "target", "bin", "obj",
+])
+
+function nonGitWorkspaceFingerprint(root, options = {}) {
+  const maxFiles = Math.max(100, Number(options.maxFiles || 5000))
+  const maxFileBytes = Math.max(64 * 1024, Number(options.maxFileBytes || 2 * 1024 * 1024))
+  const files = []
+
+  function visit(dir) {
+    if (files.length >= maxFiles) return
+    let entries = []
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    for (const entry of entries) {
+      if (files.length >= maxFiles) break
+      if (entry.isDirectory() && FINGERPRINT_SKIP_DIRS.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        visit(full)
+        continue
+      }
+      if (!entry.isFile()) continue
+      const relative = path.relative(root, full).replaceAll("\\", "/")
+      let info
+      try { info = statSync(full) } catch { continue }
+      files.push({ full, relative, size: info.size, mtimeMs: info.mtimeMs })
+    }
+  }
+
+  visit(root)
+  const hash = createHash("sha256")
+  hash.update("non-git-workspace-v2\n")
+  hash.update("truncated=" + String(files.length >= maxFiles) + "\n")
+  for (const file of files) {
+    hash.update(file.relative + "\0" + file.size + "\0")
+    if (file.size <= maxFileBytes) {
+      try {
+        hash.update(readFileSync(file.full))
+      } catch {
+        hash.update("READ_ERROR:" + file.mtimeMs)
+      }
+    } else {
+      let fd = null
+      try {
+        fd = openSync(file.full, "r")
+        const sampleBytes = Math.min(64 * 1024, file.size)
+        const first = Buffer.allocUnsafe(sampleBytes)
+        const last = Buffer.allocUnsafe(sampleBytes)
+        readSync(fd, first, 0, sampleBytes, 0)
+        readSync(fd, last, 0, sampleBytes, Math.max(0, file.size - sampleBytes))
+        hash.update("LARGE_SAMPLE:")
+        hash.update(first)
+        hash.update(last)
+      } catch {
+        hash.update("READ_ERROR:" + file.mtimeMs)
+      } finally {
+        if (fd !== null) {
+          try { closeSync(fd) } catch {}
+        }
+      }
+    }
+    hash.update("\n")
+  }
+  return hash.digest("hex")
+}
+
 export function workspaceFingerprint(root) {
   root = path.resolve(root)
   const inside = gitCapture(root, ["rev-parse", "--is-inside-work-tree"])
   if (inside.status !== 0) {
-    return createHash("sha256").update("non-git:" + root).digest("hex")
+    return nonGitWorkspaceFingerprint(root)
   }
 
   const parts = []
   const commands = [
     ["rev-parse", "HEAD"],
-    ["status", "--porcelain=v1", "--untracked-files=all", "--", ".", ":(exclude).ues-work", ":(exclude).ues-learning", ":(exclude).ues-dashboard", ":(exclude).ues-sandboxes"],
-    ["diff", "--binary", "--no-ext-diff", "--", ".", ":(exclude).ues-work", ":(exclude).ues-learning", ":(exclude).ues-dashboard", ":(exclude).ues-sandboxes"],
-    ["diff", "--cached", "--binary", "--no-ext-diff", "--", ".", ":(exclude).ues-work", ":(exclude).ues-learning", ":(exclude).ues-dashboard", ":(exclude).ues-sandboxes"],
+    ["status", "--porcelain=v1", "--untracked-files=all", "--", ".", ":(exclude).ues-work", ":(exclude).ues-learning", ":(exclude).ues-dashboard", ":(exclude).ues-sandboxes", ":(exclude).ues-cache", ":(exclude).ues-traces"],
+    ["diff", "--binary", "--no-ext-diff", "--", ".", ":(exclude).ues-work", ":(exclude).ues-learning", ":(exclude).ues-dashboard", ":(exclude).ues-sandboxes", ":(exclude).ues-cache", ":(exclude).ues-traces"],
+    ["diff", "--cached", "--binary", "--no-ext-diff", "--", ".", ":(exclude).ues-work", ":(exclude).ues-learning", ":(exclude).ues-dashboard", ":(exclude).ues-sandboxes", ":(exclude).ues-cache", ":(exclude).ues-traces"],
   ]
   for (const args of commands) {
     const result = gitCapture(root, args)
@@ -163,6 +284,7 @@ export async function initWork(root, slug, goal) {
     tasks: {},
     decisions: [],
     blockers: [],
+    checkpoint: null,
     nextAction: "Complete SPEC.md, create PLAN.json, then run ocskill work plan.",
   })
   await writeJson(paths.evidence, {
@@ -171,7 +293,9 @@ export async function initWork(root, slug, goal) {
     updatedAt: createdAt,
     entries: [],
     receipts: [],
+    gateReceipts: [],
   })
+  await journal(paths, "work.init", { goal: cleanGoal })
 
   return { ...paths, slug, goal: cleanGoal }
 }
@@ -185,6 +309,24 @@ export async function loadWork(root, slug) {
   return { paths, state, plan, evidence }
 }
 
+function evidencePolicyForPlan(plan) {
+  const tasks = Array.isArray(plan?.tasks) ? plan.tasks : []
+  const highRisk = tasks.some((task) => ["high", "critical"].includes(task?.risk))
+  const longHorizon = tasks.length > 1 || plan?.mode === "long-horizon" || plan?.longHorizon === true
+  return {
+    schemaVersion: 1,
+    strict: highRisk || longHorizon,
+    receiptRequiredForTasks: highRisk || longHorizon,
+    structuredPlanApproval: highRisk || longHorizon,
+    structuredIntegrationApproval: highRisk || longHorizon,
+    reason: highRisk ? "high-risk-plan" : longHorizon ? "long-horizon-plan" : "standard-plan",
+  }
+}
+
+function currentEvidencePolicy(state, plan) {
+  return state?.evidencePolicy || evidencePolicyForPlan(plan)
+}
+
 function taskBrief(task) {
   const files = taskFiles(task)
   return `# ${task.id}: ${task.title}\n\n## Summary\n\n${task.summary || "No summary provided."}\n\n## Dependencies\n\n${(task.dependsOn || []).map((id) => `- ${id}`).join("\n") || "- None"}\n\n## Files\n\n${files.map((file) => `- ${file}`).join("\n") || "- Scope must be established before editing."}\n\n## Acceptance criteria\n\n${(task.acceptance || []).map((item) => `- ${item}`).join("\n")}\n\n## Verification\n\n${(task.verification || []).map((item) => `- ${item}`).join("\n")}\n\n## Risk\n\n${task.risk || "medium"}\n`
@@ -246,17 +388,22 @@ export async function importPlan(root, slug, planInput) {
       planHash: hash,
       planApproval: { status: "pending", planHash: hash, at: updatedAt, evidence: null },
       integrationVerification: null,
+      checkpoint: null,
+      evidencePolicy: evidencePolicyForPlan(plan),
       tasks: stateTasks,
       nextAction: "Run ues-plan-checker, then record PASS with 'ocskill work approve-plan'.",
     }
     await writeJson(loaded.paths.state, state)
+    await journal(loaded.paths, "plan.imported", {
+      planHash: hash,
+      taskCount: plan.tasks.length,
+    })
     return { plan, analysis, state, paths: loaded.paths }
   })
 }
 
-export async function approvePlan(root, slug, evidence) {
-  const evidenceText = String(evidence || "").trim()
-  if (!evidenceText) throw new Error("plan approval requires non-empty plan-checker evidence")
+export async function approvePlan(root, slug, evidence, options = {}) {
+  const evidenceText = String(evidence || options.receipt?.evidence || "").trim()
 
   return withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
@@ -266,14 +413,43 @@ export async function approvePlan(root, slug, evidence) {
       throw new Error("PLAN.json changed after import; re-import it before approval")
     }
 
+    const policy = currentEvidencePolicy(loaded.state, loaded.plan)
+    let receipt = options.receipt || null
+    if (receipt) {
+      const validation = validateGateReceipt(receipt)
+      if (!validation.valid) {
+        const error = new Error("invalid plan verification receipt")
+        error.validation = validation
+        throw error
+      }
+      if (receipt.kind !== "plan-verification") throw new Error("plan approval requires a plan-verification receipt")
+      if (receipt.slug !== slug) throw new Error("plan verification receipt slug mismatch")
+      if (receipt.verdict !== "PASS") throw new Error("plan verification receipt must record PASS")
+      if (receipt.planHash !== hash) throw new Error("plan verification receipt planHash mismatch")
+    } else if (policy.structuredPlanApproval) {
+      throw new Error("strict plan approval requires a structured plan-verification receipt")
+    }
+
+    if (!evidenceText) throw new Error("plan approval requires non-empty plan-checker evidence")
+
     const timestamp = now()
     loaded.state.schemaVersion = STATE_SCHEMA
     loaded.state.planHash = hash
+    loaded.state.evidencePolicy = policy
     loaded.state.planApproval = {
       status: "passed",
       planHash: hash,
       at: timestamp,
       evidence: evidenceText,
+      receipt: receipt || null,
+    }
+    if (receipt) {
+      loaded.evidence.gateReceipts ??= []
+      if (!loaded.evidence.gateReceipts.some((item) => item.id === receipt.id)) {
+        loaded.evidence.gateReceipts.push({ ...receipt, recordedAt: timestamp })
+      }
+      loaded.evidence.updatedAt = timestamp
+      await writeJson(loaded.paths.evidence, loaded.evidence)
     }
     loaded.state.status = "ready"
     loaded.state.updatedAt = timestamp
@@ -282,6 +458,12 @@ export async function approvePlan(root, slug, evidence) {
       ? `Execute ready task(s): ${next.join(", ")}`
       : "No executable task; inspect dependencies and blockers."
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "plan.approved", {
+      planHash: hash,
+      ready: next,
+      structured: Boolean(receipt),
+      receiptId: receipt?.id || null,
+    })
     return { planHash: hash, approval: loaded.state.planApproval, ready: next }
   })
 }
@@ -309,7 +491,7 @@ export function readyTasks(plan, state) {
   const ready = []
   for (const task of plan.tasks) {
     const status = state.tasks?.[task.id]?.status
-    if (!["pending", "failed"].includes(status)) continue
+    if (!["pending", "failed", "retryable"].includes(status)) continue
     if (!(task.dependsOn || []).every((dep) => completed.has(dep))) continue
     const files = taskFiles(task)
     if (files.length === 0 && runningFiles.size > 0) continue
@@ -321,7 +503,7 @@ export function readyTasks(plan, state) {
 
 export async function workStatus(root, slug) {
   const loaded = await loadWork(root, slug)
-  const counts = { pending: 0, running: 0, completed: 0, failed: 0 }
+  const counts = { pending: 0, running: 0, completed: 0, failed: 0, retryable: 0 }
   for (const value of Object.values(loaded.state.tasks || {})) {
     if (Object.hasOwn(counts, value.status)) counts[value.status] += 1
   }
@@ -331,6 +513,9 @@ export async function workStatus(root, slug) {
       taskID,
       runId: value.runId || null,
       attempts: value.attempts || 0,
+      sessionID: value.owner?.sessionID || null,
+      executionDir: value.owner?.executionDir || null,
+      sandboxDir: value.owner?.sandboxDir || null,
       heartbeatAt: value.heartbeatAt || null,
       leaseExpiresAt: value.leaseExpiresAt || null,
     }))
@@ -355,8 +540,10 @@ export async function workStatus(root, slug) {
       completed,
       coverage: completed ? receiptBacked / completed : 0,
       receipts: (loaded.evidence.receipts || []).length,
+      gateReceipts: (loaded.evidence.gateReceipts || []).length,
     },
     nextAction: loaded.state.nextAction,
+    checkpoint: loaded.state.checkpoint || null,
     updatedAt: loaded.state.updatedAt,
   }
 }
@@ -396,6 +583,13 @@ export async function startTask(root, slug, taskID, options = {}) {
     loaded.state.updatedAt = timestamp
     loaded.state.nextAction = `Complete ${taskID}, write its report, then record fresh verification evidence.`
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "task.started", {
+      task: taskID,
+      runId: record.runId,
+      attempt: record.attempts,
+      owner: record.owner,
+      leaseExpiresAt: record.leaseExpiresAt,
+    })
     return { task, record: { ...record } }
   })
 
@@ -405,11 +599,46 @@ export async function startTask(root, slug, taskID, options = {}) {
 
 function assertRunFence(record, options = {}) {
   const runId = options.runId || null
-  if (runId && record.runId && runId !== record.runId) {
+  if (record.runId && !runId) {
+    throw new Error("task run fence requires the active runId")
+  }
+  if (runId && record.runId !== runId) {
     throw new Error("task run fence mismatch; the executor lease is stale")
   }
 }
 
+export async function attachTaskSession(root, slug, taskID, runId, sessionID, options = {}) {
+  const value = String(sessionID || "").trim()
+  if (!value) throw new Error("sessionID is required")
+  return withWorkLock(root, slug, async () => {
+    const loaded = await loadWork(root, slug)
+    const record = loaded.state.tasks?.[taskID]
+    if (!record) throw new Error(`task '${taskID}' is not tracked`)
+    if (record.status !== "running") throw new Error(`task '${taskID}' is not running`)
+    assertRunFence(record, { runId })
+    record.owner ??= { pid: process.pid, sessionID: null }
+    record.owner.sessionID = value
+    record.owner.executionDir = options.executionDir ? path.resolve(options.executionDir) : null
+    record.owner.sandboxDir = options.sandboxDir ? path.resolve(options.sandboxDir) : null
+    loaded.state.updatedAt = now()
+    await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "task.session-attached", {
+      task: taskID,
+      runId: record.runId,
+      sessionID: value,
+      executionDir: record.owner.executionDir,
+      sandboxDir: record.owner.sandboxDir,
+    })
+    return {
+      taskID,
+      runId: record.runId,
+      sessionID: value,
+      executionDir: record.owner.executionDir,
+      sandboxDir: record.owner.sandboxDir,
+    }
+  })
+}
+
 export async function heartbeatTask(root, slug, taskID, runId, options = {}) {
   return withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
@@ -423,10 +652,54 @@ export async function heartbeatTask(root, slug, taskID, runId, options = {}) {
     record.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString()
     loaded.state.updatedAt = timestamp
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "task.heartbeat", {
+      task: taskID,
+      runId: record.runId,
+      heartbeatAt: record.heartbeatAt,
+      leaseExpiresAt: record.leaseExpiresAt,
+    })
     return { taskID, runId: record.runId, heartbeatAt: record.heartbeatAt, leaseExpiresAt: record.leaseExpiresAt }
   })
 }
 
+export async function recoverTask(root, slug, taskID, options = {}) {
+  return withWorkLock(root, slug, async () => {
+    const loaded = await loadWork(root, slug)
+    const record = loaded.state.tasks?.[taskID]
+    if (!record) throw new Error(`task '${taskID}' is not tracked`)
+    if (record.status !== "running") throw new Error(`task '${taskID}' is not running`)
+
+    const expires = Date.parse(record.leaseExpiresAt || "")
+    const stale = options.force || !Number.isFinite(expires) || expires <= Date.now()
+    if (!stale) throw new Error(`task '${taskID}' lease is still active`)
+
+    const timestamp = now()
+    const previousOwner = record.owner ? { ...record.owner } : null
+    const previousRunId = record.runId || null
+    record.status = "retryable"
+    record.lastFailure = String(options.reason || "stale executor lease recovered after interruption")
+    record.lastOwner = previousOwner
+    record.lastRunId = previousRunId
+    record.runId = null
+    record.owner = null
+    record.heartbeatAt = null
+    record.leaseExpiresAt = null
+
+    loaded.state.integrationVerification = null
+    loaded.state.status = "executing"
+    loaded.state.updatedAt = timestamp
+    loaded.state.nextAction = `Recovered stale task ${taskID}. Re-diagnose and retry from fresh evidence.`
+    await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "task.recovered", {
+      tasks: [taskID],
+      previousRunId,
+      previousOwner,
+      forced: Boolean(options.force),
+    })
+    return { recovered: [taskID], previousRunId, previousOwner, state: loaded.state }
+  })
+}
+
 export async function recoverStaleTasks(root, slug, options = {}) {
   return withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
@@ -437,8 +710,12 @@ export async function recoverStaleTasks(root, slug, options = {}) {
       const expires = Date.parse(record.leaseExpiresAt || "")
       const stale = options.force || !Number.isFinite(expires) || expires <= Date.now()
       if (!stale) continue
-      record.status = "failed"
+      const previousOwner = record.owner ? { ...record.owner } : null
+      const previousRunId = record.runId || null
+      record.status = "retryable"
       record.lastFailure = "stale executor lease recovered after interruption"
+      record.lastOwner = previousOwner
+      record.lastRunId = previousRunId
       record.runId = null
       record.owner = null
       record.heartbeatAt = null
@@ -451,6 +728,7 @@ export async function recoverStaleTasks(root, slug, options = {}) {
       loaded.state.updatedAt = timestamp
       loaded.state.nextAction = `Recovered stale task(s): ${recovered.join(", ")}. Re-diagnose and retry from fresh evidence.`
       await writeJson(loaded.paths.state, loaded.state)
+      await journal(loaded.paths, "task.recovered", { tasks: recovered })
     }
     return { recovered, state: loaded.state }
   })
@@ -481,6 +759,12 @@ export async function recordVerificationReceipt(root, slug, taskID, receipt) {
     loaded.evidence.schemaVersion = STATE_SCHEMA
     loaded.evidence.updatedAt = normalized.recordedAt
     await writeJson(loaded.paths.evidence, loaded.evidence)
+    await journal(loaded.paths, "verification.receipt", {
+      task: taskID,
+      runId: record.runId,
+      receiptId: normalized.id,
+      passed: normalized.passed,
+    })
     return normalized
   })
 }
@@ -499,18 +783,31 @@ export async function completeTask(root, slug, taskID, options = {}) {
     assertRunFence(record, options)
 
     const timestamp = now()
+    const receipts = (loaded.evidence.receipts || []).filter((item) => item.task === taskID && (!record.runId || item.runId === record.runId))
+    const successfulReceipts = receipts.filter((item) => item.passed)
+    const evidencePolicy = currentEvidencePolicy(loaded.state, loaded.plan)
+    const currentFingerprint = workspaceFingerprint(loaded.paths.root)
+    const freshSuccessfulReceipts = successfulReceipts.filter(
+      (item) => item.workspaceAfter && item.workspaceAfter === currentFingerprint,
+    )
+    if (evidencePolicy.receiptRequiredForTasks && freshSuccessfulReceipts.length === 0) {
+      throw new Error("strict task completion requires a successful verification receipt for the active run and current workspace fingerprint")
+    }
+
+    const acceptedReceipts = evidencePolicy.receiptRequiredForTasks
+      ? freshSuccessfulReceipts
+      : successfulReceipts
+
     const reportPath = path.join(loaded.paths.reports, `${taskID}.md`)
     if (options.report) await atomicWrite(reportPath, String(options.report).trimEnd() + "\n")
     else if (!existsSync(reportPath)) {
       await atomicWrite(reportPath, `# ${taskID} report\n\nCompleted with evidence recorded in EVIDENCE.json.\n`)
     }
 
-    const receipts = (loaded.evidence.receipts || []).filter((item) => item.task === taskID && (!record.runId || item.runId === record.runId))
-    const successfulReceipts = receipts.filter((item) => item.passed)
     record.status = "completed"
     record.completedAt = timestamp
     record.report = path.relative(loaded.paths.root, reportPath).replaceAll("\\", "/")
-    record.evidenceStrength = successfulReceipts.length ? "receipt-backed" : "narrative"
+    record.evidenceStrength = acceptedReceipts.length ? "receipt-backed" : "narrative"
     record.runId = null
     record.owner = null
     record.heartbeatAt = null
@@ -522,7 +819,7 @@ export async function completeTask(root, slug, taskID, options = {}) {
       evidence: evidenceText,
       verification: task.verification,
       evidenceStrength: record.evidenceStrength,
-      receiptIDs: successfulReceipts.map((item) => item.id),
+      receiptIDs: acceptedReceipts.map((item) => item.id),
     })
     loaded.evidence.schemaVersion = STATE_SCHEMA
     loaded.evidence.updatedAt = timestamp
@@ -540,6 +837,11 @@ export async function completeTask(root, slug, taskID, options = {}) {
 
     await writeJson(loaded.paths.evidence, loaded.evidence)
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "task.completed", {
+      task: taskID,
+      evidenceStrength: record.evidenceStrength,
+      receiptIDs: acceptedReceipts.map((item) => item.id),
+    })
     return { task, state: loaded.state, ready }
   })
 }
@@ -554,6 +856,7 @@ export async function failTask(root, slug, taskID, reason, options = {}) {
     taskByID(loaded.plan, taskID)
     const record = loaded.state.tasks?.[taskID]
     if (!record) throw new Error(`task '${taskID}' is not tracked`)
+    if (record.status !== "running") throw new Error(`task '${taskID}' must be running before it can fail`)
     assertRunFence(record, options)
 
     const timestamp = now()
@@ -570,6 +873,11 @@ export async function failTask(root, slug, taskID, reason, options = {}) {
       ? `Re-plan or escalate ${taskID}; it has failed ${record.attempts} attempt(s).`
       : `Re-diagnose ${taskID} from fresh evidence before retrying.`
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "task.failed", {
+      task: taskID,
+      attempts: record.attempts,
+      reason: cleanReason,
+    })
     return { taskID, attempts: record.attempts, state: loaded.state }
   })
 }
@@ -627,12 +935,12 @@ export async function resolveBlocker(root, slug, blocker) {
   })
 }
 
-export async function recordIntegrationVerification(root, slug, verdict, evidence, report = null) {
+export async function recordIntegrationVerification(root, slug, verdict, evidence, report = null, options = {}) {
   const status = String(verdict || "").trim().toUpperCase()
   if (!["PASS", "FAIL", "PARTIAL"].includes(status)) {
     throw new Error("integration verdict must be PASS, FAIL, or PARTIAL")
   }
-  const evidenceText = String(evidence || "").trim()
+  const evidenceText = String(evidence || options.receipt?.evidence || "").trim()
   if (!evidenceText) throw new Error("integration verification requires non-empty evidence")
 
   return withWorkLock(root, slug, async () => {
@@ -650,12 +958,37 @@ export async function recordIntegrationVerification(root, slug, verdict, evidenc
 
     const timestamp = now()
     const fingerprint = workspaceFingerprint(loaded.paths.root)
+    const policy = currentEvidencePolicy(loaded.state, loaded.plan)
+    const receipt = options.receipt || null
+    if (receipt) {
+      const validation = validateGateReceipt(receipt)
+      if (!validation.valid) {
+        const error = new Error("invalid integration verification receipt")
+        error.validation = validation
+        throw error
+      }
+      if (receipt.kind !== "integration-verification") throw new Error("integration verification requires an integration-verification receipt")
+      if (receipt.slug !== slug) throw new Error("integration verification receipt slug mismatch")
+      if (receipt.verdict !== status) throw new Error("integration verification receipt verdict mismatch")
+      if (receipt.workspaceFingerprint !== fingerprint) {
+        throw new Error("integration verification receipt workspace fingerprint mismatch")
+      }
+    } else if (status === "PASS" && policy.structuredIntegrationApproval) {
+      throw new Error("strict integration PASS requires a structured integration-verification receipt")
+    }
     loaded.state.integrationVerification = {
       status,
       at: timestamp,
       evidence: evidenceText,
       report: report ? String(report) : null,
       fingerprint,
+      receipt: receipt || null,
+    }
+    if (receipt) {
+      loaded.evidence.gateReceipts ??= []
+      if (!loaded.evidence.gateReceipts.some((item) => item.id === receipt.id)) {
+        loaded.evidence.gateReceipts.push({ ...receipt, recordedAt: timestamp })
+      }
     }
     loaded.state.updatedAt = timestamp
     loaded.state.status = status === "PASS" ? "ready-to-finalize" : "integration-verification"
@@ -676,6 +1009,11 @@ export async function recordIntegrationVerification(root, slug, verdict, evidenc
 
     await writeJson(loaded.paths.evidence, loaded.evidence)
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "integration.verified", {
+      verdict: status,
+      fingerprint,
+      receiptId: receipt?.id || null,
+    })
     return loaded.state.integrationVerification
   })
 }
@@ -720,6 +1058,7 @@ export async function finalizeWork(root, slug, evidence) {
 
     await writeJson(loaded.paths.evidence, loaded.evidence)
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "work.finalized", { fingerprint: currentFingerprint })
     return { state: loaded.state, evidence: loaded.evidence.entries.at(-1) }
   })
 }
@@ -736,7 +1075,34 @@ async function buildContextPack(loaded, taskID) {
     dependencyReports[dep] = (await readFile(file, "utf8")).slice(0, 12000)
   }
 
-  const contextManifest = await buildContextManifest(loaded.paths.root, task, { budget: 24_000 }).catch(() => null)
+  const taskText = [
+    task.title,
+    task.summary,
+    ...(task.acceptance || []),
+    ...(task.verification || []),
+  ].filter(Boolean).join(" ")
+  const contextPolicy = classifyEngineeringTask(taskText, {
+    changedFiles: taskFiles(task).length,
+    risk: task.risk,
+  })
+  const attempt = Math.max(1, Number(loaded.state.tasks?.[taskID]?.attempts || 1))
+  const recovery = recoveryPolicyForAttempt(contextPolicy, attempt)
+  const effectiveContextPolicy = {
+    ...contextPolicy,
+    contextBudget: recovery.contextBudget,
+    maxSkills: recovery.maxSkills,
+    effectiveContextBudget: recovery.contextBudget,
+    effectiveMaxSkills: recovery.maxSkills,
+    recovery,
+  }
+  const contextManifest = await buildContextManifest(
+    loaded.paths.root,
+    task,
+    {
+      budget: recovery.contextBudget,
+      strategy: recovery.contextStrategy,
+    },
+  ).catch(() => null)
   const learnings = await relevantAcceptedLearnings(
     loaded.paths.root,
     [task.title, task.summary, ...(task.acceptance || [])].join(" "),
@@ -744,6 +1110,8 @@ async function buildContextPack(loaded, taskID) {
 
   return {
     schemaVersion: STATE_SCHEMA,
+    contextPolicy: effectiveContextPolicy,
+    attempt,
     slug: loaded.state.slug,
     task,
     taskBrief: path.relative(loaded.paths.root, path.join(loaded.paths.tasks, `${taskID}.md`)).replaceAll("\\", "/"),
@@ -757,14 +1125,174 @@ async function buildContextPack(loaded, taskID) {
     workingState: {
       status: loaded.state.status,
       task: loaded.state.tasks?.[taskID],
+      checkpoint: loaded.state.checkpoint || null,
     },
   }
 }
 
+export async function createPlanVerificationReceipt(root, slug, input = {}) {
+  const loaded = await loadWork(root, slug)
+  if (!loaded.plan) throw new Error("PLAN.json is missing")
+  const hash = planHash(loaded.plan)
+  return createGateReceipt({
+    kind: "plan-verification",
+    slug,
+    verdict: input.verdict || "PASS",
+    verifier: input.verifier || "ues-plan-checker",
+    sessionID: input.sessionID || null,
+    runId: input.runId || null,
+    planHash: hash,
+    evidence: input.evidence,
+    report: input.report,
+  })
+}
+
+export async function createIntegrationVerificationReceipt(root, slug, input = {}) {
+  await loadWork(root, slug)
+  return createGateReceipt({
+    kind: "integration-verification",
+    slug,
+    verdict: input.verdict || "PASS",
+    verifier: input.verifier || "ues-integration-verifier",
+    sessionID: input.sessionID || null,
+    runId: input.runId || null,
+    workspaceFingerprint: workspaceFingerprint(root),
+    evidence: input.evidence,
+    report: input.report,
+  })
+}
+
 export async function contextPack(root, slug, taskID) {
   return buildContextPack(await loadWork(root, slug), taskID)
 }
 
+function checkpointEvidencePointers(evidence = {}) {
+  const pointers = []
+  for (const entry of (evidence.entries || []).slice(-12)) {
+    pointers.push({
+      kind: "evidence-entry",
+      task: entry.task || null,
+      at: entry.at || entry.recordedAt || null,
+      runId: entry.runId || null,
+    })
+  }
+  for (const receipt of (evidence.receipts || []).slice(-12)) {
+    pointers.push({
+      kind: "verification-receipt",
+      id: receipt.id || null,
+      task: receipt.task || null,
+      runId: receipt.runId || null,
+      verdict: receipt.verdict || null,
+    })
+  }
+  for (const receipt of (evidence.gateReceipts || []).slice(-8)) {
+    pointers.push({
+      kind: "gate-receipt",
+      id: receipt.id || null,
+      receiptKind: receipt.kind || null,
+      verdict: receipt.verdict || null,
+    })
+  }
+  return pointers.slice(-24)
+}
+
+function checkpointNextAction(loaded, taskID, runId) {
+  const record = taskID ? loaded.state.tasks?.[taskID] : null
+  if (record?.status === "running") {
+    return {
+      type: "continue-task",
+      taskId: taskID,
+      runId: runId || record.runId || null,
+      instruction: "Continue the active scoped task from durable evidence; execute the next required tool/action before narrative summary.",
+    }
+  }
+
+  const ready = readyTasks(loaded.plan, loaded.state)
+  if (ready.length) {
+    const nextTask = ready[0]
+    return {
+      type: "dispatch-task",
+      taskId: nextTask,
+      attempt: Number(loaded.state.tasks?.[nextTask]?.attempts || 0) + 1,
+      instruction: "Dispatch the next ready task in a fresh executor from .ues-work.",
+    }
+  }
+
+  return {
+    type: "inspect-state",
+    instruction: loaded.state.nextAction || "Inspect durable work state and choose the next deterministic action.",
+  }
+}
+
+export async function checkpointWork(root, slug, options = {}) {
+  return withWorkLock(root, slug, async () => {
+    const loaded = await loadWork(root, slug)
+    const taskID = String(options.taskID || "").trim() ||
+      Object.entries(loaded.state.tasks || {}).find(([, value]) => value.status === "running")?.[0] ||
+      null
+    const record = taskID ? loaded.state.tasks?.[taskID] : null
+    if (taskID && !record) throw new Error(`task '${taskID}' is not tracked`)
+    if (record?.status === "running") assertRunFence(record, { runId: options.runId || null })
+
+    const timestamp = now()
+    const checkpoint = {
+      schemaVersion: 1,
+      reason: String(options.reason || "runtime-checkpoint"),
+      createdAt: timestamp,
+      currentTaskId: taskID,
+      runId: record?.runId || options.runId || null,
+      planHash: loaded.plan ? planHash(loaded.plan) : loaded.state.planHash || null,
+      nextAction: checkpointNextAction(loaded, taskID, record?.runId || options.runId || null),
+      workspaceFingerprint: workspaceFingerprint(loaded.paths.root),
+      evidencePointers: checkpointEvidencePointers(loaded.evidence),
+      resumedAt: null,
+    }
+
+    loaded.state.schemaVersion = STATE_SCHEMA
+    loaded.state.checkpoint = checkpoint
+    loaded.state.updatedAt = timestamp
+    await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "work.checkpoint", {
+      task: taskID,
+      runId: checkpoint.runId,
+      planHash: checkpoint.planHash,
+      reason: checkpoint.reason,
+      nextAction: checkpoint.nextAction,
+    })
+    return checkpoint
+  })
+}
+
+export async function markCheckpointResumed(root, slug, options = {}) {
+  return withWorkLock(root, slug, async () => {
+    const loaded = await loadWork(root, slug)
+    const checkpoint = loaded.state.checkpoint
+    if (!checkpoint) return null
+    if (options.taskID && checkpoint.currentTaskId && checkpoint.currentTaskId !== options.taskID) {
+      throw new Error("checkpoint task mismatch")
+    }
+    if (checkpoint.runId && options.runId && checkpoint.runId !== options.runId) {
+      throw new Error("checkpoint runId mismatch")
+    }
+    const timestamp = now()
+    checkpoint.resumedAt = timestamp
+    checkpoint.resumeReason = String(options.reason || "deterministic-action-observed")
+    loaded.state.updatedAt = timestamp
+    await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "work.checkpoint-resumed", {
+      task: checkpoint.currentTaskId || null,
+      runId: checkpoint.runId || null,
+      reason: checkpoint.resumeReason,
+    })
+    return checkpoint
+  })
+}
+
+export async function runtimeEvents(root, slug, options = {}) {
+  const paths = workPaths(root, slug)
+  return readRuntimeEvents(paths.events, options)
+}
+
 export async function resumeWork(root, slug) {
   await recoverStaleTasks(root, slug).catch(() => ({ recovered: [] }))
   const loaded = await loadWork(root, slug)
@@ -773,5 +1301,6 @@ export async function resumeWork(root, slug) {
     planAnalysis: loaded.plan ? analyzePlan(loaded.plan) : null,
     completedEvidence: loaded.evidence.entries || [],
     decisions: loaded.state.decisions || [],
+    recentEvents: await readRuntimeEvents(loaded.paths.events, { limit: 50 }),
   }
 }