@mcrescenzo/opencode-workflows 0.1.0

package/skills/opencode-workflow-authoring/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: opencode-workflow-authoring
+description: Use when creating, editing, reviewing, debugging, or explaining OpenCode workflows run by the workflow_* plugin tools. Covers QuickJS sandbox limits, top-level return shape, agent/parallel/pipeline fan-out, the scoped-callback arity contract, phase-loop orchestration, model tiers and per-lane effort, budget self-scaling, sourceHash/approvalHash and autoApprove launch modes, inline result readback, edit/apply boundaries, static nested workflows, roles, schema lanes, and background runs.
+---
+
+# OpenCode Workflow Authoring
+
+Use this skill for workflow source and behavior: writing a new workflow, editing
+or reviewing an existing one, debugging a stalled or misleading run, or
+explaining how approval, sandboxing, fan-out, edit/apply, background, or resume
+works. For simple "run / status / cancel / save this workflow" operations, use
+the relevant command or `workflow_*` tool directly.
+
+## Phase Loop
+
+The primary pattern is **author -> run -> read -> decide**:
+
+1. Author a small workflow source or choose a saved workflow.
+2. Run a narrow slice first. Prefer `profile: "read-only-review"` unless the
+   question truly needs shell, network, MCP, or edit authority.
+3. Read the result with `workflow_status({ runId, detail: "result" })`, or use
+   the inline foreground result returned by `workflow_run` when it fits the safe
+   display cap.
+4. Decide whether to widen scope, add lanes, raise budget, switch authority, or
+   stop. Do not build one giant workflow before proving the slice.
+
+If the plugin owner configured `options.autoApprove`, eligible runs can launch on
+the first `workflow_run` call when their resolved authority tier is within that
+ceiling. Otherwise, use the preview plus `approvalHash` flow. `workflow_apply`
+keeps its separate hash gate either way.
+
+## Source Shape
+
+A workflow body is top-level JavaScript statements ending in `return <result>`.
+The only allowed export is `export const meta = { ... }`. Do not wrap the body
+in a function and do not use `export default`.
+
+```js
+export const meta = {
+  name: "review-slice",
+  description: "One narrow read-only review slice",
+  profile: "read-only-review",
+  maxAgents: 2,
+  concurrency: 2,
+};
+
+const notes = await parallel([
+  async ({ agent }) => await agent("Inspect the entrypoints", { role: "explorer" }),
+  async ({ agent }) => await agent("Inspect the tests", { role: "explorer" }),
+]);
+
+return { notes };
+```
+
+Injected globals are `agent`, `parallel`, `pipeline`, `workflow`, `phase`,
+`log`, `budget`, and `args`; do not import them.
+
+## QuickJS Sandbox
+
+The body runs in a deterministic QuickJS sandbox, not Node. Filesystem, process,
+network, clocks, timers, randomness, `crypto`, and imports are unavailable.
+`Date`, `Date.now`, `Math.random`, `performance`, `setTimeout`, `setInterval`,
+`clearTimeout`, and `clearInterval` throw if called. Use `workflow_status` run
+artifacts for timing and diagnostics instead of in-guest clocks.
+
+## Fan-Out And Arity
+
+Use the scoped-helper callback form for `parallel()` and `pipeline()`:
+
+```js
+await parallel([
+  async ({ agent }) => await agent("first task"),
+  async ({ agent }) => await agent("second task"),
+]);
+
+await pipeline(items,
+  async (previous, { agent, item, itemIndex, stageIndex }) => await agent(`inspect ${item}`),
+  async (finding, { agent, item }) => await agent(`review ${item}: ${finding}`),
+);
+```
+
+Callback functions must declare the expected parameters. The kernel hard-errors
+ambiguous arity instead of guessing whether a zero-arg thunk should be scoped or
+legacy sequential behavior. Keep call order deterministic so lane signatures and
+resume replay stay stable.
+
+Guard every wave's outcome. A wave that silently drops most lanes can feed empty
+data into synthesis and produce a false "nothing found" result. Use `failFast`
+or explicit result-count checks when missing lanes invalidate the next phase.
+
+## Models, Effort, And Roles
+
+Set `modelTiers: { fast, deep }` on `workflow_run` and tag lanes with
+`tier: "fast"` or `tier: "deep"` when a workflow needs different model strength.
+Run `workflow_models` first and keep tiers inside the session family unless the
+user approves a deviation.
+
+OpenAI lanes may additionally request `effort: "minimal" | "low" | "medium" |
+"high"`. This is applied through OpenAI `chat.params` provider options and fails
+before child launch for unsupported providers.
+
+Pass `role: "explorer" | "skeptic" | "verifier" | "synthesizer" |
+"implementer"` to prepend a specialist prompt. Role `.md` files stay pure prompt
+text; optional sibling `roles.json` defaults can set model/tier, tools/readOnly,
+retry/timeout, and narrow policy knobs before explicit lane opts override them.
+Use `workflow_roles` to inspect available role files, hashes, and defaults.
+
+## Budgets And Scaling
+
+`maxAgents` caps total child lanes launched. `concurrency` caps in-flight lanes.
+Each `agent()` call consumes one slot; pure-JavaScript synthesis consumes none.
+
+Use `budget.remainingAgents()`, `budget.remaining()`, and `budget.ceilings()` to
+self-scale loops. Budget headroom includes live spend, replayed spend, and
+in-flight reservations, so a loop can stop before launching the next child.
+Setting `maxCost` or `maxTokens` is an approval-envelope decision, not a casual
+throttle.
+
+## Schema Lanes
+
+Use `schema` when a lane result must be structured. Native structured output is
+used when available; otherwise the kernel uses structured-text instructions plus
+Ajv validation. Correctable schema/text failures can retry in the same child
+session according to `correctiveRetries`, and exhausted validation failures are
+journaled distinctly from transient provider errors.
+
+## Nested Workflows
+
+Use direct static literals only: `workflow("saved-name", args)` or
+`workflow({ source: "return 1;", args })`. Dynamic or aliased nested workflow
+calls are rejected before approval because the source cannot be snapshotted into
+the hash. Only one nesting level is supported, and nested lanes share the parent
+run's `maxAgents`, concurrency, and budget ceilings.
+
+## Launch And Readback
+
+Default launch is two-phase: call `workflow_run` for a preview, then call again
+with `approve: true` and the matching `approvalHash`. With configured
+`options.autoApprove`, eligible readOnly/worktree/all-tier runs can launch on
+the first call; a per-call `autoApprove` argument may narrow that ceiling.
+
+Foreground runs return a size-capped, secrets-redacted inline result when it
+fits. Always prefer `workflow_status({ runId, detail: "result" })` for the final
+answer path, especially for large results where inline output is omitted or
+partial.
+
+## Background Runs
+
+Explicit `background: true` returns quickly with a run id while execution
+continues in the current OpenCode process. When `background` is omitted, the
+kernel defaults wide, deep, or long runs to background using the
+wide/deep/long heuristic; explicit `background: true` or `false` wins, and
+resume keeps the pinned mode. Background execution is not durable across process
+death; use `workflow_status`, `workflow_cancel`, `workflow_pause`, and
+`workflow_reconcile` for inspection and lifecycle control.
+
+## Edit And Apply
+
+Edit authority is only a cap. A lane receives edit tools only when it explicitly
+requests edit/worktree behavior. Edit-capable lanes run in isolated workflow
+worktrees or directories. Primary-tree writes happen through `workflow_apply`
+after source/base/diff/domain hashes and Git state are checked. Successful
+non-dry Beads drain is the special trusted extension path that can finalize
+in-run after its launch approval.
+
+## Review Checklist
+
+- Top-level body ends in `return`; only `export const meta` is exported.
+- No Node, imports, clocks, timers, randomness, or filesystem assumptions.
+- `parallel()` / `pipeline()` callbacks use explicit scoped-helper arity.
+- Fan-out waves check dropped/null lane outcomes before synthesis.
+- `maxAgents`, `concurrency`, timeouts, and budget ceilings match expected
+  lane count and cost risk.
+- Model tiers, per-lane `effort`, roles, and schemas are deliberate.
+- Nested workflow calls are static and one level deep.
+- Readbacks use inline result only when it fits; otherwise use
+  `workflow_status({ detail: "result" })`.
+- Edit lanes stop at `workflow_apply` unless using a trusted autonomous drain.
+- After changing workflow source, commands, skills, plugin code, or registration
+  behavior, restart OpenCode or use a fresh child process.

package/skills/repo-review-command-protocol/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: repo-review-command-protocol
+description: Use when running or maintaining the bundled /repo-bughunt and /repo-review commands. Provides the shared command wrapper protocol for JSON argument validation, workflow_run launch by name, workflow_status detail=result readback, .repo-review/runs report persistence, report-only mutation boundaries, and concise closeout.
+---
+
+# Repo-Review Command Protocol
+
+This skill holds the shared command wrapper protocol for `/repo-bughunt` and
+`/repo-review`. The command markdown supplies command-specific defaults,
+workflow name, model-tier policy, result fields, and optional materialization
+handling.
+
+## Shared Steps
+
+1. Parse `$ARGUMENTS` before touching `workflow_run`.
+   - Empty arguments use the command's documented default object.
+   - Non-empty arguments must parse as valid JSON and resolve to a plain object.
+   - On parse failure or non-object input, STOP before `workflow_run`; report the
+     offending value and expected object shape.
+
+2. Resolve models before launch.
+   - Follow `workflow-model-tiering` unless the command markdown declares a
+     command-specific model policy.
+   - Pass the final map as `modelTiers`.
+
+3. Launch by bundled workflow name, never by path.
+   - Use `workflow_run({ name, args, modelTiers, format: "json" })`.
+   - If the call returns a preview, report `approvalHash`,
+     `authority.profile`, and `modelPlan`, then launch with `approve: true` and
+     the matching hash.
+   - If configured `autoApprove` makes the first call execute immediately, report
+     the returned `runId` and status instead of inventing a preview step.
+
+4. Read the terminal result through
+   `workflow_status({ runId, detail: "result" })`.
+   - Use `.result.output` as the envelope.
+   - Treat raw `.opencode/workflows/runs/` files as local-sensitive artifacts.
+
+5. Persist exactly one report under `.repo-review/runs/`.
+   - Create the directory if needed with `mkdir -p .repo-review/runs`.
+   - Use the command-specific filename suffix.
+   - Prefer the command-specific full report source. If the full markdown is
+     absent or omitted for size, synthesize the documented fallback summary from
+     returned `summary`, `counts`, and `findings` only.
+   - Add a `Report-only - nothing applied.` footer.
+
+6. Enforce the report-only boundary.
+   - The ONLY allowed workspace write is the local report file.
+   - The command itself must never run `materialize`, `beads-drain`,
+     `workflow_apply`, any `git` write, or any `bd` create/update/close/claim.
+   - Do not stage or commit the report; `.repo-review/` is gitignored.
+
+7. Report back concisely.
+   - Include validated args, model plan, approval hash when there was a preview,
+     run id, terminal status, envelope status/summary/counts, report source or
+     fallback mode, truncation flags, and the absolute report path.

package/skills/workflow-model-tiering/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: workflow-model-tiering
+description: Use BEFORE running any workflow whose lanes declare fast/deep tiers (e.g. repo-bughunt). Enumerate available models with workflow_models, map fast/deep to concrete models in the invoking session's family, and confirm with the user ONLY when the plan deviates from that family.
+---
+
+# Workflow model tiering
+
+Workflows declare each lane's intent as `tier: "fast"` (cheap/bulk) or `tier: "deep"`
+(subtle reasoning); pure-JS lanes declare no model. The kernel resolves each tier to a
+concrete `provider/model` string from the run's `modelTiers` map, falling back to the
+invoking session's model (and finally to `DEFAULT_CHILD_MODEL`). Your job before running
+such a workflow is to pick the concrete fast/deep models and pass them as `modelTiers`.
+
+## Procedure
+
+1. **Enumerate.** Call `workflow_models`. Read `session.model` / `session.family` and the
+   available `providers[].models` (each model may list reasoning `variants`, e.g. `max`).
+   `suggested.fast` / `suggested.deep` both default to the session model — a safe
+   no-deviation starting point.
+
+2. **Map within the session family.** Choose concrete `fast`/`deep` models *inside the
+   session family*:
+   - `fast` = the session model (or the cheapest reasonable model in the family).
+   - `deep` = a higher-reasoning model or reasoning variant in the same family if one
+     exists (e.g. a `max` variant). If the family has only one model, `deep = fast`.
+
+3. **Deviation check.** The plan is NON-deviating when both tiers stay in the session
+   family at standard escalation. It DEVIATES when you pick a different provider family, a
+   premium cross-family `deep`, or mix families.
+   - **No deviation:** proceed. The `workflow_run` approval preview shows the model plan
+     (`Model plan: fast=… deep=…`); the user approving that preview is the confirmation.
+     Do NOT add a separate prompt.
+   - **Deviation:** STOP and confirm explicitly with the user — state the chosen models and
+     why — BEFORE calling `workflow_run`.
+
+4. **Run.** Call `workflow_run({ name: "<workflow>", args: {...}, modelTiers: { fast, deep } })`,
+   read the `approvalHash` from the returned preview, then call again with `approve: true`
+   and that `approvalHash`. Never set `maxCost` / `maxTokens` casually; ceilings are
+   part of the approved envelope, and workflow bodies should use `budget.remaining()`
+   or `budget.ceilings()` when they need to self-scale.
+
+## Notes
+
+- Omitting `modelTiers` is valid: every tier then resolves to the session model (a safe
+  no-deviation default). Pass `modelTiers` only to differentiate `deep` from `fast`.
+- An explicit per-lane `model` in a workflow's source overrides tiers entirely;
+  report-only review workflows should not use it.
+- A per-lane `effort` hint is separate from tier selection. Use it only for lanes
+  that resolve to an OpenAI provider, with `minimal`, `low`, `medium`, or `high`
+  values, for example `agent(prompt, { tier: "deep", effort: "high" })`. The
+  plugin applies it through OpenAI `chat.params` provider options. Do not assume
+  provider variants or non-OpenAI providers support this knob; unsupported
+  providers fail before child launch.
+- `modelTiers` is covered by the approval hash, so changing the model plan re-triggers
+  approval — you cannot silently swap models behind an already-approved hash.
+- Models are `provider/model` strings (exactly one `/`). A malformed tier value is a hard
+  error at planning time.

package/skills/workflow-plan-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: workflow-plan-review
+description: Use whenever you are about to run an OpenCode workflow via workflow_run, or have just called it without approve and are holding the approval summary. Covers presenting the workflow plan to the user human-first, offering structured refinement knobs plus free-text, choosing between configured autoApprove and manual approvalHash launch, and reading results back. Distinct from workflow-model-tiering and opencode-workflow-authoring.
+---
+
+# Workflow plan review (the run handoff)
+
+Workflow authority is fixed **once at launch**. On the manual path, the approval
+hash covers the whole envelope (source, args, authority, models, budgets,
+concurrency, capabilities, nested snapshots). On the configured `autoApprove`
+path, eligible runs can launch on the first call when their resolved authority
+tier is within the configured ceiling. In both cases, treat the launch plan as
+something to understand and refine, not a hash to echo back.
+
+## Procedure
+
+1. **Get the plan or run.** Prefer `workflow_run({ name: "...", args: {...}, format: "json", ... })`.
+   If the plugin is not auto-approving this authority tier, the returned JSON is a typed
+   `workflow_preview` envelope with `executed: false`, `approvalHash`, `workflow`, `source`,
+   `runtimeArgsPreview`, `laneBudget`, `modelPlan`, `budgetCeilings`, `background`, `authority`,
+   `mutationDomains`, `capabilities`, and `nestedSnapshots`. If configured `autoApprove` makes the
+   call execute immediately, report the run id/status and move to result readback instead of
+   inventing a preview step.
+
+2. **Present human-first.** Summarize the plan to the user in your own words, leading with what
+   they actually care about, in roughly this order:
+   - **What it will do** — the Description and the scope in `Runtime args preview`.
+   - **Models** — `Default child model` and `Model plan: fast=… deep=…`.
+   - **Lane budget** — `Max agents` (the ceiling on child lanes) and `Concurrency` (peak parallel).
+   - **Cost/time** — `Budget ceilings`, `Lane timeout`, and the run deadline if present.
+   - **Authority** — `Authority profile`, `Required gates`, `Isolation`, `Mutation domains`. Call
+     out anything that mutates state or stops at `awaiting-diff-approval` / in-run apply.
+   - **Background** — `Background: true/false`, and the heuristic recommendation line if present.
+   You may condense or omit the technical envelope (hashes/capabilities/consent) from what you
+   show the user — it is there for accuracy, not for the headline.
+
+3. **Offer refinement.** Give the user concrete knobs to tweak, plus a free-text channel. Surface
+   the knobs that are relevant to *this* workflow.
+
+   **Universal knobs** (every workflow accepts these as `workflow_run` args):
+   - `modelTiers: { fast, deep }` — see the `workflow-model-tiering` skill for how to pick them.
+   - `maxAgents` — ceiling on child lanes launched (one slot per `agent()` lane).
+   - `concurrency` — peak parallel lanes.
+   - `background: true/false` — keep a control channel for pause/cancel on long runs.
+   - `maxCost` / `maxTokens` — budget ceilings are approval-envelope decisions; workflow bodies can
+     self-scale with `budget.remaining()` and `budget.ceilings()`.
+   - `laneTimeoutMs` (alias `childPromptTimeoutMs`) — per-lane prompt cap.
+
+   **Per-workflow scope knobs** — read them from `runtimeArgsPreview` (or the text preview's
+   `Runtime args preview` line) and the workflow's declared args (e.g. `paths`/`depth`/
+   `categories` for repo-bughunt, `domains`/
+   `batchSize` for repo-review, `mode`/`scope` for beads-drain). If you are unsure which scope args
+   a named workflow accepts, check `workflow_list` or read its source before offering them.
+
+4. **Re-plan on any change.** If the user refines anything, re-call `workflow_run` **without**
+   `approve` with the new args/modelTiers/budget. You get a fresh preview and a fresh `approvalHash`
+   (the old hash is now stale and `approve:true` with it returns `approval_mismatch` and
+   `executed:false`). Present again. This loop is free — use it.
+
+5. **Approve or continue.** For the manual path, once the user confirms the plan, re-call
+   `workflow_run` with `approve: true` and the matching `approvalHash` from the most recent preview.
+   Do not call `approve: true` in the same turn you presented the plan unless the user already said
+   to run it. For an auto-approved run, skip this step and read back the result.
+
+## When you may skip the confirmation step
+
+- The plugin is configured with `options.autoApprove` and the resolved authority tier is covered by
+  that ceiling; the first `workflow_run` call may execute immediately.
+- The user explicitly said to just run it ("go ahead", "run it", "approve") in this turn or a prior
+  instruction that clearly covers this run.
+- You are **resuming** an already-approved envelope via `resumeRunId` (the user already approved
+  that envelope; resume replays/re-runs under the same hash). A *cold* plan is always confirmed.
+
+If unsure whether the user pre-authorized, ask. A confirmation question is always cheaper than an
+unwanted multi-lane run.
+
+## Graceful degradation
+
+Not every workflow has a static lane count you can quote up front:
+
+- **Static fan-out** (repo-bughunt, repo-* leaves, repo-review): the structure is knowable
+  (e.g. recon → N finders → skeptics → pure-JS synth), but some counts depend on results (number
+  of skeptics depends on number of findings). Present the *structure* and flag counts that are
+  data-dependent rather than implying a fixed number.
+- **Discovery-driven** (beads-drain): the lane count depends on the live backlog. For beads-drain
+  specifically, the dry-run (`mode: "dry-run"`) **is** the plan — it reports the ready items that
+  would be worked. Offer a dry-run as the preview for non-dry intent.
+- **Dynamic/inline**: if you cannot determine the structure, say so plainly and lean on the
+  envelope (authority, models, budget, background) plus `Max agents` as the ceiling.
+
+In all cases, present what you know and label what is uncertain. Never invent a precise lane count.

package/workflow-kernel/approval-hashing.js

@@ -0,0 +1,39 @@
+import { hash, hashStable, stableStringify } from "./text-json.js";
+
+export function approvalSnapshotList(nestedSnapshots) {
+  return [...new Map([...(nestedSnapshots?.values?.() ?? [])].map((item) => [item.sourcePath, item])).values()]
+    .map(({ sourcePath, sourceHash }) => ({ sourcePath, sourceHash }))
+    .sort((a, b) => `${a.sourcePath}:${a.sourceHash}`.localeCompare(`${b.sourcePath}:${b.sourceHash}`));
+}
+
+export function approvalEnvelope(approval) {
+  return {
+    version: 2,
+    sourcePath: approval.sourcePath,
+    sourceHash: approval.sourceHash,
+    runtimeArgs: approval.runtimeArgs ?? null,
+    maxAgents: approval.maxAgents,
+    concurrency: approval.concurrency,
+    defaultChildModel: approval.defaultChildModel,
+    modelTiers: approval.modelTiers ?? null,
+    authority: approval.authority,
+    budgetCeilings: approval.budgetCeilings,
+    baseCommit: approval.baseCommit ?? null,
+    guestDeadlineMs: approval.guestDeadlineMs,
+    laneTimeoutMs: approval.laneTimeoutMs ?? null,
+    debugCapture: approval.debugCapture === true,
+    background: approval.background === true,
+    resumeRunId: approval.resumeRunId ?? null,
+    resumePolicy: approval.resumePolicy ?? null,
+    capabilities: approval.capabilities,
+    nestedSnapshots: approvalSnapshotList(approval.nestedSnapshots),
+  };
+}
+
+export function approvalHash(approval) {
+  return hashStable(approvalEnvelope(approval));
+}
+
+export function computeDiffPlanHash(plan) {
+  return hash(stableStringify({ patches: plan.patches, sourceHash: plan.sourceHash, baseCommit: plan.baseCommit, domainMutationHash: plan.domainMutationHash }));
+}

package/workflow-kernel/async-util.js

@@ -0,0 +1,33 @@
+import { WorkflowCancelledError, WorkflowTimeoutError } from "./errors.js";
+
+export async function withTimeout(factory, { timeoutMs, signal, label, onTimeout }) {
+  if (signal?.aborted) {
+    Promise.resolve().then(() => onTimeout?.("abort")).catch(() => {});
+    throw new WorkflowCancelledError();
+  }
+  let timeout;
+  let abortListener;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(factory),
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+          reject(new WorkflowTimeoutError(`${label} timed out after ${timeoutMs}ms`));
+          Promise.resolve().then(() => onTimeout?.()).catch(() => {
+            // Timeout cleanup is best effort; the timeout itself is still authoritative.
+          });
+        }, timeoutMs);
+        abortListener = () => {
+          reject(new WorkflowCancelledError());
+          Promise.resolve().then(() => onTimeout?.("abort")).catch(() => {
+            // Abort cleanup is best effort; the abort itself is still authoritative.
+          });
+        };
+        signal?.addEventListener("abort", abortListener, { once: true });
+      }),
+    ]);
+  } finally {
+    clearTimeout(timeout);
+    if (abortListener) signal?.removeEventListener("abort", abortListener);
+  }
+}

package/workflow-kernel/audited-shell-policy.js

@@ -0,0 +1,200 @@
+// Audited-shell + network-advisory deep-mode policy for repo-review (iui1.7).
+//
+// repo-review ships static + read-only by default (profile "read-only-review": readOnly, no
+// shell/network/mcp). Two OPTIONAL deep modes are available behind verified gates:
+//   - audited-shell:   the inspect-with-shell profile (readOnly + shell) with a STRICT read-only
+//                      command allowlist (git ls-files, git log --numstat, npm ls --depth=0,
+//                      cargo tree, pip list, go list). Installs, audit-network, and ANY mutation
+//                      command are denied. Enables real git-churn for complexity + live dep lists.
+//   - network-advisory: a network:true profile for advisory API lookups (npm advisory, OSV,
+//                       GitHub advisories). No mutation.
+//
+// Both modes are EXPLICITLY opt-in (args.deepMode or args.profile). Static mode never requests
+// shell or network. When a deep mode is requested but the required gates are UNVERIFIED, the mode
+// FAILS CLOSED: it degrades to static and records the limitation (shellCoverage stays "none").
+//
+// This module is PURE (no fs/shell/network) so the policy is fully unit-testable without verified
+// gates or a real repo. The QuickJS repo-review guest cannot import it; the guest stays static and
+// surfaces the requested mode + coverage limitation, while the command wrapper / kernel rely on
+// this policy when a caller opts in via workflow_run({ profile }) — the kernel enforces the
+// profile's requiredGates at plan time.
+
+export const AUDITED_SHELL_ALLOWLIST = Object.freeze([
+  // Read-only manifest/tree/listing commands only. Each entry is a command-prefix (program + the
+  // fixed leading args) that a shell lens may run. Anything else is denied.
+  { id: "git-ls-files", prefix: ["git", "ls-files"], note: "tracked file inventory" },
+  { id: "git-log-numstat", prefix: ["git", "log", "--numstat"], note: "per-file churn history" },
+  { id: "npm-ls", prefix: ["npm", "ls", "--depth=0"], note: "installed dependency tree (local)" },
+  { id: "cargo-tree", prefix: ["cargo", "tree"], note: "cargo dependency tree (local)" },
+  { id: "pip-list", prefix: ["pip", "list"], note: "installed python packages (local)" },
+  { id: "go-list", prefix: ["go", "list"], note: "go module list (local)" },
+]);
+
+// Forbidden substrings/tokens — any command matching one of these is REJECTED even if its prefix is
+// allowlisted. These are the install / audit-network / mutation / shell-meta dangers.
+export const AUDITED_SHELL_DENY = Object.freeze([
+  { id: "install", test: /\b(npm|yarn|pnpm)\s+(install|i|add)\b|\bpip3?\s+install\b|\binstall-packages\b|\bpip-install\b/i, reason: "package installation is a mutation" },
+  { id: "yarn-add", test: /\byarn\s+add\b/i, reason: "yarn add is a mutation" },
+  { id: "npm-audit", test: /\bnpm\s+audit\b/i, reason: "npm audit reaches the network; use network-advisory mode for advisories" },
+  { id: "pip-audit", test: /\bpip-?audit\b/i, reason: "pip-audit reaches the network" },
+  { id: "npm-publish", test: /\b(npm\s+publish|publish)\b/i, reason: "publishing is a mutation" },
+  { id: "git-mutation", test: /\bgit\s+(commit|push|merge|rebase|reset|checkout|switch|stash|cherry-pick|tag)\b/i, reason: "git mutation" },
+  { id: "go-get", test: /\bgo\s+get\b/i, reason: "go get mutates modules / reaches the network" },
+  { id: "go-install", test: /\bgo\s+install\b/i, reason: "go install mutates the local toolchain/module cache" },
+  { id: "cargo-add", test: /\bcargo\s+add\b/i, reason: "cargo add is a mutation" },
+  { id: "cargo-install", test: /\bcargo\s+install\b/i, reason: "cargo install mutates the local toolchain cache" },
+  { id: "redirect", test: /(^|\s)(>|>>|\||&&|;|\|\|)\s*/, reason: "shell redirection/chaining is forbidden" },
+  { id: "substitution", test: /(\$\(|`|<\()/, reason: "shell command/process substitution is forbidden" },
+  { id: "rm-mutation", test: /\b(rm|mv|cp|mkdir|rmdir|chmod|chown|touch|tee)\b/i, reason: "filesystem mutation" },
+  { id: "curl-wget", test: /\b(curl|wget|nc|ssh|scp|rsync)\b/i, reason: "network fetch belongs in network-advisory mode, not audited-shell" },
+]);
+
+// Validate a single shell command against the audited-shell policy. Returns {allowed, reason}.
+// `command` is a string (the full command line) or an argv array.
+export function validateAuditedCommand(command) {
+  const argv = Array.isArray(command)
+    ? command.map(String)
+    : String(command ?? "").trim().split(/\s+/).filter(Boolean);
+  if (argv.length === 0) return { allowed: false, reason: "empty command" };
+  // Denylist first (defense-in-depth): an allowlisted prefix with a forbidden token is still rejected.
+  const joined = argv.join(" ");
+  for (const rule of AUDITED_SHELL_DENY) {
+    if (rule.test.test(joined)) return { allowed: false, reason: `denied (${rule.id}): ${rule.reason}` };
+  }
+  // Allowlist: the command's leading tokens must EXACTLY match one allowlisted prefix.
+  const match = AUDITED_SHELL_ALLOWLIST.find((entry) => {
+    if (argv.length < entry.prefix.length) return false;
+    return entry.prefix.every((tok, i) => argv[i] === tok);
+  });
+  if (!match) {
+    return { allowed: false, reason: `command not in the audited-shell allowlist (allowed: ${AUDITED_SHELL_ALLOWLIST.map((a) => a.prefix.join(" ")).join("; ")})` };
+  }
+  return { allowed: true, reason: `allowlisted:${match.id}`, matched: match };
+}
+
+// OpenCode permission-rule wildcard deny patterns that translate the AUDITED_SHELL_DENY concerns into
+// the runtime permission ruleset. These are positioned AFTER the allow patterns in the generated
+// rules (last-match-wins), so a dangerous argument tacked onto an allowlisted command is still
+// denied (e.g. `git ls-files && rm x` matches `*&&*`). Patterns use OpenCode simple wildcards:
+// `*` = zero-or-more of any char, `?` = exactly one char, all else literal.
+//
+// Kept in lock-step with AUDITED_SHELL_DENY above so validateAuditedCommand (the pure unit-testable
+// validator) and the runtime permission ruleset enforce the SAME dangerous classes.
+export const SHELL_PERMISSION_DENY_PATTERNS = Object.freeze([
+  // Shell chaining / pipes / redirection — a read-only inspection shell never composes or redirects.
+  "*&&*", "*||*", "*;*", "*|*", "*>*", "*<*",
+  // Command/process substitution (AUDITED_SHELL_DENY "substitution").
+  "*$(*", "*`*",
+  // Filesystem mutation (AUDITED_SHELL_DENY "rm-mutation").
+  "*rm *", "*rmdir *", "*mv *", "*cp *", "*mkdir *", "*chmod *", "*chown *", "*touch *", "*tee *",
+  // Network fetch (AUDITED_SHELL_DENY "curl-wget") — belongs in network-advisory, not audited-shell.
+  "*curl*", "*wget*", "*nc *", "*ssh *", "*scp *", "*rsync *",
+  // Package install / add / publish (AUDITED_SHELL_DENY "install"/"yarn-add"/"cargo-add"/"go-get"/"go-install"/"npm-publish").
+  "npm install", "npm install *", "npm i", "npm i *", "npm add", "npm add *",
+  "pnpm install", "pnpm install *", "pnpm add", "pnpm add *",
+  "yarn install", "yarn install *", "yarn add", "yarn add *",
+  "pip install", "pip install *", "pip3 install", "pip3 install *", "*install-packages*", "*pip-install*",
+  "go get", "go get *", "go install", "go install *", "cargo add", "cargo add *", "cargo install", "cargo install *", "*publish*",
+  // Networked audit tools (AUDITED_SHELL_DENY "npm-audit"/"pip-audit").
+  "*npm audit*", "*pip-audit*", "*pip audit*",
+  // Git mutation (AUDITED_SHELL_DENY "git-mutation").
+  "*git commit*", "*git push*", "*git merge*", "*git rebase*", "*git reset*", "*git checkout*", "*git switch*", "*git stash*", "*git cherry-pick*", "*git tag*",
+]);
+
+// Translate the audited-shell allowlist + denylist into OpenCode permission-rule wildcard patterns
+// ({ allow: [...], deny: [...] }). Each allowlisted command prefix becomes TWO patterns — the exact
+// prefix (matches the bare command, e.g. `git ls-files`) and a trailing " *" variant (matches the
+// command with arguments, e.g. `git ls-files path/to/dir`). The deny patterns (above) are returned
+// as-is; the caller pushes allow THEN deny so last-match-wins keeps dangerous arguments denied.
+//
+// Pure + deterministic; reused by resolveRunAuthority for the inspect-with-shell profile so the
+// runtime permission ruleset enforces the SAME allowlist that validateAuditedCommand and the docs
+// describe — the lists are never duplicated.
+export function auditedShellPermissionPatterns() {
+  const allow = [];
+  for (const entry of AUDITED_SHELL_ALLOWLIST) {
+    const base = entry.prefix.join(" ");
+    allow.push(base);
+    allow.push(`${base} *`);
+  }
+  return { allow, deny: [...SHELL_PERMISSION_DENY_PATTERNS] };
+}
+
+// The required gates per deep mode. audited-shell reuses inspect-with-shell; network-advisory adds
+// network + the permissionEnforcement gate.
+export const DEEP_MODE_REQUIRED_GATES = Object.freeze({
+  "audited-shell": Object.freeze(["permissionEnforcement", "commandScopedBash"]),
+  "network-advisory": Object.freeze(["permissionEnforcement", "networkAccess"]),
+});
+
+// Map a run's shell-lens state to a shellCoverage grade. "none" unless shell mode is active AND the
+// gates are verified (fail-closed). "partial" when the shell lens is enabled (churn measured for
+// some dirs); "full" when every dir's churn was measured.
+export function resolveShellCoverage({ shellMode, gatesVerified, measured = 0, expected = 0 } = {}) {
+  if (!shellMode || !gatesVerified) return "none";
+  if (expected > 0 && measured >= expected) return "full";
+  return "partial";
+}
+
+// Resolve the effective deep mode from runtime args. Pure + deterministic; the fail-closed rule
+// means an unverified-gate request degrades to static (the guest/command never actually enables
+// shell/network without verified gates). Returns a structured descriptor for the envelope + report.
+export function resolveDeepMode({ deepMode, profile, gatesVerified = false } = {}) {
+  const requested = String(deepMode ?? profile ?? "static");
+  const isShell = requested === "audited-shell" || requested === "inspect-with-shell";
+  const isNetwork = requested === "network-advisory" || requested === "network";
+  if (!isShell && !isNetwork) {
+    return {
+      mode: "static",
+      requested: "static",
+      authorityProfile: "read-only-review",
+      requiredGates: [],
+      shellMode: false,
+      networkMode: false,
+      shellCoverage: "none",
+      coverageLimitations: "Static, read-only analysis. Git churn is not measured (no shell); dependency/network advisories are not fetched (no network). Enable audited-shell or network-advisory (verified gates) for deeper coverage.",
+      failClosed: false,
+    };
+  }
+  const requiredGates = isShell ? DEEP_MODE_REQUIRED_GATES["audited-shell"] : DEEP_MODE_REQUIRED_GATES["network-advisory"];
+  // FAIL CLOSED: a requested deep mode that cannot verify its gates degrades to static. The mode is
+  // NEVER enabled by accident — shell/network require explicit opt-in AND verified gates.
+  if (!gatesVerified) {
+    return {
+      mode: "static",
+      requested,
+      authorityProfile: "read-only-review",
+      requiredGates,
+      shellMode: false,
+      networkMode: false,
+      shellCoverage: "none",
+      coverageLimitations: `${requested} was requested but required gates (${requiredGates.join(", ")}) are unverified; degraded to static read-only review. Verify the gates and re-run to enable the deep mode.`,
+      failClosed: true,
+    };
+  }
+  // Gates verified → the deep mode is active.
+  if (isShell) {
+    return {
+      mode: "audited-shell",
+      requested,
+      authorityProfile: "inspect-with-shell",
+      requiredGates,
+      shellMode: true,
+      networkMode: false,
+      shellCoverage: "partial",
+      coverageLimitations: null,
+      failClosed: false,
+    };
+  }
+  return {
+    mode: "network-advisory",
+    requested,
+    authorityProfile: "network-advisory",
+    requiredGates,
+    shellMode: false,
+    networkMode: true,
+    shellCoverage: "none",
+    coverageLimitations: null,
+    failClosed: false,
+  };
+}