opencode-thrum-pro 0.1.0 → 0.1.2

package/assets/skills/project-setup/SKILL.md

@@ -44,7 +44,45 @@ grep -E 'verify=Ready:Yes([[:space:]]|-->|$)' "$PLAN_FILE" \
   || grep -E 'verify=PREDATES([[:space:]]|-->|$)' "$PLAN_FILE"
 ```
 
-All three checks must pass.
+**Fourth check — the stamp must BIND, not just be PRESENT.** A stamp's
+presence proves a review happened; it does not prove the stamp still
+describes the artifact in front of you. Parse the binding keys from the
+**highest-cycle** (last-appended) `stage=plan` line — stamps are only ever
+appended, never reordered, so `tail -1` is the binding verdict; never `sort`
+(a `cycle=10` line must beat `cycle=9`, which a lexical sort inverts) — then
+re-derive the current values per `_stamp-protocol.md` § "Review-object
+binding" and compare:
+
+```bash
+# SOURCE_FILE = the LOCKED brainstorm (+ design spec, if any) this plan was reviewed against
+LINE=$(grep '^<!-- THRUM-REVIEW: stage=plan ' "$PLAN_FILE" | tail -1)
+
+# An OVERRIDE on this line already satisfies the fourth check (same escape as
+# the first check) — short-circuit BEFORE the missing-keys exit below, or a
+# legitimate OVERRIDE stamp that omits plan_obj/src_lock is wrongly rejected.
+if ! grep -qE 'verdict=OVERRIDE([[:space:]]|-->|$)' <<<"$LINE"; then
+  STAMPED_OBJ=$(sed -n 's/.*plan_obj=\([0-9a-f]\{40,64\}\).*/\1/p' <<<"$LINE")
+  STAMPED_LOCK=$(sed -n 's/.*src_lock=\([0-9a-f]\{40,64\}\).*/\1/p' <<<"$LINE")
+
+  # Missing keys fails exactly like a missing verify= — no silent-omission path.
+  [ -n "$STAMPED_OBJ" ] && [ -n "$STAMPED_LOCK" ] || {
+    echo "review stamp missing plan_obj/src_lock binding keys" >&2; exit 1; }
+
+  CURRENT_OBJ=$(grep -v '^<!-- THRUM-REVIEW:' "$PLAN_FILE" | git hash-object --no-filters --stdin)
+  CURRENT_LOCK=$(git hash-object --no-filters "$SOURCE_FILE")
+
+  [ "$STAMPED_OBJ" = "$CURRENT_OBJ" ] \
+    || { echo "review stamp does not bind the current plan object" >&2; exit 1; }
+  [ "$STAMPED_LOCK" = "$CURRENT_LOCK" ] \
+    || { echo "review stamp bound to a superseded source LOCK" >&2; exit 1; }
+fi
+```
+
+An OVERRIDE on the matched `stage=plan` line already satisfies this fourth
+check (same escape as the first check) — the snippet above short-circuits
+before re-deriving or comparing in that case.
+
+All four checks must pass.
 
 Notes on the check:
 
@@ -75,29 +113,42 @@ Notes on the check:
   `OVERRIDE`. This is what makes `verify-against-source` mandatory in fact,
   not just in name: a plan could otherwise carry `verdict=Ready:Yes` from
   some OTHER reviewer while `verify-against-source` itself never ran.
+- **The binding check fails closed on either mismatch, with no
+  silent-omission path** — a stamp missing `plan_obj`/`src_lock` entirely
+  fails exactly like a missing `verify=` field (fourth check above). The
+  remedy is the same shape as the `verify=` remedy: re-run the plan review so
+  the stamp is emitted with live binding keys (`_stamp-protocol.md` § "Review-
+  object binding"), or a coordinator adds an explicit `verdict=OVERRIDE`
+  (with `reason=`) to the `stage=plan` line — the SAME auditable escape used
+  for the first check, not a new mechanism. There is no `PREDATES` value for
+  the binding keys themselves; a legacy plan without them either gets
+  re-reviewed (which produces the keys) or overridden.
 
 If any check fails, **STOP — do not proceed.** Tell the user:
 
 > project-setup requires the plan/spec to have passed the planning-loop review
 > (or carry a coordinator override), to carry a `## Deviations from Source`
-> block, AND to carry `verify=Ready:Yes`, `verify=OVERRIDE`, or
-> `verify=PREDATES` evidence that `verify-against-source` specifically ran (or
-> was deliberately waived, or the plan predates the convention). The plan at
-> `<PLAN_FILE>` is missing one or more of: the review stamp, the Deviations
-> block, the `verify=` field — check which with the three `grep -F` commands
-> above. Run the plan review first (making sure `verify-against-source` runs
-> and stamps `verify=`), obtain a coordinator override, or stamp
-> `verify=PREDATES` if the plan predates this convention, then re-invoke
-> project-setup.
+> block, to carry `verify=Ready:Yes`, `verify=OVERRIDE`, or `verify=PREDATES`
+> evidence that `verify-against-source` specifically ran (or was deliberately
+> waived, or the plan predates the convention), AND for the review stamp to
+> BIND the current plan object and current locked source (`plan_obj`/
+> `src_lock`). The plan at `<PLAN_FILE>` is missing one or more of: the review
+> stamp, the Deviations block, the `verify=` field, or a valid binding — check
+> which with the commands above. Run the plan review first (making sure
+> `verify-against-source` runs, `verify=` is stamped, and `plan_obj`/
+> `src_lock` are computed fresh), obtain a coordinator override, or stamp
+> `verify=PREDATES` if the plan predates the `verify=` convention, then
+> re-invoke project-setup.
 
 **Fail closed, not open.** Plans that predate this feature, or that arrive from
-a different flow, will not carry the stamp, the Deviations block, or the
-`verify=` field — they still bail on all three checks. The caller must add an
-`OVERRIDE` stamp for the review-stamp check and a `verify=PREDATES` (the
+a different flow, will not carry the stamp, the Deviations block, the
+`verify=` field, or the binding keys — they still bail on all four checks. The
+caller must add an `OVERRIDE` stamp for the review-stamp check (which also
+covers the binding check, per the note above) and a `verify=PREDATES` (the
 legacy case — not `verify=OVERRIDE`, which is reserved for an active per-cycle
 waiver) for the verify check, and must author the Deviations block (there is
 no override for its absence), to proceed. Do not silently fall through when
-any of the three is absent.
+any of the four is absent.
 
 ## When to Use
 
@@ -901,11 +952,13 @@ prompt file:
    <!-- THRUM-GATE: stage=prompt next=dispatch -->
    ```
 
-2. **After the post-setup prompt review terminates `Ready:Yes`**, append the
-   verdict stamp:
+2. **After the post-setup prompt review terminates `Ready:Yes`**, compute
+   `prompt_obj`/`plan_lock` per `_stamp-protocol.md` § "Review-object binding"
+   (strip-then-hash the prompt against itself for `prompt_obj`; plain-hash the
+   LOCKED plan for `plan_lock`), then append the verdict stamp:
 
    ```text
-   <!-- THRUM-REVIEW: stage=prompt verdict=Ready:Yes cycle=<N> date=<YYYY-MM-DD> -->
+   <!-- THRUM-REVIEW: stage=prompt verdict=Ready:Yes cycle=<N> date=<YYYY-MM-DD> prompt_obj=<blob> plan_lock=<blob> -->
    ```
 
    This review happens **within the same project-setup session**: after Step 4
@@ -916,10 +969,54 @@ prompt file:
 
 Use the exact canonical, case-sensitive form (`Ready:Yes` / `OVERRIDE`; keep
 keys in the fixed order `stage=`, `verdict=`, `cycle=`, `date=` so a literal
-`grep -F` matches). At dispatch, the coordinator greps the prompt for this
-stamp: present → the pre-dispatch review is already satisfied (skip re-review);
-absent → fall through to the normal pre-dispatch dual review (the stamp is a
-shortcut, not a hard dispatch requirement).
+`grep -F` matches).
+
+**This stamp is a hard completion requirement, not an optional shortcut.**
+project-setup CANNOT report completion or dispatch-readiness for this session
+until the generated prompt carries a `stage=prompt verdict=Ready:Yes` (or
+`OVERRIDE`) THRUM-REVIEW line with valid `prompt_obj`/`plan_lock` bindings.
+Run the same binding check used at Phase 0 (§ "Fourth check" above), against
+the prompt instead of the plan:
+
+```bash
+# PROMPT_FILE = the generated prompt; PLAN_FILE = the LOCKED plan it was reviewed against
+LINE=$(grep '^<!-- THRUM-REVIEW: stage=prompt ' "$PROMPT_FILE" | tail -1)
+[ -n "$LINE" ] || {
+  echo "prompt carries no stage=prompt review stamp — cannot report dispatch-ready" >&2
+  exit 1
+}
+
+# An OVERRIDE on this line already satisfies the check (same escape as
+# Phase 0's fourth check) — short-circuit BEFORE the missing-keys exit below,
+# or a legitimate OVERRIDE stamp that omits prompt_obj/plan_lock is wrongly
+# rejected.
+if ! grep -qE 'verdict=OVERRIDE([[:space:]]|-->|$)' <<<"$LINE"; then
+  STAMPED_OBJ=$(sed -n 's/.*prompt_obj=\([0-9a-f]\{40,64\}\).*/\1/p' <<<"$LINE")
+  STAMPED_LOCK=$(sed -n 's/.*plan_lock=\([0-9a-f]\{40,64\}\).*/\1/p' <<<"$LINE")
+  [ -n "$STAMPED_OBJ" ] && [ -n "$STAMPED_LOCK" ] || {
+    echo "review stamp missing prompt_obj/plan_lock binding keys" >&2; exit 1; }
+
+  CURRENT_OBJ=$(grep -v '^<!-- THRUM-REVIEW:' "$PROMPT_FILE" | git hash-object --no-filters --stdin)
+  CURRENT_LOCK=$(git hash-object --no-filters "$PLAN_FILE")
+
+  [ "$STAMPED_OBJ" = "$CURRENT_OBJ" ] \
+    || { echo "review stamp does not bind the current prompt object" >&2; exit 1; }
+  [ "$STAMPED_LOCK" = "$CURRENT_LOCK" ] \
+    || { echo "review stamp bound to a superseded plan LOCK" >&2; exit 1; }
+fi
+```
+
+An OVERRIDE on the matched line already satisfies this check (same escape as
+Phase 0's fourth check) — the snippet above short-circuits before re-deriving
+or comparing in that case.
+
+At dispatch, the coordinator greps the prompt for this stamp. On a
+project-setup-produced prompt it is ALWAYS present — project-setup will not
+have reported completion without it — so its absence on such a prompt is an
+ANOMALY requiring the full pre-dispatch review, never a sanctioned shortcut
+for skipping it. (Pre-feature prompts and prompts from non-project-setup
+flows are a separate, narrower carve-out — see
+`coordinator-dispatching-work`.)
 
 ## Common Mistakes
 

package/assets/skills/update-queue/SKILL.md

@@ -112,7 +112,9 @@ Give each sub-agent:
   `merge-base`, `status` ONLY — never `checkout`/`reset`/`restore`/`stash`/
   `clean`/`rebase`/`commit`/`push`, in any directory; never enter another
   worktree.
-- pinned `model:` + `effort:` (sonnet, low for mechanical lookups).
+- pinned `model:` (sonnet; intended tier is low for mechanical lookups — the
+  Agent tool takes no `effort`, so carry the tier via the agent definition or
+  the tmux launch flags).
 
 ## Step 5 — Add missing committed work
 

package/assets/thrum_allowlist.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "_supersedes": "the earlier watcher-settings allowlist spec (single-watcher restart-flow scope)",
+  "_comment": [
+    "This is the canonical, code-consumed source for the Thrum ordinary-operation allowlist (allowlist).",
+    "TWO-CAVEAT SPLIT (owner ruling) — read both before editing this file:",
+    "  1. SUPERSEDED: the original spec's 'scoped to one watcher's restart flow, not a general starting point' framing is superseded. This IS the general, code-consumed source every runtime generator draws from.",
+    "  2. STILL BINDING, NOT SUPERSEDED — BUT THE MODEL CHANGED (owner ruling via the fleet coordinator, allowlist consolidated round): command_patterns is no longer an enumerated per-subcommand list. The owner ruled ALL thrum commands are globally allowlisted — 'thrum' itself is the ONE entry, representing the whole command FAMILY (any subcommand). This is still bounded, never a blanket Bash(*): the ONLY thing that admits a candidate is an exact executable-token match (bare 'thrum', or the Part-C canonical-install-path forms) at an executable boundary, and the fail-closed metachar/alt-exec guard (containsForbiddenFragment + the alt-exec check in matchesCommandPattern) is now the PRIMARY scoping boundary, not a secondary one — it alone is what stops sh -c/bash -c, command substitution ($(...)/backticks), compound commands (&&, ;, |, ||), and alternate executable paths (./thrum, /tmp/thrum, arbitrary absolute paths, suffix/prefix lookalikes like thrum-evil). Every generator consuming this file must render the FAMILY grant in its native syntax (Claude/OpenCode: any-subcommand pattern, no shell composition; Codex: native profile only, §5.1, no invented Bash allowlist — command_patterns is not a Codex concept) and prove the negative controls above still hold — see each generator's test file.",
+    "READ-PATH INVARIANT: read_paths below (including the recursive '.thrum/**'-shaped grant every generator renders from '.thrum') MUST NEVER be allowed to carry secrets. .thrum is granted broad READ access across every supported runtime by this file — if any future change adds credentials, tokens, or private keys under .thrum, this allowlist makes them world-readable to every runtime this file feeds. Keep secrets out of .thrum, not out of this file.",
+    "GLOBAL READ PATHS (allowlist round-4, owner P0): global_read_paths grants ABSOLUTE, home-relative directories outside the project root — distinct from read_paths above, which are project-relative. Per-runtime because the underlying installed-plugin-cache layout differs by runtime (no shared portable form exists): claude = ~/.claude/plugins/cache/thrum (the thrum marketplace/plugin's OWN cache subtree, version-hash-stripped — NEVER pin a specific installed <version> segment, and never grant the broader ~/.claude/plugins/cache root, which also holds OTHER installed marketplaces' plugin payload); codex = ~/.codex/skills (Codex's flattened global skill install dir — granted in full because Codex's permission syntax has no glob/prefix-match primitive to scope it to thrum-named skills only; it also exposes non-thrum skill dirs as an accepted, documented trade-off) + ~/.codex/plugins/cache/thrum-marketplace/thrum (the versioned plugin-cache mirror, same version-hash-stripping rule as Claude's). OpenCode needs NO entry here — its own installer (opencode-plugin/src/installer.ts, opencodeGlobalReadPaths) already derives its global skill/command paths dynamically from its own resolved configDir at generation time, so a static path here would be redundant and could drift from the real value.",
+    "OWNER-AUTHORIZED EXCEPTION — /private/tmp (owner ruling, watcher-recovery P0; scope CONFIRMED all-runtimes by the fleet coordinator the same day — owner's wording was 'global configs for all agents', the operational-artifact class is runtime-independent): owner_authorized_exceptions grants EVERY supported runtime broad READ access to /private/tmp/* DESPITE it being a world-writable directory — explicitly ruled acceptable by the owner for coordinator/watcher operational artifacts. This is a DELIBERATE exception, not a template for widening elsewhere: it grants READ/ACCESS ONLY — never execute, never shell-interpolation, never a sibling root like /private or /private/tmpfoo, never write/delete. Codex renders this via its NATIVE filesystem-read profile mechanism, never as an invented Bash-pattern entry (still-binding caveat above). Every generator consuming this list must prove those boundaries by negative-control test AND by-effect (a real read actually succeeds; a real write/exec attempt actually fails), not merely by the shape of the grant string.",
+    "~/.local/bin OWNER CORRECTION (owner ruling, consolidated round): global_read_paths.<runtime> gains '~/.local/bin' for ALL THREE runtimes — the install location of the thrum binary itself, so PATH-resolved 'thrum' can actually execute under each runtime's sandbox. Granted in full (not scoped to just the thrum binary file) for the same reason as Codex's flattened ~/.codex/skills grant above: none of the three permission syntaxes has a single-file-only primitive that stays portable, so the directory is the smallest expressible unit. This is a FILESYSTEM READ/ACCESS/EXEC grant on the install directory — it is a SEPARATE axis from command_patterns matching, and does NOT loosen the alt-exec guard in approved.go beyond the tight, explicitly-scoped canonical-install-path carve-out documented in that file (canonicalInstallPathPrefixes) — a lookalike executable in the same directory (~/.local/bin/thrum-evil) is still rejected by that carve-out's own boundary check even though the DIRECTORY grant here would let a runtime read/access it."
+  ],
+  "command_patterns": [
+    "thrum"
+  ],
+  "read_paths": [
+    ".claude/skills",
+    ".claude/commands",
+    ".codex/skills",
+    ".opencode/skills",
+    ".thrum"
+  ],
+  "global_read_paths": {
+    "claude": ["~/.claude/plugins/cache/thrum", "~/.local/bin"],
+    "codex": ["~/.codex/skills", "~/.codex/plugins/cache/thrum-marketplace/thrum", "~/.local/bin"],
+    "opencode": ["~/.local/bin"]
+  },
+  "owner_authorized_exceptions": {
+    "claude": ["/private/tmp"],
+    "codex": ["/private/tmp"],
+    "opencode": ["/private/tmp"]
+  }
+}

package/dist/allowlist-sync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/allowlist-sync.test.js

@@ -0,0 +1,44 @@
+// Drift guard (allowlist round 2, finding 9): the canonical allowlist
+// (internal/permissions/thrum_allowlist.json, Go-owned) is copied verbatim
+// into this plugin's bundled asset (opencode-plugin/assets/thrum_allowlist.
+// json) by scripts/sync-skills.sh's sync_opencode step, since TypeScript
+// cannot import a Go package. This test fails LOUDLY the moment the two
+// diverge — a hand-edit of either copy, or a Go-side change that never got
+// synced.
+//
+// Deliberately compares RAW BYTES, not parsed-then-reserialized JSON: a
+// round-trip through JSON.parse/JSON.stringify would normalize whitespace,
+// key order, and formatting, and could mask a real drift (e.g. a
+// re-ordered or re-indented — but content-different — copy would compare
+// "equal" after reserialization while still being a byte-for-byte
+// divergence from the Go source of truth).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "fs";
+import path from "path";
+// This test file compiles to dist/allowlist-sync.test.js (flat src ->
+// flat dist, see tsconfig rootDir/outDir), so at runtime
+// path.dirname(import.meta.url) is opencode-plugin/dist. One level up is
+// opencode-plugin/ (matches the existing ALLOWLIST_ASSET_PATH convention in
+// installer.permissions.test.ts); two levels up is the repo root, from
+// which internal/permissions/ is reachable.
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const PLUGIN_ROOT = path.resolve(HERE, "..");
+const REPO_ROOT = path.resolve(PLUGIN_ROOT, "..");
+const OPENCODE_COPY = path.join(PLUGIN_ROOT, "assets", "thrum_allowlist.json");
+const CANONICAL_SOURCE = path.join(REPO_ROOT, "internal", "permissions", "thrum_allowlist.json");
+test("opencode-plugin/assets/thrum_allowlist.json is byte-identical to internal/permissions/thrum_allowlist.json", (t) => {
+    // The canonical source only exists in the monorepo (github.com/leonletto/thrum);
+    // the public standalone opencode-thrum-pro repo this test also ships in does not
+    // carry internal/permissions/, so skip gracefully there instead of failing —
+    // mirrors the binary-absent skip idiom in permission-fixture.integration.test.ts.
+    if (!fs.existsSync(CANONICAL_SOURCE)) {
+        t.skip(`canonical source not found at ${CANONICAL_SOURCE} — expected outside the monorepo (e.g. public opencode-thrum-pro), skipping drift check`);
+        return;
+    }
+    assert.ok(fs.existsSync(OPENCODE_COPY), `synced copy not found at ${OPENCODE_COPY}`);
+    const canonical = fs.readFileSync(CANONICAL_SOURCE);
+    const copy = fs.readFileSync(OPENCODE_COPY);
+    assert.ok(canonical.equals(copy), "opencode-plugin/assets/thrum_allowlist.json has drifted from internal/permissions/thrum_allowlist.json — " +
+        "re-run scripts/sync-skills.sh (sync_opencode step) to resync, never hand-edit either copy independently");
+});

package/dist/index.js

@@ -1,4 +1,4 @@
-import { installAssets } from "./installer.js";
+import { installAssets, installPermissions } from "./installer.js";
 import { shellEnvHook } from "./hooks/shell-env.js";
 import { blockSyncCdHook } from "./hooks/block-sync-cd.js";
 const TOOL_MAPPING = `
@@ -13,6 +13,29 @@ When Thrum skills reference Claude Code tool names, use these OpenCode equivalen
 `.trim();
 const server = async (ctx) => {
     await installAssets(ctx);
+    // Runs unconditionally (not version-gated like installAssets above): it's
+    // cheap and idempotent, and gating it on the skills-version marker would
+    // skip re-merging the allowlist for users who already had the plugin
+    // installed before this permission block existed (allowlist).
+    //
+    // installPermissions() throws when the user's existing global
+    // opencode.json is present but malformed (unreadable or invalid JSON) —
+    // deliberately, so we never silently overwrite it (allowlist landing-
+    // blocker). Catch and log here rather than letting it become an unhandled
+    // rejection that would abort plugin bootstrap entirely; every other hook
+    // this plugin provides should still register.
+    try {
+        await installPermissions();
+    }
+    catch (err) {
+        await ctx.client.app.log({
+            body: {
+                service: "opencode-thrum",
+                level: "error",
+                message: `failed to install thrum permission allowlist (leaving your opencode.json untouched): ${err.message}`,
+            },
+        });
+    }
     return {
         "shell.env": shellEnvHook(ctx),
         "tool.execute.before": blockSyncCdHook(),

package/dist/installer.d.ts

@@ -1,2 +1,31 @@
 import type { PluginInput } from "@opencode-ai/plugin";
+export declare function getConfigDir(): string;
 export declare function installAssets(ctx: PluginInput): Promise<void>;
+interface AllowlistSource {
+    version: number;
+    command_patterns: string[];
+    read_paths: string[];
+    owner_authorized_exceptions?: Record<string, string[]>;
+    global_read_paths?: Record<string, string[]>;
+}
+type PermissionAction = "ask" | "allow" | "deny";
+type PermissionRuleMap = Record<string, PermissionAction>;
+interface OpenCodeConfig {
+    permission?: {
+        bash?: PermissionRuleMap | PermissionAction;
+        read?: PermissionRuleMap | PermissionAction;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare function bashExactPatternFor(commandPattern: string): string;
+export declare function bashPatternFor(commandPattern: string): string;
+export declare function readPatternFor(readPath: string): string;
+export declare function resolveHomePath(p: string, homeDir?: string): string;
+export declare function readFilePatternFor(filePath: string): string;
+export declare function loadAllowlist(assetPath?: string): AllowlistSource;
+export declare function mergePermissions(config: OpenCodeConfig, allowlist: AllowlistSource, extraReadPatterns?: string[], homeDir?: string): OpenCodeConfig;
+export declare function writeConfig(configPath: string, config: OpenCodeConfig): void;
+export declare function opencodeGlobalReadPaths(configDir: string): string[];
+export declare function installPermissions(configDir?: string, homeDir?: string): Promise<void>;
+export {};