opencode-agent-skill 7.7.0 → 10.0.0

package/bin/ocskill.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs"
+import { writeFileSync } from "node:fs"
 import { spawnSync } from "node:child_process"
 import { fileURLToPath } from "node:url"
 import path from "node:path"
@@ -15,6 +15,7 @@ import {
 import { compareVersions } from "../lib/version.mjs"
 import { resolveLatestPublishedVersion } from "../lib/update-resolver.mjs"
 import { readRouterConfig, writeRouterConfig } from "../lib/router-config.mjs"
+import { resolveWindowsCommand } from "../lib/windows-shim.mjs"
 import {
   detectStack,
   detectTestCommands,
@@ -24,10 +25,15 @@ import {
   checkWorkingTree,
 } from "../lib/repo-inspect.mjs"
 import { buildRepoGraph } from "../lib/repo-graph.mjs"
+import { buildSemanticIndex, semanticIndexStatus } from "../lib/semantic-index.mjs"
+import { aciReferences, aciSearch, aciTextSearch, aciView } from "../lib/aci.mjs"
+import { appendTrajectoryEvent, readTrajectory } from "../lib/trajectory.mjs"
+import { containerSandboxCapability, runContainerSandbox } from "../lib/container-sandbox.mjs"
 import { analyzePlan } from "../lib/task-graph.mjs"
 import {
   addBlocker,
   addDecision,
+  attachTaskSession,
   approvePlan,
   completeTask,
   contextPack,
@@ -42,18 +48,34 @@ import {
   workStatus,
   heartbeatTask,
   recoverStaleTasks,
+  recoverTask,
   recordVerificationReceipt,
   workspaceFingerprint,
+  createPlanVerificationReceipt,
+  createIntegrationVerificationReceipt,
+  runtimeEvents,
+  checkpointWork,
+  markCheckpointResumed,
 } from "../lib/task-engine.mjs"
 import { reviewScope } from "../lib/review-scope.mjs"
 import { buildVerificationPlan } from "../lib/verification-plan.mjs"
 import { resolveAdaptiveModel, resolveModel } from "../lib/model-policy.mjs"
 import { createVerificationReceipt } from "../lib/evidence-receipt.mjs"
 import { classifyEngineeringTask } from "../lib/orchestrator-policy.mjs"
-import { createTaskSandbox, listTaskSandboxes, removeTaskSandbox } from "../lib/worktree-sandbox.mjs"
-import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning } from "../lib/learning-engine.mjs"
+import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskSandbox } from "../lib/worktree-sandbox.mjs"
+import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning, promoteLearning } from "../lib/learning-engine.mjs"
 import { hermesStatus, buildHermesDelegationPrompt, hermesOneShotArgs } from "../lib/hermes-bridge.mjs"
 import { readModelPolicy, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
+import {
+  clipOutput,
+  errorMessage,
+  optionInt,
+  optionIntOrUndefined,
+  optionValue,
+  positionalArg,
+  readJsonFile,
+  readTextFile,
+} from "../lib/cli-utils.mjs"
 
 const args = process.argv.slice(2)
 const command = args[0] || "help"
@@ -76,6 +98,11 @@ Usage:
   ocskill evidence [dir]       Collect stack, verification and Git evidence
   ocskill working-tree [dir]   Report Git branch/HEAD/dirty state
   ocskill repo-graph [dir]      Build a bounded source import/dependency graph
+  ocskill index <status|build|rebuild> [dir]
+                              Build/reuse the persistent incremental semantic index
+  ocskill aci <search|refs|view|text> ...
+                              Bounded evidence-first code search/view interface
+  ocskill trace <show|append> ... Inspect or append redacted operational trajectory events
   ocskill review-scope [base] [dir]
                               Enumerate changed files, review coverage and risk
   ocskill verification-plan [dir]
@@ -87,8 +114,9 @@ Usage:
   ocskill model-policy <role> [--attempt N]
                               Resolve light/standard/heavy escalation tier
   ocskill task-policy <text>    Classify task mode/risk/context/model tier
-  ocskill sandbox <action> ...  Manage isolated Git worktree task sandboxes
-  ocskill learn <action> ...    Analyze eval traces and promote accepted lessons
+  ocskill sandbox <action> ...  Create, integrate and clean isolated Git worktree sandboxes
+                              Also supports capability/exec for fail-closed container verification
+  ocskill learn <action> ...    Analyze eval traces and promote benchmark-validated lessons
   ocskill hermes <action> ...   Optional Hermes adapter/status
   ocskill dashboard [dir] [--serve] [--port N]
                               Generate/serve the local UES Control Center
@@ -105,16 +133,20 @@ Usage:
     ocskill work init <slug> [dir] --goal <text>
     ocskill work plan <slug> <plan.json> [dir]
     ocskill work status|resume <slug> [dir]
-    ocskill work approve-plan <slug> [dir] --evidence <plan-checker-evidence>
+    ocskill work gate-receipt <slug> <plan|integration> [dir] --evidence <text> [--verdict PASS|FAIL|PARTIAL] [--verifier <role>] [--session-id <id>] [--report-file <file>] [--out <file>]
+    ocskill work approve-plan <slug> [dir] --evidence <plan-checker-evidence> [--receipt-file <file>]
     ocskill work start <slug> <task-id> [dir] [--lease-ms N]
-    ocskill work heartbeat <slug> <task-id> [dir] [--run-id <id>]
+    ocskill work attach-session <slug> <task-id> [dir] --run-id <id> --session-id <id> [--execution-dir <dir>] [--sandbox-dir <dir>]
+    ocskill work heartbeat <slug> <task-id> [dir] --run-id <id>
     ocskill work recover <slug> [dir] [--force]
-    ocskill work verify-command <slug> <task-id> [dir] [--run-id <id>] -- <command> [args...]
-    ocskill work complete <slug> <task-id> [dir] --evidence <text> [--report-file <file>] [--run-id <id>]
-    ocskill work fail <slug> <task-id> [dir] --reason <text> [--run-id <id>]
+    ocskill work recover-task <slug> <task-id> [dir] [--force] [--reason <text>]
+    ocskill work events <slug> [dir] [--limit N]
+    ocskill work verify-command <slug> <task-id> [dir] --run-id <id> -- <command> [args...]
+    ocskill work complete <slug> <task-id> [dir] --run-id <id> --evidence <text> [--report-file <file>]
+    ocskill work fail <slug> <task-id> [dir] --run-id <id> --reason <text>
     ocskill work decision <slug> [dir] --text <decision>
     ocskill work block|unblock <slug> [dir] --text <blocker>
-    ocskill work verify-integration <slug> [dir] --verdict PASS|FAIL|PARTIAL --evidence <text> [--report-file <file>]
+    ocskill work verify-integration <slug> [dir] --verdict PASS|FAIL|PARTIAL --evidence <text> [--report-file <file>] [--receipt-file <file>]
     ocskill work finalize <slug> [dir] --evidence <integration-evidence>
 
   Model routing:
@@ -127,38 +159,6 @@ Usage:
 `)
 }
 
-function findWindowsCommand(name) {
-  if (path.isAbsolute(name) && existsSync(name)) return name
-
-  const result = spawnSync("where", [name], { encoding: "utf8" })
-  if (result.status !== 0 || !result.stdout) return null
-
-  const matches = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
-  return matches.find((item) => /\.(cmd|bat)$/i.test(item)) || matches[0] || null
-}
-
-function quoteCmd(value) {
-  if (/^[A-Za-z0-9_@%+=:,./\\-]+$/.test(value)) return value
-  return `"${value.replaceAll('"', '""')}"`
-}
-
-function findNodeShimEntry(cmdPath) {
-  const dir = path.dirname(cmdPath)
-
-  if (/^npm(?:\.cmd|\.exe)?$/i.test(path.basename(cmdPath))) {
-    const entry = path.join(dir, "node_modules", "npm", "bin", "npm-cli.js")
-    if (existsSync(entry)) return entry
-  }
-
-  let shim = ""
-  try {
-    shim = readFileSync(cmdPath, "utf8")
-  } catch {}
-  const match = shim.match(/node_modules[\\/][^\s"]+?\.(?:js|mjs)/gi)?.at(-1)
-  if (!match) return null
-  const entry = path.resolve(dir, match)
-  return existsSync(entry) ? entry : null
-}
 
 function run(executable, commandArgs, options = {}) {
   const common = { stdio: "inherit", ...options }
@@ -168,26 +168,22 @@ function run(executable, commandArgs, options = {}) {
     return result.status ?? 1
   }
 
-  const resolved = findWindowsCommand(executable)
-  if (!resolved) return 127
-
-  if (/\.(cmd|bat)$/i.test(resolved)) {
-    const entry = findNodeShimEntry(resolved)
-    if (entry) {
-      const result = spawnSync(process.execPath, [entry, ...commandArgs], common)
-      return result.status ?? 1
-    }
-    const line = [resolved, ...commandArgs].map(quoteCmd).join(" ")
-    const result = spawnSync(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", line], common)
-    return result.status ?? 1
+  const resolved = resolveWindowsCommand(executable)
+  if (!resolved) {
+    console.error("[ocskill] No safely executable Windows command found for: " + executable)
+    return 127
   }
 
-  const result = spawnSync(resolved, commandArgs, common)
+  const result = spawnSync(
+    resolved.executable,
+    [...resolved.argsPrefix, ...commandArgs],
+    common,
+  )
   return result.status ?? 1
 }
 
 function hasCommand(name) {
-  if (process.platform === "win32") return findWindowsCommand(name) !== null
+  if (process.platform === "win32") return resolveWindowsCommand(name) !== null
   return spawnSync("which", [name], { stdio: "ignore" }).status === 0
 }
 
@@ -198,22 +194,20 @@ function runCapture(executable, commandArgs, options = {}) {
     return spawnSync(executable, commandArgs, common)
   }
 
-  const resolved = findWindowsCommand(executable)
-  if (!resolved) return { status: 127, stdout: "", stderr: `Command not found: ${executable}` }
-
-  if (/\.(cmd|bat)$/i.test(resolved)) {
-    const entry = findNodeShimEntry(resolved)
-    if (entry) return spawnSync(process.execPath, [entry, ...commandArgs], common)
-
-    const line = [resolved, ...commandArgs].map(quoteCmd).join(" ")
-    return spawnSync(
-      process.env.ComSpec || "cmd.exe",
-      ["/d", "/s", "/c", line],
-      common,
-    )
+  const resolved = resolveWindowsCommand(executable)
+  if (!resolved) {
+    return {
+      status: 127,
+      stdout: "",
+      stderr: `No safely executable Windows command found for: ${executable}`,
+    }
   }
 
-  return spawnSync(resolved, commandArgs, common)
+  return spawnSync(
+    resolved.executable,
+    [...resolved.argsPrefix, ...commandArgs],
+    common,
+  )
 }
 
 
@@ -278,8 +272,12 @@ async function doctor() {
   console.log(`Node:     ${process.version}`)
   console.log(`Config:   ${getConfigDir()}`)
   console.log(`npm:      ${hasCommand("npm") ? "OK" : "MISSING"}`)
-  console.log(`OpenCode: ${hasCommand("opencode") ? "OK" : "MISSING"}`)
-  if (hasCommand("opencode")) run("opencode", ["--version"])
+  const openCodeAvailable = hasCommand("opencode")
+  console.log(`OpenCode: ${openCodeAvailable ? "OK" : "MISSING"}`)
+  if (openCodeAvailable) {
+    const code = run("opencode", ["--version"])
+    if (code !== 0) process.exitCode = code
+  }
   await status()
 }
 
@@ -309,7 +307,7 @@ async function evaluateReport() {
 }
 
 async function inspectRepository() {
-  printJson(await repoMap(args[1] || process.cwd()))
+  printJson(await repoMap(positionalArg(args, 1) || process.cwd()))
 }
 
 async function inspectImpact() {
@@ -319,42 +317,129 @@ async function inspectImpact() {
     process.exitCode = 2
     return
   }
-  printJson(await impactMap(args[2] || process.cwd(), query))
+  printJson(await impactMap(positionalArg(args, 2) || process.cwd(), query))
 }
 
 async function inspectEvidence() {
-  printJson(await collectEvidence(args[1] || process.cwd()))
+  printJson(await collectEvidence(positionalArg(args, 1) || process.cwd()))
 }
 
 async function inspectWorkingTree() {
-  printJson(await checkWorkingTree(args[1] || process.cwd()))
+  printJson(await checkWorkingTree(positionalArg(args, 1) || process.cwd()))
 }
 
 async function inspectStack() {
-  printJson(await detectStack(args[1] || process.cwd()))
+  printJson(await detectStack(positionalArg(args, 1) || process.cwd()))
 }
 
 async function inspectTests() {
-  printJson(await detectTestCommands(args[1] || process.cwd()))
+  printJson(await detectTestCommands(positionalArg(args, 1) || process.cwd()))
 }
 
-function optionValue(name) {
-  const index = args.indexOf(name)
-  return index >= 0 ? args[index + 1] : null
+async function inspectRepoGraph() {
+  printJson(await buildRepoGraph(positionalArg(args, 1) || process.cwd()))
 }
 
-async function inspectRepoGraph() {
-  printJson(await buildRepoGraph(args[1] || process.cwd()))
+async function semanticIndexControl() {
+  const action = args[1] || "status"
+  const root = positionalArg(args, 2) || process.cwd()
+  try {
+    if (action === "status") {
+      printJson(await semanticIndexStatus(root))
+      return
+    }
+    if (action === "build" || action === "rebuild") {
+      const built = await buildSemanticIndex(root, { rebuild: action === "rebuild" })
+      printJson({ action, stats: built.stats })
+      return
+    }
+    throw new Error("Usage: ocskill index <status|build|rebuild> [dir]")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function aciControl() {
+  const action = args[1]
+  try {
+    if (action === "search") {
+      const query = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!query) throw new Error("Usage: ocskill aci search <query> [dir] [--limit N]")
+      printJson(await aciSearch(root, query, { limit: optionInt(args, "--limit", 20) }))
+      return
+    }
+    if (action === "refs") {
+      const symbol = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!symbol) throw new Error("Usage: ocskill aci refs <symbol> [dir] [--limit N]")
+      printJson(await aciReferences(root, symbol, { limit: optionInt(args, "--limit", 40) }))
+      return
+    }
+    if (action === "view") {
+      const file = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!file) throw new Error("Usage: ocskill aci view <file> [dir] [--line N] [--lines N]")
+      printJson(await aciView(root, file, {
+        line: optionInt(args, "--line", 1),
+        startLine: optionInt(args, "--start-line", 0),
+        lines: optionInt(args, "--lines", 120),
+      }))
+      return
+    }
+    if (action === "text") {
+      const query = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!query) throw new Error("Usage: ocskill aci text <query> [dir] [--limit N]")
+      printJson(await aciTextSearch(root, query, { limit: optionInt(args, "--limit", 80) }))
+      return
+    }
+    throw new Error("Usage: ocskill aci <search|refs|view|text> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function traceControl() {
+  const action = args[1] || "show"
+  try {
+    if (action === "show") {
+      const traceID = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!traceID) throw new Error("Usage: ocskill trace show <trace-id> [dir] [--limit N]")
+      printJson(await readTrajectory(root, traceID, { limit: optionInt(args, "--limit", 200) }))
+      return
+    }
+    if (action === "append") {
+      const traceID = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      const type = optionValue(args, "--type")
+      const payload64 = optionValue(args, "--payload-b64")
+      if (!traceID || !type) throw new Error("Usage: ocskill trace append <trace-id> [dir] --type <type> [--payload-b64 <base64-json>]")
+      let payload = {}
+      if (payload64) {
+        payload = JSON.parse(Buffer.from(payload64, "base64").toString("utf8"))
+      }
+      printJson(await appendTrajectoryEvent(root, traceID, type, payload))
+      return
+    }
+    throw new Error("Usage: ocskill trace <show|append> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
 }
 
 async function inspectReviewScope() {
-  const base = args[1] && !args[1].startsWith("--") ? args[1] : null
-  const root = args[2] && !args[2].startsWith("--") ? args[2] : process.cwd()
+  const base = positionalArg(args, 1)
+  const root = positionalArg(args, 2) || process.cwd()
   printJson(reviewScope(root, base))
 }
 
 async function inspectVerificationPlan() {
-  printJson(await buildVerificationPlan(args[1] || process.cwd(), optionValue("--base")))
+  printJson(await buildVerificationPlan(positionalArg(args, 1) || process.cwd(), optionValue(args, "--base")))
 }
 
 async function inspectTaskGraph() {
@@ -365,12 +450,12 @@ async function inspectTaskGraph() {
     return
   }
   try {
-    const plan = JSON.parse(readFileSync(path.resolve(file), "utf8"))
+    const plan = readJsonFile(file)
     const analysis = analyzePlan(plan)
     printJson(analysis)
     if (!analysis.valid) process.exitCode = 1
   } catch (error) {
-    console.error(error instanceof Error ? error.message : error)
+    console.error(errorMessage(error))
     process.exitCode = 1
   }
 }
@@ -383,78 +468,166 @@ async function inspectContextPack() {
     process.exitCode = 2
     return
   }
-  printJson(await contextPack(args[3] || process.cwd(), slug, taskID))
+  printJson(await contextPack(positionalArg(args, 3) || process.cwd(), slug, taskID))
 }
 
 async function workControl() {
   const action = args[1]
   const slug = args[2]
   if (!action || !slug) {
-    console.error("Usage: ocskill work <init|plan|status|resume|approve-plan|start|heartbeat|recover|verify-command|complete|fail|decision|block|unblock|verify-integration|finalize> <slug> ...")
+    console.error("Usage: ocskill work <init|plan|status|resume|gate-receipt|approve-plan|start|attach-session|heartbeat|recover|recover-task|events|verify-command|complete|fail|decision|block|unblock|verify-integration|finalize> <slug> ...")
     process.exitCode = 2
     return
   }
 
   try {
     if (action === "init") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      printJson(await initWork(root, slug, optionValue("--goal")))
+      const root = positionalArg(args, 3) || process.cwd()
+      printJson(await initWork(root, slug, optionValue(args, "--goal")))
       return
     }
     if (action === "plan") {
       const planFile = args[3]
-      const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
+      const root = positionalArg(args, 4) || process.cwd()
       if (!planFile) throw new Error("Usage: ocskill work plan <slug> <plan.json> [dir]")
       const result = await importPlan(root, slug, planFile)
       printJson({ state: result.state, analysis: result.analysis, dir: result.paths.dir })
       return
     }
     if (action === "status") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
+      const root = positionalArg(args, 3) || process.cwd()
       printJson(await workStatus(root, slug))
       return
     }
     if (action === "resume") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
+      const root = positionalArg(args, 3) || process.cwd()
       printJson(await resumeWork(root, slug))
       return
     }
+    if (action === "gate-receipt") {
+      const kind = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!["plan", "integration"].includes(kind)) {
+        throw new Error("Usage: ocskill work gate-receipt <slug> <plan|integration> [dir] --evidence <text>")
+      }
+      const reportFile = optionValue(args, "--report-file")
+      const report = reportFile ? readTextFile(reportFile) : null
+      const input = {
+        verdict: optionValue(args, "--verdict") || "PASS",
+        verifier: optionValue(args, "--verifier") || undefined,
+        sessionID: optionValue(args, "--session-id"),
+        runId: optionValue(args, "--run-id"),
+        evidence: optionValue(args, "--evidence"),
+        report,
+      }
+      const receipt = kind === "plan"
+        ? await createPlanVerificationReceipt(root, slug, input)
+        : await createIntegrationVerificationReceipt(root, slug, input)
+      const outputFile = optionValue(args, "--out")
+      if (outputFile) {
+        const resolved = path.resolve(outputFile)
+        writeFileSync(resolved, JSON.stringify(receipt, null, 2) + "\n", "utf8")
+        printJson({ file: resolved, receipt })
+      } else {
+        printJson(receipt)
+      }
+      return
+    }
     if (action === "approve-plan") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      printJson(await approvePlan(root, slug, optionValue("--evidence")))
+      const root = positionalArg(args, 3) || process.cwd()
+      const receiptFile = optionValue(args, "--receipt-file")
+      const receipt = receiptFile ? readJsonFile(receiptFile) : null
+      printJson(await approvePlan(root, slug, optionValue(args, "--evidence"), { receipt }))
       return
     }
     if (action === "start") {
       const taskID = args[3]
-      const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
+      const root = positionalArg(args, 4) || process.cwd()
       if (!taskID) throw new Error("Usage: ocskill work start <slug> <task-id> [dir]")
       printJson(await startTask(root, slug, taskID, {
-        leaseMs: Number.parseInt(optionValue("--lease-ms") || "0", 10) || undefined,
+        leaseMs: optionIntOrUndefined(args, "--lease-ms"),
       }))
       return
     }
+    if (action === "attach-session") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!taskID) throw new Error("Usage: ocskill work attach-session <slug> <task-id> [dir] --run-id <id> --session-id <id>")
+      printJson(await attachTaskSession(
+        root,
+        slug,
+        taskID,
+        optionValue(args, "--run-id"),
+        optionValue(args, "--session-id"),
+        {
+          executionDir: optionValue(args, "--execution-dir"),
+          sandboxDir: optionValue(args, "--sandbox-dir"),
+        },
+      ))
+      return
+    }
     if (action === "heartbeat") {
       const taskID = args[3]
-      const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
-      if (!taskID) throw new Error("Usage: ocskill work heartbeat <slug> <task-id> [dir] [--run-id <id>]")
-      printJson(await heartbeatTask(root, slug, taskID, optionValue("--run-id"), {
-        leaseMs: Number.parseInt(optionValue("--lease-ms") || "0", 10) || undefined,
+      const root = positionalArg(args, 4) || process.cwd()
+      const runId = optionValue(args, "--run-id")
+      if (!taskID || !runId) throw new Error("Usage: ocskill work heartbeat <slug> <task-id> [dir] --run-id <id>")
+      printJson(await heartbeatTask(root, slug, taskID, runId, {
+        leaseMs: optionIntOrUndefined(args, "--lease-ms"),
       }))
       return
     }
     if (action === "recover") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
+      const root = positionalArg(args, 3) || process.cwd()
       printJson(await recoverStaleTasks(root, slug, { force: args.includes("--force") }))
       return
     }
+    if (action === "recover-task") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!taskID) throw new Error("Usage: ocskill work recover-task <slug> <task-id> [dir] [--force] [--reason <text>]")
+      printJson(await recoverTask(root, slug, taskID, {
+        force: args.includes("--force"),
+        reason: optionValue(args, "--reason"),
+      }))
+      return
+    }
+    if (action === "checkpoint") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!taskID) throw new Error("Usage: ocskill work checkpoint <slug> <task-id> [dir] --run-id <id> [--reason <text>]")
+      printJson(await checkpointWork(root, slug, {
+        taskID,
+        runId: optionValue(args, "--run-id"),
+        reason: optionValue(args, "--reason") || "pre-compaction",
+      }))
+      return
+    }
+    if (action === "checkpoint-resumed") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!taskID) throw new Error("Usage: ocskill work checkpoint-resumed <slug> <task-id> [dir] --run-id <id> [--reason <text>]")
+      printJson(await markCheckpointResumed(root, slug, {
+        taskID,
+        runId: optionValue(args, "--run-id"),
+        reason: optionValue(args, "--reason"),
+      }))
+      return
+    }
+    if (action === "events") {
+      const root = positionalArg(args, 3) || process.cwd()
+      const limit = optionInt(args, "--limit", 200)
+      printJson(await runtimeEvents(root, slug, { limit }))
+      return
+    }
     if (action === "verify-command") {
       const taskID = args[3]
-      const root = args[4] && args[4] !== "--" && !args[4].startsWith("--") ? args[4] : process.cwd()
+      const root = positionalArg(args, 4) || process.cwd()
       const separator = args.indexOf("--")
       const executable = separator >= 0 ? args[separator + 1] : null
       const commandArgs = separator >= 0 ? args.slice(separator + 2) : []
-      if (!taskID || !executable) {
-        throw new Error("Usage: ocskill work verify-command <slug> <task-id> [dir] [--run-id <id>] -- <command> [args...]")
+      const runId = optionValue(args, "--run-id")
+      if (!taskID || !runId || !executable) {
+        throw new Error("Usage: ocskill work verify-command <slug> <task-id> [dir] --run-id <id> -- <command> [args...]")
       }
       const startedAt = new Date().toISOString()
       const before = workspaceFingerprint(root)
@@ -465,7 +638,7 @@ async function workControl() {
       })
       const receipt = createVerificationReceipt({
         task: taskID,
-        runId: optionValue("--run-id"),
+        runId,
         command: executable,
         args: commandArgs,
         cwd: path.resolve(root),
@@ -479,15 +652,11 @@ async function workControl() {
         workspaceAfter: workspaceFingerprint(root),
       })
       const recorded = await recordVerificationReceipt(root, slug, taskID, receipt)
-      const clip = (value) => {
-        const text = String(value || "")
-        return text.length <= 8000 ? text : "...[truncated]\n" + text.slice(-8000)
-      }
       printJson({
         receipt: recorded,
         output: {
-          stdout: clip(result.stdout),
-          stderr: clip(result.stderr),
+          stdout: clipOutput(result.stdout),
+          stderr: clipOutput(result.stderr),
         },
       })
       if ((result.status ?? 1) !== 0) process.exitCode = result.status ?? 1
@@ -495,61 +664,66 @@ async function workControl() {
     }
     if (action === "complete") {
       const taskID = args[3]
-      const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
-      if (!taskID) throw new Error("Usage: ocskill work complete <slug> <task-id> [dir] --evidence <text>")
-      const reportFile = optionValue("--report-file")
-      const report = reportFile ? readFileSync(path.resolve(reportFile), "utf8") : null
+      const root = positionalArg(args, 4) || process.cwd()
+      const runId = optionValue(args, "--run-id")
+      if (!taskID || !runId) throw new Error("Usage: ocskill work complete <slug> <task-id> [dir] --run-id <id> --evidence <text>")
+      const reportFile = optionValue(args, "--report-file")
+      const report = reportFile ? readTextFile(reportFile) : null
       printJson(await completeTask(root, slug, taskID, {
-        evidence: optionValue("--evidence"),
+        evidence: optionValue(args, "--evidence"),
         report,
-        runId: optionValue("--run-id"),
+        runId,
       }))
       return
     }
     if (action === "fail") {
       const taskID = args[3]
-      const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
-      if (!taskID) throw new Error("Usage: ocskill work fail <slug> <task-id> [dir] --reason <text>")
-      printJson(await failTask(root, slug, taskID, optionValue("--reason"), { runId: optionValue("--run-id") }))
+      const root = positionalArg(args, 4) || process.cwd()
+      const runId = optionValue(args, "--run-id")
+      if (!taskID || !runId) throw new Error("Usage: ocskill work fail <slug> <task-id> [dir] --run-id <id> --reason <text>")
+      printJson(await failTask(root, slug, taskID, optionValue(args, "--reason"), { runId }))
       return
     }
     if (action === "decision") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      printJson(await addDecision(root, slug, optionValue("--text")))
+      const root = positionalArg(args, 3) || process.cwd()
+      printJson(await addDecision(root, slug, optionValue(args, "--text")))
       return
     }
     if (action === "block") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      printJson(await addBlocker(root, slug, optionValue("--text")))
+      const root = positionalArg(args, 3) || process.cwd()
+      printJson(await addBlocker(root, slug, optionValue(args, "--text")))
       return
     }
     if (action === "unblock") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      printJson(await resolveBlocker(root, slug, optionValue("--text")))
+      const root = positionalArg(args, 3) || process.cwd()
+      printJson(await resolveBlocker(root, slug, optionValue(args, "--text")))
       return
     }
     if (action === "verify-integration") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      const reportFile = optionValue("--report-file")
-      const report = reportFile ? readFileSync(path.resolve(reportFile), "utf8") : null
+      const root = positionalArg(args, 3) || process.cwd()
+      const reportFile = optionValue(args, "--report-file")
+      const report = reportFile ? readTextFile(reportFile) : null
+      const receiptFile = optionValue(args, "--receipt-file")
+      const receipt = receiptFile ? readJsonFile(receiptFile) : null
       printJson(await recordIntegrationVerification(
         root,
         slug,
-        optionValue("--verdict"),
-        optionValue("--evidence"),
+        optionValue(args, "--verdict"),
+        optionValue(args, "--evidence"),
         report,
+        { receipt },
       ))
       return
     }
     if (action === "finalize") {
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      printJson(await finalizeWork(root, slug, optionValue("--evidence")))
+      const root = positionalArg(args, 3) || process.cwd()
+      printJson(await finalizeWork(root, slug, optionValue(args, "--evidence")))
       return
     }
 
     throw new Error("Unknown work action: " + action)
   } catch (error) {
-    console.error(error instanceof Error ? error.message : error)
+    console.error(errorMessage(error))
     if (error?.validation) printJson(error.validation)
     process.exitCode = 1
   }
@@ -562,10 +736,10 @@ async function modelPolicy() {
     process.exitCode = 2
     return
   }
-  const attempt = Number.parseInt(optionValue("--attempt") || "1", 10)
+  const attempt = optionInt(args, "--attempt", 1)
   const policy = await readModelPolicy(getConfigDir())
   const normalizedAttempt = Number.isInteger(attempt) && attempt > 0 ? attempt : 1
-  const taskText = optionValue("--text")
+  const taskText = optionValue(args, "--text")
   if (taskText) {
     printJson(resolveAdaptiveModel(role, normalizedAttempt, classifyEngineeringTask(taskText), policy))
     return
@@ -627,7 +801,7 @@ async function modelsControl() {
 async function routerControl() {
   const action = args[1] || "status"
   const maxIndex = args.indexOf("--max")
-  const maxValue = maxIndex >= 0 ? Number.parseInt(args[maxIndex + 1] || "", 10) : null
+  const maxValue = maxIndex >= 0 ? Number.parseInt(optionValue(args, "--max") ?? "", 10) : null
 
   if (!["status", "on", "off"].includes(action)) {
     console.error("Usage: ocskill router [status|on|off] [--max 1..6]")
@@ -678,42 +852,76 @@ async function taskPolicyControl() {
 async function sandboxControl() {
   const action = args[1] || "list"
   try {
+    if (action === "capability") {
+      printJson(containerSandboxCapability(optionValue(args, "--engine")))
+      return
+    }
+    if (action === "exec") {
+      const separator = args.indexOf("--")
+      const root = positionalArg(args, 2) || process.cwd()
+      const executable = separator >= 0 ? args[separator + 1] : null
+      const commandArgs = separator >= 0 ? args.slice(separator + 2) : []
+      const image = optionValue(args, "--image")
+      if (!image || !executable) {
+        throw new Error("Usage: ocskill sandbox exec [dir] --image <image> [--engine docker|podman] -- <command> [args...]")
+      }
+      const result = runContainerSandbox(root, {
+        engine: optionValue(args, "--engine"),
+        image,
+        command: executable,
+        args: commandArgs,
+        timeoutMs: optionInt(args, "--timeout-ms", 10 * 60_000),
+      })
+      printJson({ ...result, stdout: clipOutput(result.stdout), stderr: clipOutput(result.stderr) })
+      if (result.status !== 0) process.exitCode = result.status
+      return
+    }
     if (action === "list") {
-      printJson(listTaskSandboxes(args[2] || process.cwd()))
+      printJson(listTaskSandboxes(positionalArg(args, 2) || process.cwd()))
       return
     }
     if (action === "create") {
       const slug = args[2]
       const taskID = args[3]
-      const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
+      const root = positionalArg(args, 4) || process.cwd()
       if (!slug || !taskID) throw new Error("Usage: ocskill sandbox create <slug> <task-id> [dir]")
       printJson(await createTaskSandbox(root, slug, taskID))
       return
     }
+    if (action === "integrate") {
+      const dir = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!dir) throw new Error("Usage: ocskill sandbox integrate <worktree-path> [dir] [--keep]")
+      printJson(await integrateTaskSandbox(root, dir, { keep: args.includes("--keep") }))
+      return
+    }
     if (action === "remove") {
       const dir = args[2]
-      const root = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
-      if (!dir) throw new Error("Usage: ocskill sandbox remove <worktree-path> [dir] [--force]")
-      printJson(await removeTaskSandbox(root, dir, { force: args.includes("--force") }))
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!dir) throw new Error("Usage: ocskill sandbox remove <worktree-path> [dir] [--force] [--delete-branch]")
+      printJson(await removeTaskSandbox(root, dir, {
+        force: args.includes("--force"),
+        deleteBranch: args.includes("--delete-branch"),
+      }))
       return
     }
-    throw new Error("Usage: ocskill sandbox <list|create|remove> ...")
+    throw new Error("Usage: ocskill sandbox <capability|exec|list|create|integrate|remove> ...")
   } catch (error) {
-    console.error(error instanceof Error ? error.message : error)
+    console.error(errorMessage(error))
     process.exitCode = 1
   }
 }
 
 async function learningControl() {
   const action = args[1] || "status"
-  const root = args[2] && !args[2].startsWith("--") ? args[2] : process.cwd()
+  const root = positionalArg(args, 2) || process.cwd()
   try {
     if (action === "status") {
       printJson(await readLearningState(root))
       return
     }
     if (action === "analyze") {
-      const evalDir = optionValue("--eval-dir") || path.join(path.resolve(root), ".ues-evals")
+      const evalDir = optionValue(args, "--eval-dir") || path.join(path.resolve(root), ".ues-evals")
       const analysis = await analyzeEvalTraces(evalDir)
       const state = await saveLearningAnalysis(root, analysis)
       printJson({ analysis, state })
@@ -721,14 +929,23 @@ async function learningControl() {
     }
     if (action === "accept") {
       const id = args[2]
-      const acceptRoot = args[3] && !args[3].startsWith("--") ? args[3] : process.cwd()
+      const acceptRoot = positionalArg(args, 3) || process.cwd()
       if (!id) throw new Error("Usage: ocskill learn accept <proposal-id> [dir]")
       printJson(await acceptLearning(acceptRoot, id))
       return
     }
-    throw new Error("Usage: ocskill learn <status|analyze|accept> ...")
+    if (action === "promote") {
+      const id = args[2]
+      const promoteRoot = positionalArg(args, 3) || process.cwd()
+      if (!id) throw new Error("Usage: ocskill learn promote <proposal-id> [dir] --report <matrix-summary.json>")
+      printJson(await promoteLearning(promoteRoot, id, {
+        report: optionValue(args, "--report"),
+      }))
+      return
+    }
+    throw new Error("Usage: ocskill learn <status|analyze|accept|promote> ...")
   } catch (error) {
-    console.error(error instanceof Error ? error.message : error)
+    console.error(errorMessage(error))
     process.exitCode = 1
   }
 }
@@ -742,7 +959,7 @@ async function hermesControl() {
   if (action === "prompt" || action === "exec") {
     const slug = args[2]
     const taskID = args[3]
-    const root = args[4] && !args[4].startsWith("--") ? args[4] : process.cwd()
+    const root = positionalArg(args, 4) || process.cwd()
     if (!slug || !taskID) {
       console.error("Usage: ocskill hermes <prompt|exec> <slug> <task-id> [dir]")
       process.exitCode = 2
@@ -796,7 +1013,7 @@ async function update() {
     })
   } catch (error) {
     console.error("[ocskill] Could not determine the latest published npm version; refusing an unsafe self-update.")
-    console.error(error instanceof Error ? error.message : error)
+    console.error(errorMessage(error))
     process.exitCode = error?.exitCode || 1
     return
   }
@@ -808,7 +1025,7 @@ async function update() {
     compared = compareVersions(latestVersion, currentVersion)
   } catch (error) {
     console.error("[ocskill] npm returned a version that could not be compared safely; refusing update.")
-    console.error(error instanceof Error ? error.message : error)
+    console.error(errorMessage(error))
     process.exitCode = 1
     return
   }
@@ -906,6 +1123,15 @@ switch (command) {
   case "repo-graph":
     await inspectRepoGraph()
     break
+  case "index":
+    await semanticIndexControl()
+    break
+  case "aci":
+    await aciControl()
+    break
+  case "trace":
+    await traceControl()
+    break
   case "review-scope":
     await inspectReviewScope()
     break