opencode-agent-skill 13.0.0-beta.2 → 14.2.0-beta.1

package/lib/task-policy.mjs

@@ -0,0 +1,235 @@
+const SENSITIVE_DOMAIN = /(\bauth\b|authorization|authentication|security|permission|payment|schema|database|production|deploy|public api|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|triển khai|api công khai|bí mật|thông tin xác thực)/i
+const HIGH_RISK_MUTATION = /((?:fix|change|modify|update|alter|migrate|drop|truncate|delete|remove|rotate|deploy|publish|push|sửa|thay đổi|cập nhật|xóa|xoá|di trú|chuyển đổi|triển khai).{0,64}(?:\bauth\b|authorization|authentication|security|permission|payment(?: handling| flow)?|schema|database|production|public api|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|api công khai|bí mật|thông tin xác thực)|(?:\bauth\b|authorization|authentication|security|permission|payment(?: handling| flow)?|schema|database|production|public api|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|api công khai|bí mật|thông tin xác thực).{0,64}(?:fix|change|modify|update|alter|migrate|drop|truncate|delete|remove|rotate|deploy|publish|push|sửa|thay đổi|cập nhật|xóa|xoá|di trú|chuyển đổi|triển khai)|database migration|schema migration|migrate database|migrate schema|drop table|truncate table|deploy(?:ment)?\s+(?:to\s+)?production|production\s+deploy(?:ment)?|rotate\s+(?:secret|credential)|breaking\s+(?:change\s+to\s+)?(?:public\s+)?api|npm publish|git push|force push|reset --hard|git clean)/i
+const LONG = /(whole repo|whole repository|whole project|entire repo|entire project|large refactor|major refactor|long[- ](?:running|horizon)|durable state|dependency graph|integration verification|resume|refactor all|multi[- ]step migration|migration across|toàn bộ repo|toàn bộ repository|toàn bộ dự án|toàn bộ project|refactor lớn|tác vụ dài|nhiều file|nhiều module|tiếp tục công việc|refactor toàn bộ|xác minh tích hợp|kiểm tra tích hợp|chia (?:công việc|task|tác vụ).*(?:dependency|phụ thuộc))/i
+const DEBUG = /(fix|bug|debug|crash|regression|failure|error|broken|sửa lỗi|lỗi|điều tra lỗi|không chạy)/i
+const CONTRACT = /(public api|api contract|openapi|response schema|request schema|breaking api|hợp đồng api|api công khai)/i
+const DATA = /(database|sql|migration|schema|transaction|index|cơ sở dữ liệu|dữ liệu|migrate)/i
+
+function riskTextFor(value) {
+  return String(value || "")
+    .replace(/\b(?:do not|don't|without)\s+(?:edit|modify|change|write|delete|remove)[^.\n]*/gi, "")
+    .replace(/\b(?:no|read[- ]only)\s+(?:edits?|changes?|writes?)[^.\n]*/gi, "")
+    .replace(/không\s+(?:sửa|chỉnh sửa|thay đổi|ghi|xóa|xoá)[^.\n]*/gi, "")
+    .replace(/chỉ\s+đọc[^.\n]*/gi, "")
+}
+
+function signal(name, matched, weight) {
+  return matched ? { name, weight } : null
+}
+
+function profileFor(mode, risk) {
+  if (mode === "inline" && risk === "low") {
+    return {
+      name: "fast",
+      maxSkills: 2,
+      contextBudget: 8_000,
+      contextStrategy: "incremental-semantic",
+      skillLoading: "direct-only",
+      durableState: false,
+      worktree: "off",
+      critic: "off",
+      verification: "targeted",
+      fullCI: false,
+      containerVerification: "off",
+    }
+  }
+  if (mode === "long-horizon" || risk === "high") {
+    return {
+      name: "deep",
+      maxSkills: 5,
+      contextBudget: 48_000,
+      contextStrategy: "semantic+graph+git",
+      skillLoading: "orchestrated",
+      durableState: true,
+      worktree: "auto-writers",
+      critic: "required-for-high-risk-or-final",
+      verification: "targeted+integration",
+      fullCI: true,
+      containerVerification: risk === "high" ? "preferred-if-capable" : "optional",
+    }
+  }
+  return {
+    name: "standard",
+    maxSkills: 4,
+    contextBudget: 20_000,
+    contextStrategy: "incremental-semantic+git",
+    skillLoading: "selective",
+    durableState: false,
+    worktree: "auto-on-conflict",
+    critic: "on-failure-or-elevated-risk",
+    verification: "targeted+affected",
+    fullCI: false,
+    containerVerification: "off",
+  }
+}
+
+function boundedInt(value, fallback, min, max) {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.min(max, Math.max(min, Math.round(parsed)))
+}
+
+export function recoveryPolicyForAttempt(taskPolicy = {}, attempt = 1) {
+  const normalizedAttempt = boundedInt(attempt, 1, 1, 99)
+  const baseBudget = boundedInt(
+    taskPolicy.contextBudget ?? taskPolicy.profile?.contextBudget,
+    20_000,
+    4_000,
+    48_000,
+  )
+  const baseSkills = boundedInt(
+    taskPolicy.maxSkills ?? taskPolicy.profile?.maxSkills,
+    4,
+    1,
+    5,
+  )
+  const baseStrategy = taskPolicy.profile?.contextStrategy || "incremental-semantic+git"
+
+  if (normalizedAttempt <= 1) {
+    return {
+      schemaVersion: 1,
+      stage: "initial",
+      attempt: normalizedAttempt,
+      contextBudget: baseBudget,
+      maxSkills: baseSkills,
+      contextStrategy: baseStrategy,
+      requireDiagnosis: false,
+      requireCritic: false,
+      modelEscalation: false,
+      directives: [],
+    }
+  }
+
+  if (normalizedAttempt === 2) {
+    return {
+      schemaVersion: 1,
+      stage: "diagnose",
+      attempt: normalizedAttempt,
+      contextBudget: Math.min(48_000, Math.max(baseBudget, Math.round(baseBudget * 1.35))),
+      maxSkills: Math.min(5, baseSkills + 1),
+      contextStrategy:
+        taskPolicy.executionProfile === "fast"
+          ? "incremental-semantic+git"
+          : baseStrategy,
+      requireDiagnosis: true,
+      requireCritic: false,
+      modelEscalation: true,
+      directives: [
+        "reproduce or capture the exact previous failure before editing",
+        "inspect the direct caller, nearest test and failure-adjacent evidence",
+        "do not stack another speculative patch on top of the failed attempt",
+      ],
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    stage: "deep-recovery",
+    attempt: normalizedAttempt,
+    contextBudget: Math.min(48_000, Math.max(20_000, Math.round(baseBudget * 1.75))),
+    maxSkills: Math.min(5, baseSkills + 2),
+    contextStrategy: "semantic+graph+git",
+    requireDiagnosis: true,
+    requireCritic: true,
+    modelEscalation: true,
+    directives: [
+      "re-investigate from fresh evidence and explicitly reject the failed hypothesis",
+      "expand to callers, dependencies, tests and boundary contracts before editing",
+      "challenge the architecture or coupling if repeated fixes expose a wider problem",
+      "run an independent critic or review pass before accepting the recovery",
+    ],
+  }
+}
+
+export function shouldRunDedicatedDiagnosis(taskPolicy = {}, attempt = 1) {
+  const hasDebugSignal = Array.isArray(taskPolicy.signals) &&
+    taskPolicy.signals.some((item) => item?.name === "debugging")
+  if (!hasDebugSignal) return false
+
+  const normalizedAttempt = boundedInt(attempt, 1, 1, 99)
+  if (normalizedAttempt > 1) {
+    return recoveryPolicyForAttempt(taskPolicy, normalizedAttempt).requireDiagnosis === true
+  }
+
+  return taskPolicy.executionProfile !== "fast" || taskPolicy.risk !== "low"
+}
+
+export function classifyEngineeringTask(text, facts = {}) {
+  const value = String(text || "")
+  const riskText = riskTextFor(value)
+  const sensitiveDomain = SENSITIVE_DOMAIN.test(value)
+  const sensitiveMutation = HIGH_RISK_MUTATION.test(riskText)
+  const declaredHighRisk =
+    ["high", "critical"].includes(String(facts.risk || "").toLowerCase()) ||
+    /\b(?:risk|rủi ro)\s*[:=\/-]?\s*(?:high|critical|cao|nghiêm trọng)\b/i.test(value) ||
+    /\b(?:high|critical)[-\s]?(?:risk|rủi ro)\b/i.test(value)
+  const declaredLongHorizon =
+    facts.longHorizon === true ||
+    ["long", "long-horizon", "deep"].includes(String(facts.mode || "").toLowerCase())
+  const compoundLongRisk =
+    /\blong\s*[/|,+]\s*(?:high|critical)[-\s]?risk\b/i.test(value) ||
+    /\b(?:high|critical)[-\s]?risk\s*[/|,+]\s*long\b/i.test(value)
+  const explicitLongHorizon = declaredLongHorizon || compoundLongRisk || LONG.test(value)
+  const signals = [
+    signal("long-request-text", value.length > 700, 1),
+    signal("medium-request-text", value.length > 250, 1),
+    signal("high-risk-domain", sensitiveDomain, 1),
+    signal("high-risk-operation", sensitiveMutation, 2),
+    signal("declared-high-risk", declaredHighRisk, 2),
+    signal("explicit-long-horizon", explicitLongHorizon, 2),
+    signal("debugging", DEBUG.test(value), 1),
+    signal("public-contract", CONTRACT.test(value) || facts.hasPublicContract, 2),
+    signal("data-migration", (DATA.test(riskText) && /migration|schema|migrate|di trú|chuyển đổi/i.test(riskText)) || facts.hasMigration, 2),
+    signal("many-changed-files", Number(facts.changedFiles || 0) > 5, 1),
+    signal("very-many-changed-files", Number(facts.changedFiles || 0) > 12, 1),
+    signal("large-repository", Number(facts.repoFiles || 0) > 1500, 1),
+    signal("monorepo", facts.monorepo === true, 1),
+  ].filter(Boolean)
+
+  const score = signals.reduce((sum, item) => sum + item.weight, 0)
+  const highRisk = declaredHighRisk || sensitiveMutation || Boolean(facts.hasMigration) || Boolean(facts.hasPublicContract)
+  const risk = highRisk ? "high" : score >= 3 ? "medium" : "low"
+  const mode = explicitLongHorizon || score >= 4 ? "long-horizon" : score >= 2 ? "standard" : "inline"
+  const modelTier = risk === "high" || mode === "long-horizon" ? "heavy" : score >= 2 ? "standard" : "light"
+  const maxAttempts = risk === "high" ? 2 : 3
+  const profile = profileFor(mode, risk)
+
+  const domains = []
+  if (/(auth|permission|tenant|token|session|phân quyền|xác thực)/i.test(value)) domains.push("auth-security")
+  if (/(payment|checkout|refund|webhook|thanh toán|hoàn tiền)/i.test(value)) domains.push("payment")
+  if (DATA.test(value)) domains.push("database")
+  if (CONTRACT.test(value)) domains.push("api-contract")
+  if (/(react native|expo|android|ios|gradle|xcode)/i.test(value)) domains.push("react-native")
+  else if (/(next\.js|nextjs|app router|server component)/i.test(value)) domains.push("nextjs")
+  else if (/\breact\b|useeffect|usestate|component/i.test(value)) domains.push("react")
+  if (/(docker|kubernetes|terraform|github actions|ci\/cd|deploy|triển khai)/i.test(value)) domains.push("devops")
+
+  return {
+    schemaVersion: 4,
+    score,
+    signals,
+    risk,
+    mode,
+    executionProfile: profile.name,
+    modelTier,
+    maxAttempts,
+    contextBudget: profile.contextBudget,
+    maxSkills: profile.maxSkills,
+    requirePlanCheck: profile.durableState || risk === "high",
+    requireIntegrationVerification: mode !== "inline" || risk === "high",
+    requireFreshEvidence: true,
+    profile,
+    domains: [...new Set(domains)],
+    recovery: {
+      escalateAfterFailure: true,
+      diagnosisBeforePatch: true,
+      deepRecoveryFromAttempt: 3,
+    },
+    antiHallucination: {
+      evidenceFirst: true,
+      noCompletionWithoutVerification: mode !== "inline" || risk === "high",
+      noUnsupportedSemanticClaims: true,
+      failClosedOnMissingCapability: risk === "high",
+    },
+  }
+}

package/lib/verification-broker.mjs

@@ -0,0 +1,284 @@
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { createHash, randomUUID } from "node:crypto"
+import { createVerificationReceipt, validateVerificationReceipt } from "./evidence-receipt.mjs"
+import { getEvidence, putEvidence } from "./evidence-store.mjs"
+import { runtimeWorkspaceFingerprint } from "./workspace-fingerprint.mjs"
+
+const CACHE_VERSION = 1
+const CACHE_FILE = "verification-broker-v1.json"
+
+const CACHE_WRITE_TAILS = new Map()
+const CACHE_LOCK_SUFFIX = ".lock"
+const CACHE_LOCK_STALE_MS = 5_000
+const CACHE_LOCK_WAIT_MS = 8_000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function cacheLockPath(root) {
+  return cachePath(root) + CACHE_LOCK_SUFFIX
+}
+
+async function withCrossProcessCacheLock(root, fn) {
+  const lockDir = cacheLockPath(root)
+  await mkdir(path.dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + CACHE_LOCK_WAIT_MS
+  let delayMs = 8
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+
+      const info = await stat(lockDir).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > CACHE_LOCK_STALE_MS) {
+        const confirmed = await stat(lockDir).catch(() => null)
+        if (
+          confirmed &&
+          confirmed.ino === info.ino &&
+          confirmed.mtimeMs === info.mtimeMs
+        ) {
+          await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          continue
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("Timed out waiting for verification broker cache lock")
+      }
+      await sleep(delayMs)
+      delayMs = Math.min(80, delayMs * 2)
+    }
+  }
+
+  try {
+    return await fn()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function withCacheWriteLock(root, fn) {
+  const key = path.resolve(root)
+  const previous = CACHE_WRITE_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  CACHE_WRITE_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await withCrossProcessCacheLock(root, fn)
+  } finally {
+    release()
+    if (CACHE_WRITE_TAILS.get(key) === tail) CACHE_WRITE_TAILS.delete(key)
+  }
+}
+
+function cachePath(root) {
+  return path.join(path.resolve(root), ".ues-cache", CACHE_FILE)
+}
+
+function keyFor(command, args = []) {
+  return createHash("sha256")
+    .update(JSON.stringify([String(command || ""), (args || []).map(String)]))
+    .digest("hex")
+}
+
+function receiptReusableAtFingerprint(receipt, fingerprint) {
+  if (!validateVerificationReceipt(receipt).valid) return false
+  if (receipt.exitCode !== 0 || receipt.passed !== true) return false
+  if (!Number.isFinite(Date.parse(receipt.startedAt || ""))) return false
+  if (!Number.isFinite(Date.parse(receipt.finishedAt || ""))) return false
+  return Boolean(
+    receipt.workspaceBefore &&
+    receipt.workspaceAfter &&
+    receipt.workspaceBefore === receipt.workspaceAfter &&
+    receipt.workspaceAfter === fingerprint
+  )
+}
+
+function entryMatchesKey(key, entry) {
+  const receipt = entry?.receipt
+  if (!receipt || !String(receipt.command || "").trim()) return false
+  if (!Array.isArray(receipt.args)) return false
+  return keyFor(receipt.command, receipt.args) === key
+}
+
+function finishedAtMs(entry) {
+  const value = Date.parse(entry?.finishedAt || entry?.receipt?.finishedAt || "")
+  return Number.isFinite(value) ? value : null
+}
+
+function freshEnough(entry, maxAgeMs, now = Date.now()) {
+  const finished = finishedAtMs(entry)
+  if (finished == null) return false
+  if (finished > now + 60_000) return false
+  if (!maxAgeMs) return true
+  return now - finished <= maxAgeMs
+}
+
+async function readCache(root) {
+  try {
+    const parsed = JSON.parse(await readFile(cachePath(root), "utf8"))
+    if (parsed?.schemaVersion !== CACHE_VERSION || typeof parsed.entries !== "object") return { schemaVersion: CACHE_VERSION, entries: {} }
+    return parsed
+  } catch {
+    return { schemaVersion: CACHE_VERSION, entries: {} }
+  }
+}
+
+async function writeCache(root, value) {
+  const file = cachePath(root)
+  await mkdir(path.dirname(file), { recursive: true })
+  const temp = file + "." + process.pid + "." + Date.now() + "." + randomUUID() + ".tmp"
+  await writeFile(temp, JSON.stringify(value, null, 2) + "\n", "utf8")
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+export async function findReusableVerification(root, command, args = [], options = {}) {
+  root = path.resolve(root)
+  const maxAgeMs = Math.max(0, Number(options.maxAgeMs ?? 20 * 60_000))
+  const cache = await readCache(root)
+  const key = keyFor(command, args)
+  const entry = cache.entries[key]
+  if (!entry || !entryMatchesKey(key, entry)) return null
+  if (!freshEnough(entry, maxAgeMs)) return null
+
+  const currentFingerprint = String(options.workspaceFingerprint || runtimeWorkspaceFingerprint(root))
+  if (!receiptReusableAtFingerprint(entry.receipt, currentFingerprint)) return null
+
+  const stdout = entry.stdoutRef
+    ? await getEvidence(root, entry.stdoutRef, { maxBytes: options.maxBytes || 16_000 }).catch(() => null)
+    : null
+  const stderr = entry.stderrRef
+    ? await getEvidence(root, entry.stderrRef, { maxBytes: options.maxBytes || 8_000 }).catch(() => null)
+    : null
+
+  return {
+    schemaVersion: 1,
+    reused: true,
+    key,
+    receipt: entry.receipt,
+    stdoutRef: entry.stdoutRef || null,
+    stderrRef: entry.stderrRef || null,
+    stdout: stdout?.content || "",
+    stderr: stderr?.content || "",
+    ageMs: Math.max(0, Date.now() - finishedAtMs(entry)),
+  }
+}
+
+export async function recordVerification(root, input = {}) {
+  root = path.resolve(root)
+  const stdout = String(input.stdout || "")
+  const stderr = String(input.stderr || "")
+  const stdoutEvidence = await putEvidence(root, stdout, {
+    kind: "verification-stdout",
+    source: input.command || "verification-broker",
+    summary: "Captured stdout preserved for reusable verification receipt",
+  })
+  const stderrEvidence = await putEvidence(root, stderr, {
+    kind: "verification-stderr",
+    source: input.command || "verification-broker",
+    summary: "Captured stderr preserved for reusable verification receipt",
+  })
+
+  const receipt = createVerificationReceipt({
+    task: input.task || null,
+    runId: input.runId || null,
+    command: input.command,
+    args: input.args || [],
+    cwd: root,
+    exitCode: input.exitCode,
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    durationMs: input.durationMs,
+    stdout,
+    stderr,
+    workspaceBefore: input.workspaceBefore || null,
+    workspaceAfter: input.workspaceAfter || runtimeWorkspaceFingerprint(root),
+  })
+
+  const key = keyFor(input.command, input.args || [])
+  await withCacheWriteLock(root, async () => {
+    const cache = await readCache(root)
+    cache.entries[key] = {
+      receipt,
+      stdoutRef: stdoutEvidence.ref,
+      stderrRef: stderrEvidence.ref,
+      finishedAt: receipt.finishedAt,
+    }
+
+    // Keep cache small and deterministic.
+    const rows = Object.entries(cache.entries)
+      .sort((a, b) => (finishedAtMs(b[1]) || 0) - (finishedAtMs(a[1]) || 0))
+      .slice(0, 200)
+    cache.entries = Object.fromEntries(rows)
+    await writeCache(root, cache)
+  })
+
+  return {
+    schemaVersion: 1,
+    reused: false,
+    key,
+    receipt,
+    stdoutRef: stdoutEvidence.ref,
+    stderrRef: stderrEvidence.ref,
+  }
+}
+
+export async function listReusableVerification(root, options = {}) {
+  root = path.resolve(root)
+  const currentFingerprint = String(options.workspaceFingerprint || runtimeWorkspaceFingerprint(root))
+  const maxAgeMs = Math.max(0, Number(options.maxAgeMs ?? 30 * 60_000))
+  const limit = Math.max(1, Math.min(50, Number(options.limit || 12)))
+  const now = Date.now()
+  const cache = await readCache(root)
+  const rows = []
+
+  for (const [key, entry] of Object.entries(cache.entries || {})) {
+    const receipt = entry?.receipt
+    if (!entryMatchesKey(key, entry)) continue
+    if (!receiptReusableAtFingerprint(receipt, currentFingerprint)) continue
+    const finished = finishedAtMs(entry)
+    if (!freshEnough(entry, maxAgeMs, now)) continue
+    rows.push({
+      key,
+      receipt,
+      stdoutRef: entry.stdoutRef || null,
+      stderrRef: entry.stderrRef || null,
+      finishedAt: entry.finishedAt || receipt.finishedAt || null,
+    })
+  }
+
+  rows.sort((a, b) => (Date.parse(b.finishedAt || "") || 0) - (Date.parse(a.finishedAt || "") || 0))
+  const selected = rows.slice(0, limit)
+  const output = []
+  for (const row of selected) {
+    const stdout = row.stdoutRef
+      ? await getEvidence(root, row.stdoutRef, { maxBytes: options.previewBytes || 2400 }).catch(() => null)
+      : null
+    const stderr = row.stderrRef
+      ? await getEvidence(root, row.stderrRef, { maxBytes: options.previewBytes || 1200 }).catch(() => null)
+      : null
+    output.push({
+      ...row,
+      stdoutPreview: stdout?.content || "",
+      stderrPreview: stderr?.content || "",
+    })
+  }
+  return {
+    schemaVersion: 1,
+    workspaceFingerprint: currentFingerprint,
+    count: output.length,
+    results: output,
+  }
+}

package/lib/verification-command.mjs

@@ -0,0 +1,111 @@
+export const VERIFICATION_COMMAND_RE =
+  /(?:^|\s|&&|;|\|)(?:pnpm|npm|yarn|bun|npx|node|python|pytest|go|cargo|dotnet|mvn|gradle|\.\/gradlew|gradlew\.bat)[^\n]*(?:test|jest|vitest|pytest|typecheck|tsc|lint|eslint|ruff|mypy|check|build|compile)/i
+
+export function looksLikeVerificationCommand(command = "") {
+  return VERIFICATION_COMMAND_RE.test(String(command || ""))
+}
+
+export function hasMaskedShellExitRisk(command = "") {
+  const value = String(command || "")
+  // Receipt reuse is an optimization, so ambiguity fails closed. Quoted shell
+  // metacharacters may cause a false negative here, which only means rerunning
+  // the check; it can never create a false PASS receipt.
+  if (value.includes("||") || value.includes(";") || value.includes("|") || /\r|\n/.test(value)) {
+    return true
+  }
+  // Reject a single/background '&' while allowing '&&'.
+  const withoutAndAnd = value.replaceAll("&&", "")
+  if (withoutAndAnd.includes("&")) return true
+  return false
+}
+
+export function canRecordReusableVerification(command = "") {
+  const value = String(command || "").trim()
+  return Boolean(value) &&
+    looksLikeVerificationCommand(value) &&
+    !hasMaskedShellExitRisk(value)
+}
+
+function tokenizeSimpleShell(command) {
+  const value = String(command || "").trim()
+  if (!value || hasMaskedShellExitRisk(value)) return null
+  // Exact executable+args reuse is stricter than generic receipt eligibility:
+  // a compound chain has one aggregate exit status but no single argv identity.
+  if (/&&|\|\||;|\||\r|\n/.test(value)) return null
+  // Fail closed on expansion, redirection, globs and backslash-sensitive
+  // shell syntax. Receipt reuse is only an optimization, so false negatives
+  // here cost latency rather than correctness.
+  if (/[<>\\]/.test(value) || value.includes("\u0060") || /\$\(|\$\{|\$[A-Za-z_]|%[A-Za-z_][A-Za-z0-9_]*%|\*|\?|\[|\]/.test(value)) return null
+
+  const tokens = []
+  let current = ""
+  let quote = null
+  let escaped = false
+
+  const push = () => {
+    if (!current) return
+    tokens.push(current)
+    current = ""
+  }
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]
+    if (escaped) {
+      current += char
+      escaped = false
+      continue
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true
+      continue
+    }
+    if (quote) {
+      if (char === quote) quote = null
+      else current += char
+      continue
+    }
+    if (char === "'" || char === '"') {
+      quote = char
+      continue
+    }
+    if (/\s/.test(char)) {
+      push()
+      continue
+    }
+    current += char
+  }
+
+  if (escaped || quote) return null
+  push()
+  return tokens.length ? tokens : null
+}
+
+export function canonicalVerificationCommand(command = "") {
+  const value = String(command || "").trim()
+  if (!canRecordReusableVerification(value)) return null
+
+  const tokens = tokenizeSimpleShell(value)
+  if (!tokens?.length) return null
+
+  const firstRaw = String(tokens[0] || "")
+  const first = firstRaw.toLowerCase()
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(firstRaw) || firstRaw.startsWith("~")) {
+    return null
+  }
+  if ((first === "cmd" || first === "cmd.exe") && /^\/c$/i.test(tokens[1] || "")) {
+    if (tokens.length < 3 || /\s/.test(tokens[2])) return null
+    return { command: tokens[2], args: tokens.slice(3), raw: value }
+  }
+
+  // PowerShell -Command is intentionally not canonicalized: quoting and command
+  // parsing semantics are too rich for a safe exact-reuse key.
+  if (first === "powershell" || first === "powershell.exe" || first === "pwsh" || first === "pwsh.exe") {
+    return null
+  }
+
+  return {
+    command: tokens[0],
+    args: tokens.slice(1),
+    raw: value,
+  }
+}

package/lib/windows-shim.mjs

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs"
 import path from "node:path"
+import os from "node:os"
 import { spawnSync } from "node:child_process"
 
 function within(base, candidate) {
@@ -219,6 +220,40 @@ export function resolveWindowsCommand(name) {
   return resolveWindowsCommandCandidates(candidates)
 }
 
+export function resolveManagedPiCommand(homeDir = os.homedir()) {
+  const releasesDir = path.join(homeDir, ".pi", "agent", "install", "releases")
+  let releases = []
+  try {
+    releases = readdirSync(releasesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: "base" }))
+  } catch {
+    return null
+  }
+
+  for (const release of releases) {
+    const packageDir = path.join(
+      releasesDir,
+      release,
+      "node_modules",
+      "@earendil-works",
+      "pi-coding-agent",
+    )
+    const target = packageBinTarget(packageDir, "pi")
+    if (!target) continue
+    const resolved = executionForTarget(target)
+    if (resolved) {
+      return {
+        ...resolved,
+        source: target,
+        managedRelease: release,
+      }
+    }
+  }
+  return null
+}
+
 function spawnWhere(name) {
   // Lazy import avoidance is unnecessary here; child_process is builtin and this
   // module is Node-only. Kept as one helper so tests can cover candidate selection