@snarkipus/opencode-beads 1.0.2 → 1.1.0-beta.2

package/assets/oc-beads/resources/WORKFLOWS.md

@@ -0,0 +1,64 @@
+# Workflows and checkpoints
+
+> Adapted from [Beads marketplace-main `WORKFLOWS.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/WORKFLOWS.md). The append policy below resolves conflicting upstream examples: checkpoints append; replacing notes is deliberate.
+
+## Begin with the current context
+
+Use current Beads context if it was supplied. Read the target issue, dependencies,
+existing notes, and relevant memory before choosing an action. Confirm the exact
+assignment and authority. Do not treat `ready` output as an assignment or
+permission to work every listed item.
+
+For an authorized task, claim it atomically with the actual executor actor. Keep
+that actor on all subsequent writes and heartbeats. Direct execution is fine for
+small tasks; use delegation where it improves the work, carrying a bounded scope
+and the real delegate actor. Do not impose a one-item-per-invocation loop or
+delegate by command count.
+
+## Checkpoint at useful transitions
+
+Append when a failed approach changes the next step, a finding is validated, a
+decision changes, work becomes blocked, a child returns, or a session may stop.
+Include the attempt, result, why it matters, evidence, blocker, and next action.
+Use `--append-notes`, for example:
+
+```sh
+bd update '<id>' --append-notes="Validated …; evidence …; next …" --actor='<executor-actor>' --sandbox --json
+```
+
+This is an append. Do not use the replacing `--notes` field as the default
+checkpoint. If nothing material changed, do not write a redundant note just to
+meet a quota. Avoid credentials, raw logs, and claims unsupported by evidence.
+
+## Capture reusable knowledge selectively
+
+Task details and short-lived failures belong with the issue. Search existing
+memory before recording a validated lesson that will likely help elsewhere.
+Include its scope and evidence, use the actual executor actor for memory writes,
+and amend stale knowledge intentionally. Do not save every task outcome as
+global memory.
+
+## Validate and hand off
+
+Check the issue's acceptance conditions, run authorized relevant validation,
+and record exact results. If a parent or human owns acceptance, return the
+evidence without closing for them. A delegate returns attempts, results,
+rationale, validation, blockers, next action, and useful record references; the
+parent reconciles before continuing. If the task was an exact assignment, stop
+there. Explicitly authorized batches may continue within their stated scope;
+new discoveries never expand it.
+
+When context is held or a required guarantee is missing, stop the affected path
+and state the limitation. Do not switch to a manual prime, unregistered tool,
+automatic setup, sync, or permission change to complete it.
+
+## Planning and independently owned review
+
+Follow project-owned planning and review policy. Track substantive multi-session
+or delegated planning in one bounded planning item, separate from implementation;
+a quick draft need not get its own ticket. Give substantive independently owned
+review one bounded review item linked to planning and the exact candidate. Reuse
+the same review item through corrections and rechecks. Record actual reviewer
+actor/session, verdict, findings and evidence without retroactive claims.
+Planning/review closure needs its own evidence and owner acceptance; readiness
+alone never authorizes dispatch, implementation, release or deployment.

package/assets/oc-beads/resources/WORKTREES.md

@@ -0,0 +1,24 @@
+# Worktree routing
+
+> Adapted from [Beads marketplace-main `WORKTREES.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/WORKTREES.md).
+
+A worktree can isolate code changes while retaining a repository's shared Beads
+database. The installed CLI documents common-directory discovery for its
+worktree command. Do not assume that every unrelated checkout, redirected
+workspace, or custom route shares the same store.
+
+Use a worktree only when isolation helps and its creation is authorized. Before
+changing issues, confirm which repository and Beads location the CLI resolved.
+Keep the assignment and explicit executor actor the same across the worktree;
+Git identity is not a Beads actor. Do not initialize a separate store, change
+routes, or copy database state to make a task appear ready.
+
+Use `bd worktree --help` and relevant subcommand help for current commands and
+safety checks. Inspect local changes before removal, preserve work that is not
+yours, and remove only a worktree whose cleanup is authorized. This resource
+does not create or clean up a worktree automatically.
+
+`oc-beads:sync` guides `bd sync` Dolt-remote synchronization, distinct from
+`bd federation sync` and removed JSONL sync. Inspect current help and synchronize
+only with explicit authority. Report conflicts without forcing a side; the
+installed Beads CLI owns synchronization and consistency semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "1.0.2",
+  "version": "1.1.0-beta.2",
   "type": "module",
   "description": "A maintained OpenCode V2 integration for the Beads issue tracker: bd prime context injection with a schema-migration guard, and a bounded task agent.",
   "author": "Matt Jackson",
@@ -43,6 +43,7 @@
   },
   "files": [
     "src",
+    "assets/oc-beads",
     "README.md",
     "LICENSE"
   ],
@@ -55,11 +56,11 @@
     "typecheck": "tsc --noEmit"
   },
   "beads": {
-    "minimum": "1.3.0",
+    "minimum": "1.3.1",
     "validated": "1.3.1"
   },
   "peerDependencies": {
-    "@opencode/plugin": ">=2.0.26 <3"
+    "@opencode/plugin": ">=2.1.1 <2.2"
   },
   "peerDependenciesMeta": {
     "@opencode/plugin": {
@@ -67,7 +68,7 @@
     }
   },
   "devDependencies": {
-    "@opencode/plugin": "2.0.26",
+    "@opencode/plugin": "2.1.1",
     "@types/bun": "1.3.4",
     "@types/node": "^22.0.0",
     "typescript": "5.9.3"

package/src/agents.ts

@@ -8,7 +8,7 @@ export const BEADS_TASK_AGENTS: ReadonlySet<string> = new Set([
   BEADS_TASK_AGENT_LUNA,
 ]);
 
-/** Default hard cap on worker steps; a backstop for "one bead, then return", not a target. */
+/** Default interruption cap on worker steps; never a completion target or authority to continue. */
 export const DEFAULT_TASK_AGENT_STEPS = 100;
 
 /**
@@ -45,7 +45,7 @@ export interface BeadsAgentDefinition {
 export interface BeadsAgentOptions {
   /** Register the Luna Max profile alongside the default task agent. */
   luna?: boolean;
-  /** Hard cap on worker steps; 0 removes the cap. */
+  /** Interruption cap on worker steps; 0 removes the cap, never the assignment's scope limits. */
   steps?: number;
 }
 

package/src/context.ts

@@ -1,7 +1,8 @@
+import { executorActor } from "./continuity";
 import { BEADS_TASK_AGENTS } from "./agents";
 import { guardNotice, type GuardResult } from "./guard";
 import { PrimeTimeoutError } from "./prime";
-import { beadsGuidance, primeFailureNotice } from "./guidance";
+import { beadsGuidance, primeFailureNotice, type RequestCapabilities } from "./guidance";
 
 /** Retry window for withheld or failed context, so model steps do not respawn `bd` each time. */
 export const DEFAULT_CONTEXT_RETRY_MS = 30_000;
@@ -15,11 +16,12 @@ export const DEFAULT_IDLE_REFRESH_MS = 30 * 60_000;
 
 export type AgentMode = "primary" | "subagent" | "all";
 export type ContextAudience = "primary" | "task-agent";
-export type ContextDiagnostic = "agent_lookup_failed" | "prime_failed" | "prime_timeout";
+export type ContextDiagnostic = "agent_lookup_failed" | "guard_failed" | "prime_failed" | "prime_timeout";
+export type ContextStatus = "loading" | "missing" | "withheld" | "failed" | "empty" | "ready";
 
 export interface ContextRuntime {
-  guard(directory: string): Promise<GuardResult>;
-  prime(directory: string): Promise<string>;
+  guard(directory: string, signal?: AbortSignal): Promise<GuardResult>;
+  prime(directory: string, signal?: AbortSignal): Promise<string>;
   /** Resolve an agent's mode; undefined when the agent is unknown. */
   agentMode(agentID: string): Promise<AgentMode | undefined>;
   diagnose?(code: ContextDiagnostic, sessionID: string): void;
@@ -34,26 +36,33 @@ export interface ContextControllerOptions {
 
 export interface ContextController {
   /** System text for one model request, or undefined when nothing should be added. */
-  systemFor(sessionID: string, agentID: string): Promise<string | undefined>;
+  systemFor(sessionID: string, agentID: string, capabilities?: RequestCapabilities): Promise<string | undefined>;
   /** Refresh prime on the next request, e.g. after compaction changed the session. */
   invalidate(sessionID: string): void;
   /** Drop all state for a deleted session. */
   forget(sessionID: string): void;
+  /** Context state is distinct from an absent text part (including intentional empty prime). */
+  statusFor(sessionID: string, audience: ContextAudience): ContextStatus | undefined;
+  /** A write can affect every cached session in this location. */
+  invalidateAll(): void;
+  /** Abort owned loads and prevent late context injection after unload. */
+  dispose(): void;
 }
 
-type CacheEntry = { value: Promise<string | undefined>; expiresAt?: number; lastUsed: number };
+type CacheEntry = { value: Promise<string | undefined>; expiresAt?: number; lastUsed: number; abort: AbortController; status?: ContextStatus };
 
 /** Wrap prime output in the envelope and shared guidance for one audience. */
-export function renderBeadsContext(prime: string, audience: ContextAudience): string {
-  return `<beads-context audience="${audience}">\n${prime}\n</beads-context>\n\n${beadsGuidance(audience)}`;
+export function renderBeadsContext(prime: string, audience: ContextAudience, request?: { sessionID: string; agent: string; capabilities?: RequestCapabilities }): string {
+  const identity = request ? `\nYour Beads executor actor: ${executorActor(request)}. Use this exact actor for every direct shell write, claim and heartbeat (command-scoped --actor or BEADS_ACTOR); children use their own actual request actor. Attribution grants no permission.\n` : "";
+  return `<beads-context audience="${audience}">\n${prime}\n</beads-context>\n${identity}\n${beadsGuidance(audience, request?.capabilities)}`;
 }
 
 /**
  * Supply Beads context through the per-request session context hook.
  *
  * OpenCode V2 attaches system parts to every model request without storing them, so context
- * survives compaction on its own. The rendered text is cached per session to keep it stable
- * across requests; compaction invalidates it so persistent memories can refresh.
+ * survives compaction on its own. Guarded prime is cached separately from per-request actor/capability rendering;
+ * compaction invalidates it so persistent memories can refresh.
  */
 export function createContextController(
   runtime: ContextRuntime,
@@ -65,6 +74,7 @@ export function createContextController(
   const now = options.now ?? Date.now;
   const cache = new Map<string, CacheEntry>();
   const modes = new Map<string, Promise<AgentMode | undefined>>();
+  let disposed = false;
 
   async function audienceFor(
     sessionID: string,
@@ -97,34 +107,53 @@ export function createContextController(
 
     let guard: GuardResult;
     try {
-      guard = await runtime.guard(directory);
+      guard = await runtime.guard(directory, entry.abort.signal);
     } catch {
-      return retryLater(undefined);
+      if (entry.abort.signal.aborted) return undefined;
+      entry.status = "failed";
+      runtime.diagnose?.("guard_failed", sessionID);
+      return retryLater("<beads-notice>Beads workflow context failed during the store safety check. Store authority is unknown; do not bypass this failure with manual prime.</beads-notice>");
+    }
+    if (entry.abort.signal.aborted) return undefined;
+    if (guard.kind !== "ready") {
+      entry.status = guard.kind === "probe-failed" ? "failed" : guard.kind === "migration-pending" || guard.kind === "unsupported" ? "withheld" : "missing";
+      return retryLater(guardNotice(guard));
     }
-    if (guard.kind !== "ready") return retryLater(guardNotice(guard));
 
     let output: string;
     try {
-      output = (await runtime.prime(directory)).trim();
+      output = (await runtime.prime(directory, entry.abort.signal)).trim();
     } catch (error) {
+      if (entry.abort.signal.aborted) return undefined;
+      entry.status = "failed";
       const timedOut = error instanceof PrimeTimeoutError;
       runtime.diagnose?.(timedOut ? "prime_timeout" : "prime_failed", sessionID);
       return retryLater(primeFailureNotice(timedOut ? "timed out" : "failed"));
     }
-    if (!output) return retryLater(undefined);
-    return renderBeadsContext(output, audience);
+    if (entry.abort.signal.aborted) return undefined;
+    if (!output) {
+      entry.status = "empty";
+      return retryLater(undefined);
+    }
+    entry.status = "ready";
+    return output;
   }
 
   function dropSession(sessionID: string): void {
+    modes.clear();
     for (const key of cache.keys()) {
-      if (key.startsWith(`${sessionID}\0`)) cache.delete(key);
+      if (key.startsWith(`${sessionID}\0`)) {
+        cache.get(key)?.abort.abort();
+        cache.delete(key);
+      }
     }
   }
 
   return {
-    async systemFor(sessionID, agentID) {
+    async systemFor(sessionID, agentID, capabilities) {
+      if (disposed) return undefined;
       const audience = await audienceFor(sessionID, agentID);
-      if (!audience) return undefined;
+      if (!audience || disposed) return undefined;
 
       const key = `${sessionID}\0${audience}`;
       const current = now();
@@ -133,16 +162,32 @@ export function createContextController(
       const resumed = cached && idleRefreshMs > 0 && current - cached.lastUsed > idleRefreshMs;
       if (cached && fresh && !resumed) {
         cached.lastUsed = current;
-        return cached.value;
+        const output = await cached.value;
+        if (disposed || cached.abort.signal.aborted) return undefined;
+        return cached.status === "ready" ? renderBeadsContext(output!, audience, { sessionID, agent: agentID, capabilities }) : output;
       }
 
-      const entry: CacheEntry = { value: Promise.resolve(undefined), lastUsed: current };
+      cached?.abort.abort();
+      const entry: CacheEntry = { value: Promise.resolve(undefined), lastUsed: current, abort: new AbortController(), status: "loading" };
       entry.value = load(sessionID, audience, entry);
       cache.set(key, entry);
-      return entry.value;
+      const output = await entry.value;
+      if (disposed || entry.abort.signal.aborted) return undefined;
+      return entry.status === "ready" ? renderBeadsContext(output!, audience, { sessionID, agent: agentID, capabilities }) : output;
     },
 
     invalidate: dropSession,
     forget: dropSession,
+    statusFor: (sessionID, audience) => cache.get(`${sessionID}\0${audience}`)?.status,
+    invalidateAll() {
+      for (const entry of cache.values()) entry.abort.abort();
+      cache.clear();
+    },
+    dispose() {
+      disposed = true;
+      for (const entry of cache.values()) entry.abort.abort();
+      cache.clear();
+      modes.clear();
+    },
   };
 }