opencode-agent-skill 12.0.0-beta.0 → 13.0.0-beta.1

package/bin/ocskill.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { writeFileSync } from "node:fs"
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
 import { spawnSync } from "node:child_process"
 import { fileURLToPath } from "node:url"
 import path from "node:path"
@@ -62,7 +62,7 @@ import { buildVerificationPlan } from "../lib/verification-plan.mjs"
 import { resolveAdaptiveModel, resolveCapabilityModel, resolveModel } from "../lib/model-policy.mjs"
 import { createVerificationReceipt } from "../lib/evidence-receipt.mjs"
 import { classifyEngineeringTask } from "../lib/orchestrator-policy.mjs"
-import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskSandbox } from "../lib/worktree-sandbox.mjs"
+import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskSandbox, rollbackTaskSandbox } from "../lib/worktree-sandbox.mjs"
 import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning, promoteLearning } from "../lib/learning-engine.mjs"
 import { hermesStatus, buildHermesDelegationPrompt, buildHermesWorkflowPrompt, hermesOneShotArgs, hermesSidecarPlan } from "../lib/hermes-bridge.mjs"
 import { readModelPolicy, recordModelPerformance, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
@@ -77,6 +77,7 @@ import { planDynamicWorkflow } from "../lib/dynamic-workflow.mjs"
 import { lintSkillCatalog } from "../lib/skill-quality.mjs"
 import { designTokenEvidence, extractDesignTokens, inspectResponsiveLayout } from "../lib/ui-inspector.mjs"
 import {
+  cliErrorPayload,
   clipOutput,
   errorMessage,
   optionInt,
@@ -85,10 +86,22 @@ import {
   positionalArg,
   readJsonFile,
   readTextFile,
+  usageError,
 } from "../lib/cli-utils.mjs"
 
-const args = process.argv.slice(2)
+const rawArgs = process.argv.slice(2)
+const rawSeparator = rawArgs.indexOf("--")
+const jsonOutput = rawArgs.some((value, index) =>
+  value === "--json" && (rawSeparator < 0 || index < rawSeparator),
+)
+const args = rawArgs.filter((value, index) =>
+  !(value === "--json" && (rawSeparator < 0 || index < rawSeparator)),
+)
 const command = args[0] || "help"
+const argsSeparator = args.indexOf("--")
+const helpRequested = args.some((value, index) =>
+  (value === "--help" || value === "-h") && (argsSeparator < 0 || index < argsSeparator),
+)
 const force = args.includes("--force")
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
 
@@ -107,7 +120,11 @@ Usage:
   ocskill impact <query> [dir] Search likely impact paths and matching lines
   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 diff [dir] [--out file] Emit Git diff safely as UTF-8 (Windows-safe)
+  ocskill text-read <file> [--start N] [--max N]  Read UTF-8/UTF-16 text safely with bounded output
+  ocskill normalize-text <file>  Convert UTF-8/UTF-16 text files to UTF-8
+  ocskill repo-graph [dir] [--compact] [--max-files N]
+                              Build a bounded source import/dependency graph; compact omits full node/edge payloads
   ocskill index <status|build|rebuild> [dir]
                               Build/reuse the persistent incremental semantic index
   ocskill aci <search|refs|view|text> ...
@@ -124,7 +141,7 @@ 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> ...  Create, integrate and clean isolated Git worktree sandboxes
+  ocskill sandbox <action> ...  Create, integrate, rollback 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 sidecar/status/task/workflow planning
@@ -151,12 +168,15 @@ Usage:
     ocskill work plan <slug> <plan.json> [dir]
     ocskill work status|resume <slug> [dir]
     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 agent-receipt <slug> <task-id> [dir] --run-id <id> --verdict PASS|FAIL --evidence <text>
     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 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 recover-task <slug> <task-id> [dir] [--force] [--reason <text>]
+    ocskill work checkpoint <slug> <task-id> [dir] --run-id <id> [--reason <text>]
+    ocskill work checkpoint-resumed <slug> <task-id> [dir] --run-id <id> [--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>]
@@ -178,6 +198,95 @@ Usage:
 `)
 }
 
+function printCommandHelp(commandName, subcommand) {
+  const workUsage = {
+    init: "ocskill work init <slug> [dir] --goal <text>",
+    plan: "ocskill work plan <slug> <plan.json> [dir]",
+    status: "ocskill work status [slug|dir]",
+    resume: "ocskill work resume <slug> [dir]",
+    "gate-receipt": "ocskill work gate-receipt <slug> <plan|integration> [dir] --evidence <text>",
+    "agent-receipt": "ocskill work agent-receipt <slug> <task-id> [dir] --run-id <id> --verdict PASS|FAIL --evidence <text>",
+    "approve-plan": "ocskill work approve-plan <slug> [dir] --evidence <text>",
+    start: "ocskill work start <slug> <task-id> [dir]",
+    "attach-session": "ocskill work attach-session <slug> <task-id> [dir] --run-id <id> --session-id <id>",
+    heartbeat: "ocskill work heartbeat <slug> <task-id> [dir] --run-id <id>",
+    recover: "ocskill work recover <slug> [dir]",
+    "recover-task": "ocskill work recover-task <slug> <task-id> [dir]",
+    checkpoint: "ocskill work checkpoint <slug> <task-id> [dir] --run-id <id> [--reason <text>]",
+    "checkpoint-resumed": "ocskill work checkpoint-resumed <slug> <task-id> [dir] --run-id <id> [--reason <text>]",
+    events: "ocskill work events <slug> [dir]",
+    "verify-command": "ocskill work verify-command <slug> <task-id> [dir] --run-id <id> -- <command> [args...]",
+    complete: "ocskill work complete <slug> <task-id> [dir] --run-id <id> --evidence <text>",
+    fail: "ocskill work fail <slug> <task-id> [dir] --run-id <id> --reason <text>",
+    decision: "ocskill work decision <slug> [dir] --text <decision>",
+    block: "ocskill work block <slug> [dir] --text <blocker>",
+    unblock: "ocskill work unblock <slug> [dir] --text <blocker>",
+    "verify-integration": "ocskill work verify-integration <slug> [dir] --verdict PASS|FAIL|PARTIAL --evidence <text>",
+    finalize: "ocskill work finalize <slug> [dir] --evidence <text>",
+  }
+  if (commandName === "work") {
+    if (subcommand && workUsage[subcommand]) console.log("Usage: " + workUsage[subcommand] + "\n")
+    else console.log("Usage: ocskill work <action> ...\n\nActions:\n  " + Object.keys(workUsage).join("\n  "))
+    return
+  }
+  if (commandName === "sandbox") {
+    console.log("Usage: ocskill sandbox <capability|exec|list|create|integrate|rollback|remove> ...\n")
+    return
+  }
+  if (commandName === "diff") {
+    console.log("Usage: ocskill diff [dir] [--base <ref>] [--out <utf8-file>]\n")
+    return
+  }
+  if (commandName === "text-read") {
+    console.log("Usage: ocskill text-read <file> [--start N] [--max N] [--json]\n")
+    return
+  }
+  if (commandName === "normalize-text") {
+    console.log("Usage: ocskill normalize-text <file> [--out <utf8-file>]\n")
+    return
+  }
+  printHelp()
+}
+
+function printCliError(error, options = {}) {
+  const payload = cliErrorPayload(error, {
+    command: options.command || args.filter((value) => value !== "--help" && value !== "-h").join(" "),
+    usage: options.usage,
+    hint: options.hint,
+    recoverable: options.recoverable,
+  })
+  if (jsonOutput) console.error(JSON.stringify(payload))
+  else {
+    console.error("[ocskill] " + payload.error.code + ": " + payload.error.message)
+    if (payload.error.hint) console.error("[ocskill] Hint: " + payload.error.hint)
+  }
+  process.exitCode = payload.exitCode
+}
+
+function pathLikeWorkRoot(value) {
+  return !value || value === "." || value === ".." || value.includes("/") || value.includes("\\")
+}
+
+function listWorkspaces(root) {
+  root = path.resolve(root)
+  const base = path.join(root, ".ues-work")
+  if (!existsSync(base)) return []
+  const result = []
+  for (const entry of readdirSync(base, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    try {
+      const state = JSON.parse(readTextFile(path.join(base, entry.name, "STATE.json")))
+      result.push({
+        slug: entry.name,
+        status: state.status || null,
+        goal: state.goal || null,
+        updatedAt: state.updatedAt || null,
+        nextAction: state.nextAction || null,
+      })
+    } catch {}
+  }
+  return result.sort((a, b) => a.slug.localeCompare(b.slug))
+}
 
 function run(executable, commandArgs, options = {}) {
   const common = { stdio: "inherit", ...options }
@@ -241,9 +350,18 @@ async function install() {
   console.log(`[ocskill] Installed resources for v${result.version}`)
   console.log(`[ocskill] OpenCode config: ${result.configDir}`)
   console.log(`[ocskill] Skills: ${result.skills.length}`)
-  console.log(`[ocskill] Commands: ${result.commands.length}`)
+  if (Number(result.openCodeMajor) >= 2) {
+    console.log(`[ocskill] Prompt aliases: ${(result.promptAliases || []).length} (session.prompt compatibility path)`)
+  } else {
+    console.log(`[ocskill] Commands: ${result.commands.length}`)
+  }
   console.log(`[ocskill] Subagents: ${result.agents.length}`)
   console.log(`[ocskill] OpenCode major: ${result.openCodeMajor}`)
+  console.log(
+    Number(result.openCodeMajor) >= 2
+      ? "[ocskill] V13 parallel: runtime capability-gated; open a new OpenCode session and check ues.capabilities."
+      : "[ocskill] V13 parallel: unavailable on OpenCode 1.x; CLI/durable workflow remains available.",
+  )
   if ((result.plugins || []).length) console.log(`[ocskill] Router plugins: ${result.plugins.length}`)
   for (const warning of result.warnings) console.warn(`[ocskill] WARNING: ${warning}`)
   console.log("[ocskill] Start a new OpenCode session to pick up workflow changes.")
@@ -268,15 +386,25 @@ async function status() {
   console.log(`[ocskill] Sync: ${synced ? "OK" : "OUTDATED - run ocskill install"}`)
   console.log(`[ocskill] Config: ${result.configDir}`)
   console.log(`[ocskill] Skills: ${result.skillsPresent}/${result.skills.length}`)
-  console.log(`[ocskill] Commands: ${result.commandsPresent}/${result.commands.length}`)
+  if (Number(result.openCodeMajor) >= 2) {
+    console.log(`[ocskill] Prompt aliases: ${result.promptAliasesPresent || 0}/${(result.promptAliases || []).length}`)
+  } else {
+    console.log(`[ocskill] Commands: ${result.commandsPresent}/${result.commands.length}`)
+  }
   console.log(`[ocskill] Subagents: ${result.agentsPresent}/${(result.agents || []).length}`)
   console.log(`[ocskill] OpenCode major: ${result.openCodeMajor ?? "legacy/unknown"}`)
+  console.log(
+    Number(result.openCodeMajor) >= 2
+      ? "[ocskill] V13 parallel: runtime capability-gated; verify freshDispatch with ues.capabilities in a new session."
+      : "[ocskill] V13 parallel: unavailable on OpenCode 1.x; use serial durable execution or upgrade the runtime.",
+  )
   if ((result.plugins || []).length) console.log(`[ocskill] Router plugins: ${result.pluginsPresent}/${result.plugins.length}`)
   console.log(`[ocskill] Workflow: ${result.workflowPresent ? "OK" : "MISSING"}`)
 
   if (!synced ||
       result.skillsPresent !== result.skills.length ||
       result.commandsPresent !== result.commands.length ||
+      (result.promptAliasesPresent || 0) !== (result.promptAliases || []).length ||
       result.agentsPresent !== (result.agents || []).length ||
       result.pluginsPresent !== (result.plugins || []).length ||
       !result.workflowPresent) {
@@ -332,8 +460,7 @@ async function inspectRepository() {
 async function inspectImpact() {
   const query = args[1]
   if (!query) {
-    console.error("Usage: ocskill impact <query> [dir]")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill impact <query> [dir]"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   printJson(await impactMap(positionalArg(args, 2) || process.cwd(), query))
@@ -356,7 +483,26 @@ async function inspectTests() {
 }
 
 async function inspectRepoGraph() {
-  printJson(await buildRepoGraph(positionalArg(args, 1) || process.cwd()))
+  const root = positionalArg(args, 1) || process.cwd()
+  const parsedMaxFiles = optionInt(args, "--max-files", 2500)
+  const maxFiles = Number.isFinite(parsedMaxFiles)
+    ? Math.max(100, Math.min(parsedMaxFiles, 10000))
+    : 2500
+  const graph = await buildRepoGraph(root, { maxFiles })
+  if (args.includes("--compact")) {
+    printJson({
+      schemaVersion: graph.schemaVersion,
+      root: graph.root,
+      scannedFiles: graph.scannedFiles,
+      truncated: graph.truncated,
+      nodeCount: graph.nodes.length,
+      edgeCount: graph.edges.length,
+      hotspots: graph.hotspots,
+      externalImports: graph.externalImports,
+    })
+    return
+  }
+  printJson(graph)
 }
 
 async function semanticIndexControl() {
@@ -374,8 +520,7 @@ async function semanticIndexControl() {
     }
     throw new Error("Usage: ocskill index <status|build|rebuild> [dir]")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -416,8 +561,7 @@ async function aciControl() {
     }
     throw new Error("Usage: ocskill aci <search|refs|view|text> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -446,8 +590,7 @@ async function traceControl() {
     }
     throw new Error("Usage: ocskill trace <show|append> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -464,8 +607,7 @@ async function inspectVerificationPlan() {
 async function inspectTaskGraph() {
   const file = args[1]
   if (!file) {
-    console.error("Usage: ocskill task-graph <plan.json>")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill task-graph <plan.json>"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   try {
@@ -474,8 +616,7 @@ async function inspectTaskGraph() {
     printJson(analysis)
     if (!analysis.valid) process.exitCode = 1
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -483,8 +624,7 @@ async function inspectContextPack() {
   const slug = args[1]
   const taskID = args[2]
   if (!slug || !taskID) {
-    console.error("Usage: ocskill context-pack <slug> <task-id> [dir]")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill context-pack <slug> <task-id> [dir]"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   printJson(await contextPack(positionalArg(args, 3) || process.cwd(), slug, taskID))
@@ -493,9 +633,56 @@ async function inspectContextPack() {
 async function workControl() {
   const action = args[1]
   const slug = args[2]
-  if (!action || !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
+  if (!action) {
+    const error = new Error("Usage: ocskill work <action> ...")
+    error.code = "UES_USAGE"
+    error.exitCode = 2
+    printCliError(error)
+    return
+  }
+
+  if (action === "status" && pathLikeWorkRoot(slug)) {
+    const root = path.resolve(slug || process.cwd())
+    const workspaces = listWorkspaces(root)
+    const active = workspaces.filter((item) => item.status !== "completed")
+    const candidate = active.length === 1
+      ? active[0]
+      : active.length === 0 && workspaces.length === 1
+        ? workspaces[0]
+        : null
+    if (candidate) {
+      const status = await workStatus(root, candidate.slug)
+      printJson({
+        ...status,
+        autoResolved: true,
+        autoResolvedSlug: candidate.slug,
+        requestedRoot: root,
+      })
+    } else {
+      printJson({
+        schemaVersion: 1,
+        root,
+        autoResolved: false,
+        workspaces,
+        hint: workspaces.length > 1 ? "Pass an explicit work slug because multiple workspaces exist." : null,
+      })
+    }
+    return
+  }
+
+  if (!slug) {
+    const error = usageError("Usage: ocskill work " + action + " <slug> ...")
+    printCliError(error)
+    return
+  }
+
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(String(slug))) {
+    printCliError(usageError(
+      "Invalid work slug '" + String(slug) + "'. Use lowercase letters, numbers and dashes only.",
+    ), {
+      usage: "Usage: ocskill work " + action + " <slug> ...",
+      hint: "Example slug: recovery-2-foundation",
+    })
     return
   }
 
@@ -552,6 +739,44 @@ async function workControl() {
       }
       return
     }
+    if (action === "agent-receipt") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      const runId = optionValue(args, "--run-id")
+      const verdict = String(optionValue(args, "--verdict") || "").toUpperCase()
+      const evidence = String(optionValue(args, "--evidence") || "").trim()
+      const verifier = String(optionValue(args, "--verifier") || "ues-verifier")
+      const sessionID = optionValue(args, "--session-id")
+      if (!taskID || !runId || !["PASS", "FAIL"].includes(verdict) || !evidence) {
+        const error = new Error("Usage: ocskill work agent-receipt <slug> <task-id> [dir] --run-id <id> --verdict PASS|FAIL --evidence <text> [--verifier <role>] [--session-id <id>]")
+        error.code = "UES_USAGE"
+        error.exitCode = 2
+        throw error
+      }
+      const fingerprint = workspaceFingerprint(root)
+      const timestamp = new Date().toISOString()
+      const receipt = createVerificationReceipt({
+        task: taskID,
+        runId,
+        command: "ues-agent-verifier",
+        args: [verifier, ...(sessionID ? [sessionID] : [])],
+        cwd: path.resolve(root),
+        exitCode: verdict === "PASS" ? 0 : 1,
+        startedAt: timestamp,
+        finishedAt: timestamp,
+        durationMs: 0,
+        stdout: evidence,
+        stderr: verdict === "PASS" ? "" : evidence,
+        workspaceBefore: fingerprint,
+        workspaceAfter: fingerprint,
+      })
+      receipt.kind = "agent-verifier"
+      receipt.verifier = verifier
+      receipt.sessionID = sessionID || null
+      receipt.evidence = evidence
+      printJson(await recordVerificationReceipt(root, slug, taskID, receipt))
+      return
+    }
     if (action === "approve-plan") {
       const root = positionalArg(args, 3) || process.cwd()
       const receiptFile = optionValue(args, "--receipt-file")
@@ -740,19 +965,20 @@ async function workControl() {
       return
     }
 
-    throw new Error("Unknown work action: " + action)
+    throw usageError("Unknown work action: " + action)
   } catch (error) {
-    console.error(errorMessage(error))
-    if (error?.validation) printJson(error.validation)
-    process.exitCode = 1
+    if (error?.validation && !jsonOutput) printJson(error.validation)
+    printCliError(error, {
+      command: "work " + String(action || ""),
+      recoverable: error?.code === "UES_USAGE",
+    })
   }
 }
 
 async function modelPolicy() {
   const role = args[1]
   if (!role) {
-    console.error("Usage: ocskill model-policy <role> [--attempt N]")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill model-policy <role> [--attempt N]"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   const attempt = optionInt(args, "--attempt", 1)
@@ -786,8 +1012,7 @@ async function modelsControl() {
     const tier = args[2]
     const model = args[3]
     if (!["light", "standard", "heavy"].includes(tier) || !validateModelID(model)) {
-      console.error("Usage: ocskill models set <light|standard|heavy> <provider/model[#variant]>")
-      process.exitCode = 2
+      printCliError(Object.assign(new Error("Usage: ocskill models set <light|standard|heavy> <provider/model[#variant]>"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
     policy = await writeModelPolicy(getConfigDir(), {
@@ -802,8 +1027,7 @@ async function modelsControl() {
     const role = args[2]
     const tier = args[3]
     if (!role || !["light", "standard", "heavy"].includes(tier)) {
-      console.error("Usage: ocskill models role <role> <light|standard|heavy>")
-      process.exitCode = 2
+      printCliError(Object.assign(new Error("Usage: ocskill models role <role> <light|standard|heavy>"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
     policy = await writeModelPolicy(getConfigDir(), {
@@ -817,8 +1041,7 @@ async function modelsControl() {
   if (action === "observe") {
     const model = args[2]
     if (!validateModelID(model)) {
-      console.error("Usage: ocskill models observe <provider/model> --task-class <class> --passed on|off")
-      process.exitCode = 2
+      printCliError(Object.assign(new Error("Usage: ocskill models observe <provider/model> --task-class <class> --passed on|off"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
     const taskClass = optionValue(args, "--task-class") || "general"
@@ -838,8 +1061,7 @@ async function modelsControl() {
   if (action === "capability") {
     const model = args[2]
     if (!validateModelID(model)) {
-      console.error("Usage: ocskill models capability <provider/model> [capability flags]")
-      process.exitCode = 2
+      printCliError(Object.assign(new Error("Usage: ocskill models capability <provider/model> [capability flags]"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
     const current = policy.capabilities?.[model] || {}
@@ -877,8 +1099,7 @@ async function modelsControl() {
     return
   }
 
-  console.error("Usage: ocskill models <status|on|off|set|role> ...")
-  process.exitCode = 2
+  printCliError(Object.assign(new Error("Usage: ocskill models <status|on|off|set|role> ..."), { code: "UES_USAGE", exitCode: 2 }))
 }
 
 async function routerControl() {
@@ -887,13 +1108,14 @@ async function routerControl() {
   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]")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill router [status|on|off] [--max 1..6]"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   if (maxIndex >= 0 && (!Number.isInteger(maxValue) || maxValue < 1 || maxValue > 6)) {
-    console.error("--max must be an integer from 1 through 6")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("--max must be an integer from 1 through 6"), {
+      code: "UES_USAGE",
+      exitCode: 2,
+    }))
     return
   }
 
@@ -925,8 +1147,7 @@ async function routerControl() {
 async function taskPolicyControl() {
   const text = args.slice(1).join(" ").trim()
   if (!text) {
-    console.error("Usage: ocskill task-policy <text>")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill task-policy <text>"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   printJson(classifyEngineeringTask(text))
@@ -968,7 +1189,11 @@ async function sandboxControl() {
       const taskID = args[3]
       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))
+      printJson(await createTaskSandbox(root, slug, taskID, {
+        inheritDirtyRoot: args.includes("--inherit-dirty-root"),
+        allowDirtyRoot: args.includes("--allow-dirty-root"),
+        startPoint: optionValue(args, "--start-point") || undefined,
+      }))
       return
     }
     if (action === "integrate") {
@@ -978,6 +1203,13 @@ async function sandboxControl() {
       printJson(await integrateTaskSandbox(root, dir, { keep: args.includes("--keep") }))
       return
     }
+    if (action === "rollback") {
+      const dir = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!dir) throw new Error("Usage: ocskill sandbox rollback <worktree-path> [dir] [--keep]")
+      printJson(await rollbackTaskSandbox(root, dir, { keep: args.includes("--keep") }))
+      return
+    }
     if (action === "remove") {
       const dir = args[2]
       const root = positionalArg(args, 3) || process.cwd()
@@ -988,10 +1220,9 @@ async function sandboxControl() {
       }))
       return
     }
-    throw new Error("Usage: ocskill sandbox <capability|exec|list|create|integrate|remove> ...")
+    throw new Error("Usage: ocskill sandbox <capability|exec|list|create|integrate|rollback|remove> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -1028,8 +1259,7 @@ async function learningControl() {
     }
     throw new Error("Usage: ocskill learn <status|analyze|accept|promote> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -1043,8 +1273,7 @@ async function hermesControl() {
     const slug = args[2]
     const root = positionalArg(args, 3) || process.cwd()
     if (!slug) {
-      console.error("Usage: ocskill hermes <workflow|exec-workflow> <slug> [dir] [--max-concurrent N]")
-      process.exitCode = 2
+      printCliError(Object.assign(new Error("Usage: ocskill hermes <workflow|exec-workflow> <slug> [dir] [--max-concurrent N]"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
     const planFile = path.join(path.resolve(root), ".ues-work", slug, "PLAN.json")
@@ -1078,8 +1307,7 @@ async function hermesControl() {
     const taskID = args[3]
     const root = positionalArg(args, 4) || process.cwd()
     if (!slug || !taskID) {
-      console.error("Usage: ocskill hermes <prompt|exec> <slug> <task-id> [dir]")
-      process.exitCode = 2
+      printCliError(Object.assign(new Error("Usage: ocskill hermes <prompt|exec> <slug> <task-id> [dir]"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
     const prompt = buildHermesDelegationPrompt(await contextPack(root, slug, taskID))
@@ -1103,8 +1331,7 @@ async function hermesControl() {
     if ((result.status ?? 1) !== 0) process.exitCode = result.status ?? 1
     return
   }
-  console.error("Usage: ocskill hermes <status|prompt|exec|workflow|exec-workflow> ...")
-  process.exitCode = 2
+  printCliError(Object.assign(new Error("Usage: ocskill hermes <status|prompt|exec|workflow|exec-workflow> ..."), { code: "UES_USAGE", exitCode: 2 }))
 }
 
 async function evidenceStoreControl() {
@@ -1146,16 +1373,14 @@ async function evidenceStoreControl() {
     }
     throw new Error("Usage: ocskill store <status|put|get|gc> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
 async function capabilityControl() {
   const text = args.slice(1).join(" ").trim()
   if (!text) {
-    console.error("Usage: ocskill capabilities <task text>")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill capabilities <task text>"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   printJson(inferTaskCapabilities(text))
@@ -1204,8 +1429,7 @@ async function visualControl() {
     }
     throw new Error("Usage: ocskill visual <spec|geometry|compare|crop|viewports> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -1243,8 +1467,7 @@ async function browserControl() {
     }
     throw new Error("Usage: ocskill browser <capability|plan|inspect> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -1274,16 +1497,83 @@ async function uiControl() {
     }
     throw new Error("Usage: ocskill ui <tokens|layout> ...")
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
+  }
+}
+
+async function diffControl() {
+  const root = path.resolve(positionalArg(args, 1) || process.cwd())
+  const base = optionValue(args, "--base")
+  const outputFile = optionValue(args, "--out")
+  const commandArgs = ["diff", "--binary", "--no-ext-diff", ...(base ? [base] : []), "--"]
+  const result = runCapture("git", commandArgs, { cwd: root, maxBuffer: 16 * 1024 * 1024 })
+  if ((result.status ?? 1) !== 0) {
+    const error = new Error((result.stderr || result.stdout || "git diff failed").trim())
+    error.code = "UES_GIT_DIFF"
+    throw error
+  }
+  if (outputFile) {
+    const resolved = path.resolve(outputFile)
+    writeFileSync(resolved, result.stdout || "", "utf8")
+    printJson({ schemaVersion: 1, root, base: base || null, file: resolved, encoding: "utf8", bytes: Buffer.byteLength(result.stdout || "") })
+    return
+  }
+  if (jsonOutput) {
+    printJson({ schemaVersion: 1, root, base: base || null, encoding: "utf8", diff: result.stdout || "" })
+    return
   }
+  process.stdout.write(result.stdout || "")
+}
+
+async function textReadControl() {
+  const file = positionalArg(args, 1)
+  if (!file) {
+    const error = new Error("Usage: ocskill text-read <file> [--start N] [--max N] [--json]")
+    error.code = "UES_USAGE"
+    error.exitCode = 2
+    throw error
+  }
+  const text = readTextFile(file)
+  const parsedStart = optionInt(args, "--start", 0)
+  const parsedMax = optionInt(args, "--max", 12000)
+  const start = Number.isFinite(parsedStart) ? Math.max(0, parsedStart) : 0
+  const maxChars = Number.isFinite(parsedMax) ? Math.max(256, Math.min(parsedMax, 100000)) : 12000
+  const slice = text.slice(start, start + maxChars)
+  const truncated = start + slice.length < text.length
+  if (jsonOutput) {
+    printJson({
+      schemaVersion: 1,
+      file: path.resolve(file),
+      chars: text.length,
+      start,
+      returnedChars: slice.length,
+      truncated,
+      text: slice,
+    })
+    return
+  }
+  process.stdout.write(slice)
+  if (truncated) process.stdout.write("\n...[UES text-read truncated]...\n")
+}
+
+async function normalizeTextControl() {
+  const file = args[1]
+  if (!file) {
+    const error = new Error("Usage: ocskill normalize-text <file> [--out <utf8-file>]")
+    error.code = "UES_USAGE"
+    error.exitCode = 2
+    throw error
+  }
+  const text = readTextFile(file)
+  const output = path.resolve(optionValue(args, "--out") || file)
+  writeFileSync(output, text, "utf8")
+  printJson({ schemaVersion: 1, input: path.resolve(file), output, encoding: "utf8", bytes: Buffer.byteLength(text) })
 }
 
 async function workflowPlanControl() {
   const file = args[1]
   if (!file) {
-    console.error("Usage: ocskill workflow-plan <PLAN.json> [--max-concurrent N]")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill workflow-plan <PLAN.json> [--max-concurrent N]"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   try {
@@ -1297,23 +1587,20 @@ async function workflowPlanControl() {
       minVisionAgentCost: optionInt(args, "--min-vision-agent-cost", 4),
     }))
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
 async function skillsControl() {
   const action = args[1] || "lint"
   if (action !== "lint") {
-    console.error("Usage: ocskill skills lint [dir]")
-    process.exitCode = 2
+    printCliError(Object.assign(new Error("Usage: ocskill skills lint [dir]"), { code: "UES_USAGE", exitCode: 2 }))
     return
   }
   try {
     printJson(await lintSkillCatalog(positionalArg(args, 2) || packageRoot))
   } catch (error) {
-    console.error(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
   }
 }
 
@@ -1352,8 +1639,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(errorMessage(error))
-    process.exitCode = 1
+    printCliError(error)
     return
   }
 
@@ -1414,7 +1700,13 @@ async function remove() {
   if (code !== 0) process.exitCode = code
 }
 
-switch (command) {
+async function main() {
+  if (helpRequested) {
+    printCommandHelp(command, args[1])
+    return
+  }
+
+  switch (command) {
   case "install":
   case "sync":
     await install()
@@ -1504,6 +1796,15 @@ switch (command) {
   case "workflow-plan":
     await workflowPlanControl()
     break
+  case "diff":
+    await diffControl().catch((error) => printCliError(error))
+    break
+  case "text-read":
+    await textReadControl().catch((error) => printCliError(error))
+    break
+  case "normalize-text":
+    await normalizeTextControl().catch((error) => printCliError(error))
+    break
   case "ui":
     await uiControl()
     break
@@ -1542,8 +1843,17 @@ switch (command) {
   case "-h":
     printHelp()
     break
-  default:
-    console.error(`Unknown command: ${command}`)
-    printHelp()
-    process.exitCode = 1
+  default: {
+    const error = new Error("Unknown command: " + command)
+    error.code = "UES_USAGE"
+    error.exitCode = 2
+    throw error
+  }
+  }
+}
+
+try {
+  await main()
+} catch (error) {
+  printCliError(error)
 }