opencode-swarm 7.126.2 → 7.126.3

package/.opencode/skills/engineering-conventions/SKILL.md

@@ -35,7 +35,7 @@ If you are not sure whether you are touching one of these, you are touching one
 The full list of 12 invariants is in `AGENTS.md`. The four that have caused the most recent production regressions:
 
 1. **Plugin initialization is bounded and fail-open.** Every awaited operation on the plugin-init path must be wrapped in `withTimeout(...)` and degrade non-fatally on timeout. Issue #704 (v7.0.3) and the v7.3.3 git-hygiene regression both stem from violating this. The OpenCode plugin host silently drops a plugin whose entry never resolves; users see "no agents in TUI / GUI" with no error.
-   - **Bounded is not free:** `withTimeout` only prevents an *unbounded* hang — the awaited work's latency still counts toward the ~400 ms repro-704 init deadline. Defer non-trivial init I/O via `queueMicrotask` when nothing downstream needs it before `server()` resolves.
+   - **Bounded is not free:** `withTimeout` only prevents an *unbounded* hang — the awaited work's latency still counts toward the ~400 ms repro-704 init deadline. Register non-trivial init I/O in the wrapper-owned post-resolution task queue when nothing downstream needs it before `server()` resolves. Do not use `queueMicrotask` inside the initializer: it can run during a later `await` while `server()` is still unresolved.
 2. **Subprocesses are bounded, non-interactive, and killable.** Every `bunSpawn(['<bin>', ...])` call must pass `cwd`, `stdin: 'ignore'` (unless intentionally interactive), `timeout: <ms>`, bounded stdio, and call `proc.kill()` in a `finally`. An outer `withTimeout` is not enough — it lets the awaiter proceed but does not abort the child.
 3. **Runtime portability — Node-ESM-loadable + v1 plugin shape.** No top-level `bun:` imports in `dist/index.js`. Default export is `{ id, server }`. All `Bun.*` calls go through `src/utils/bun-compat.ts`. v6.86.8 / v6.86.9 are the cautionary tales.
 4. **Test mock isolation.** `mock.module(...)` leaks across files in Bun's shared test-runner process. Prefer, in order: (a) `_test_exports` for pure function testing with zero mocks, (b) `_internals` dependency-injection seam for within-module mocking (see `src/utils/gitignore-warning.ts:_internals` and `src/hooks/diff-scope.ts:_internals`), (c) `mock.module` only when unavoidable. Restore in `afterEach`. The writing-tests skill covers all three tiers in detail; load it before modifying tests.

package/.opencode/skills/swarm-pr-feedback/SKILL.md

@@ -144,7 +144,7 @@ tree:
   tracked path. It creates an auditable, path-scoped stash and returns its
   recovery command. Do not issue `git stash` through shell. The controller never
   stashes untracked files; move or remove those manually, or abort the checkout.
-- **Check out the head branch locally.** Feedback verification reads the working-tree
+- **Check out the head branch locally before dispatching feedback lanes.** Feedback verification reads the working-tree
   filesystem (`Read`/`Glob`/`Grep`), and fixes must land on the PR branch — without a
   checkout you would verify and patch the base branch's code instead. Record the
   exact `merge_base...head_ref` range for diff-scoped inspection.
@@ -159,6 +159,15 @@ tree:
   the upstream of an existing local branch with
   `git branch --set-upstream-to=<remote>/<remote-branch> <local-branch>`).
   Branch creation/tracking is blocked after the immutable head is bound.
+- `gh pr checkout` is permitted only in its non-force, non-submodule form with
+  the PR number/URL and optional `--repo` or `--branch` flags. Never use
+  `--force`, `--recurse-submodules`, or detached checkout during this
+  transition.
+- Before the first feedback verification dispatch binds the head, prove that
+  `git rev-parse HEAD` equals the authoritative full `pr_head_sha`,
+  `git status --porcelain` is empty, and the current branch tracks the intended
+  PR head remote/branch. A detached checkout is valid for review, not feedback
+  publication.
 
 When a verification lane result includes `output_ref`, treat `output` as a
 preview and call `retrieve_lane_output` before using it to classify, resolve,
@@ -733,8 +742,10 @@ the independently approved digest, the exact approved commit remains current,
 its bound upstream remote-tracking ref points to that exact commit, every
 feedback ID has exact-provenance evidence, and no PR-workflow lanes remain
 open. While the gate remains active, the runtime replaces architect
-final-response text with a mechanical blocked notice and re-wakes an idle
-parent session.
+final-response text with a mechanical blocked notice and normally re-wakes an
+idle parent session. A user interruption pauses automatic wakes until a later
+explicit user turn settles; the durable gate remains available to continue or
+abort.
 
 Report:
 

package/.opencode/skills/swarm-pr-review/SKILL.md

@@ -134,9 +134,26 @@ If scope cannot be determined, review the narrowest safe scope available and sta
 
 ### Pre-flight git ref availability
 
-Before launching explorers (Phase 3), confirm the PR branch refs are available:
-- If `head_ref` is a remote branch that is not checked out locally, fetch it via `git fetch origin <head_ref>`
-- **Check out the head branch locally.** Explorer agents read files from the working tree, not from git history — passing the commit range in the delegation prompt is not sufficient because `Read` / `Glob` / `Grep` tools operate on the filesystem. Without a checkout, explorers silently read the base branch's version of changed files and produce invalid candidates. **Before checking out, verify the working tree is clean (`git status --porcelain`). If tracked changes exist, call `prepare_pr_workflow_checkout` with every explicit dirty tracked path. It creates an auditable, path-scoped stash and returns its recovery command. Do not issue `git stash` through shell. The controller never stashes untracked files; move or remove those manually, or abort the checkout.**
+Before launching explorers (Phase 3), perform this exact standalone sequence:
+
+1. Resolve and retain the authoritative full `pr_head_sha` from PR metadata.
+2. Verify the working tree is clean with `git status --porcelain`. If tracked
+   changes exist, call `prepare_pr_workflow_checkout` with every explicit dirty
+   tracked path. Do not issue `git stash` through shell. The controller never
+   stashes untracked files; move or remove those manually, or abort.
+3. Fetch the PR head as one standalone command, for example
+   `git fetch origin refs/pull/<N>/head`. Do not compose fetch and checkout.
+4. Prove the full commit exists locally with
+   `git cat-file -e <full_pr_head_sha>^{commit}`.
+5. Check out the exact PR filesystem with
+   `git switch --detach <full_pr_head_sha>`. Do not use `--track FETCH_HEAD`:
+   `FETCH_HEAD` is not a remote-tracking branch.
+6. Confirm `git rev-parse HEAD` equals the full `pr_head_sha`, bind that exact
+   head through the first PR-review controller call, and finish this before dispatching explorer lanes.
+
+Explorer agents read files from the working tree, not from git history. Passing
+the commit range in a prompt cannot substitute for this checkout because
+`Read` / `Glob` / `Grep` operate on the filesystem.
 - Explicitly pass the verified merge-base range (`base_sha...pr_head_sha`) in every explorer delegation so explorers inspect exactly the controller-bound PR diff. Include `base_ref` only as the live ref used to recompute `base_sha`; do not substitute a two-dot branch-tip range.
 
 If refs cannot be fetched or checked out, state the limitation in the context pack.
@@ -1405,7 +1422,9 @@ the same exact
 `pr_head_sha`. The tool refuses to clear the session gate while required base,
 trigger, declared reviewer/critic, or open-lane obligations remain incomplete.
 While the gate remains active, the runtime replaces architect final-response
-text with a mechanical blocked notice and re-wakes an idle parent session. Only
+text with a mechanical blocked notice and re-wakes an idle parent session. A
+user interruption pauses every automatic wake path until a later explicit user
+turn settles; the durable gate remains available to continue or abort. Only
 emit the final report after the completion tool confirms that the gate cleared.
 
 ## Aborting an unrecoverable review
@@ -1419,9 +1438,11 @@ the merge-base bind can never verify. In that state the response gate
 suspends further auto-resumes after a small number of consecutive
 unproductive wakes, and the only exits are:
 
-1. **Diagnose and retry as two separate standalone commands.** First run
-   `git fetch origin refs/pull/<N>/head:pr-<N>-head` (single command), then
-   `git checkout pr-<N>-head` (single command). Then recompute the exact
+1. **Diagnose and retry the canonical standalone sequence.** Run
+   `git fetch origin refs/pull/<N>/head`, verify
+   `git cat-file -e <full_pr_head_sha>^{commit}`, then run
+   `git switch --detach <full_pr_head_sha>`. Do not use `--track FETCH_HEAD`.
+   Confirm `git rev-parse HEAD` equals the authoritative PR head, then recompute the exact
    merge base with `git merge-base -- <base_ref> <pr_head_sha>` (single
    command) and retry the `swarm-pr-review:base` dispatch with the exact
    `pr_head_sha`, `base_sha`, and `base_ref`.

package/dist/background/pr-event-delivery.d.ts

@@ -89,7 +89,7 @@ export declare function buildWakeMessage(events: FormattedPrEvent[]): string;
  * clients that lack it. Bounded by withTimeout; returns false on any
  * failure or timeout. Never throws.
  */
-declare function sendWakePrompt(sessionID: string, events: FormattedPrEvent[]): Promise<boolean>;
+declare function sendWakePrompt(sessionID: string, events: FormattedPrEvent[], messageID: string): Promise<boolean>;
 export declare const _internals: {
     sendWakePrompt: typeof sendWakePrompt;
     withTimeout: typeof withTimeout;

package/dist/cli/{curator-qfh9xty4.js → curator-jm9ehfkg.js}

@@ -14,7 +14,7 @@ import {
   runCuratorInit,
   runCuratorPhase,
   writeCuratorSummary
-} from "./index-d88y17ht.js";
+} from "./index-5n868tw8.js";
 import"./index-gxw20m1d.js";
 import"./index-3xd9a2g7.js";
 import"./index-kk1scggc.js";

package/dist/cli/{curator-llm-factory-0rf29gfq.js → curator-llm-factory-3cy0h9yw.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   createCuratorLLMDelegate
-} from "./index-d88y17ht.js";
+} from "./index-5n868tw8.js";
 import"./index-gxw20m1d.js";
 import"./index-3xd9a2g7.js";
 import"./index-kk1scggc.js";

package/dist/cli/{guardrail-explain-jsrjqps1.js → guardrail-explain-va0kj05m.js}

@@ -1,8 +1,8 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-z8ftpav0.js";
-import"./index-d88y17ht.js";
+} from "./index-6t5sa6v0.js";
+import"./index-5n868tw8.js";
 import"./index-gxw20m1d.js";
 import"./index-3xd9a2g7.js";
 import"./index-kk1scggc.js";

package/dist/cli/{hive-promoter-ktt17fyf.js → hive-promoter-h9c4kyv0.js}

@@ -7,7 +7,7 @@ import {
   isHiveEligible,
   promoteFromSwarm,
   promoteToHive
-} from "./index-d88y17ht.js";
+} from "./index-5n868tw8.js";
 import"./index-gxw20m1d.js";
 import"./index-3xd9a2g7.js";
 import"./index-kk1scggc.js";

package/dist/cli/{index-d88y17ht.js → index-5n868tw8.js}

@@ -940,8 +940,11 @@ async function bindPrWorkflowHead(directory, sessionID, prHeadSha) {
   const state = await requireAnyActiveState(directory, sessionID);
   const normalizedHead = normalizePrHeadSha(prHeadSha);
   assertCurrentCheckoutHead(directory, normalizedHead);
-  if (state.mode === "PR_REVIEW")
-    assertPrReviewCleanCheckout(directory);
+  if (!state.prHeadSha)
+    assertPrReviewCleanCheckout(directory, state.mode);
+  if (!state.prHeadSha && state.mode === "PR_FEEDBACK") {
+    assertPrFeedbackTrackingCheckout(directory, normalizedHead);
+  }
   if (state.prHeadSha && state.prHeadSha !== normalizedHead) {
     throw new Error(`BLOCKED: active ${state.mode} workflow is bound to PR head "${state.prHeadSha}"; received "${normalizedHead}"`);
   }
@@ -966,9 +969,19 @@ function assertCurrentCheckoutHead(directory, expectedHead) {
   }
   return normalizedExpected;
 }
-function assertPrReviewCleanCheckout(directory) {
+function assertPrReviewCleanCheckout(directory, mode = "PR_REVIEW") {
   if (_test_exports.resolveIsWorkingTreeClean(directory) !== true) {
-    throw new Error("BLOCKED: PR_REVIEW requires a clean index and working tree at the exact PR head");
+    throw new Error(`BLOCKED: ${mode} requires a clean index and working tree at the exact PR head`);
+  }
+}
+function assertPrFeedbackTrackingCheckout(directory, prHeadSha) {
+  const upstream = _test_exports.resolveCurrentUpstreamPushTarget(directory);
+  if (!upstream) {
+    throw new Error("BLOCKED: PR_FEEDBACK requires a current local branch bound to an exact remote name, remote branch ref, and remote-tracking ref before the first head bind; detached or non-tracking checkouts are not allowed");
+  }
+  const matchingRemoteRefs = _test_exports.resolveRemoteRefsContainingHead(directory, prHeadSha);
+  if (!matchingRemoteRefs?.includes(upstream.remoteTrackingRef)) {
+    throw new Error(`BLOCKED: PR_FEEDBACK upstream "${upstream.remoteTrackingRef}" must point to the exact intake PR head "${prHeadSha}" before the first head bind`);
   }
 }
 var _test_exports = {
@@ -12267,11 +12280,11 @@ var _internals15 = {
     }
   },
   applyCuratorKnowledgeUpdates: async (directory, recommendations, knowledgeConfig, generation) => {
-    const { applyCuratorKnowledgeUpdates: applyCuratorKnowledgeUpdates2 } = await import("./curator-qfh9xty4.js");
+    const { applyCuratorKnowledgeUpdates: applyCuratorKnowledgeUpdates2 } = await import("./curator-jm9ehfkg.js");
     return applyCuratorKnowledgeUpdates2(directory, recommendations, knowledgeConfig, generation);
   },
   checkHivePromotions: async (entries, knowledgeConfig, directory) => {
-    const { checkHivePromotions } = await import("./hive-promoter-ktt17fyf.js");
+    const { checkHivePromotions } = await import("./hive-promoter-h9c4kyv0.js");
     return checkHivePromotions(entries, knowledgeConfig, directory);
   },
   applyProposalTriage: async (directory, triage) => {
@@ -20138,8 +20151,8 @@ var _internals28 = {
   loadCuratorDeps: async () => {
     const [{ CuratorConfigSchema }, curator, { createCuratorLLMDelegate: createCuratorLLMDelegate2 }] = await Promise.all([
       import("./schema-fa033pqw.js"),
-      import("./curator-qfh9xty4.js"),
-      import("./curator-llm-factory-0rf29gfq.js")
+      import("./curator-jm9ehfkg.js"),
+      import("./curator-llm-factory-3cy0h9yw.js")
     ]);
     return { CuratorConfigSchema, curator, createCuratorLLMDelegate: createCuratorLLMDelegate2 };
   }
@@ -20638,7 +20651,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "opencode-swarm",
-  version: "7.126.2",
+  version: "7.126.3",
   description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
   main: "dist/index.js",
   types: "dist/index.d.ts",
@@ -41188,7 +41201,7 @@ function buildDetailedHelp(commandName, entry) {
 async function handleHelpCommand(ctx) {
   const targetCommand = ctx.args.join(" ");
   if (!targetCommand) {
-    const { buildHelpText } = await import("./index-5nq8dp63.js");
+    const { buildHelpText } = await import("./index-b16153py.js");
     return buildHelpText();
   }
   const tokens = targetCommand.split(/\s+/);
@@ -41197,7 +41210,7 @@ async function handleHelpCommand(ctx) {
     return _internals62.buildDetailedHelp(resolved.key, resolved.entry);
   }
   const similar = _internals62.findSimilarCommands(targetCommand);
-  const { buildHelpText: fullHelp } = await import("./index-5nq8dp63.js");
+  const { buildHelpText: fullHelp } = await import("./index-b16153py.js");
   if (similar.length > 0) {
     return `Command '/swarm ${targetCommand}' not found.
 
@@ -41336,7 +41349,7 @@ var COMMAND_REGISTRY = {
   },
   "guardrail explain": {
     handler: async (ctx) => {
-      const { handleGuardrailExplain } = await import("./guardrail-explain-jsrjqps1.js");
+      const { handleGuardrailExplain } = await import("./guardrail-explain-va0kj05m.js");
       return handleGuardrailExplain(ctx.directory, ctx.args);
     },
     description: "Dry-run: show what the guardrails would do to a command or write target (executes nothing)",
@@ -41346,7 +41359,7 @@ var COMMAND_REGISTRY = {
   },
   "guardrail-explain": {
     handler: async (ctx) => {
-      const { handleGuardrailExplain } = await import("./guardrail-explain-jsrjqps1.js");
+      const { handleGuardrailExplain } = await import("./guardrail-explain-va0kj05m.js");
       return handleGuardrailExplain(ctx.directory, ctx.args);
     },
     description: "Dry-run: show what the guardrails would do to a command or write target (executes nothing)",
@@ -43140,7 +43153,7 @@ HARD CONSTRAINTS (apply regardless of skill load success):
 - Test execution, explorer lanes, reviewer dispatch, and critic challenge are all permitted within this mode
 - Quality is the only metric \u2014 there is no speed, efficiency, or time exception; time, tokens, and agent dispatches are irrelevant to correctness
 - FOLLOW THE SKILL EXACTLY: execute every phase of the loaded SKILL.md in order with no shortcuts, no phase-skipping, and no premature synthesis. If a required coverage phase cannot complete, apply the skill's coverage gate (retry or verified equivalent alternative). If the gap still cannot be closed, stop and surface the lane failure to the user as BLOCKED; do not produce a degraded review, partial verdict, or final synthesis.
-- CHECK OUT THE PR BRANCH LOCALLY before launching explorer lanes: fetch the PR head ref if it is not present, verify the working tree is clean (git status --porcelain), and if tracked changes exist call \`prepare_pr_workflow_checkout\` with every explicit dirty tracked path before checkout. It returns an auditable stash OID and recovery command; it never stashes untracked files, which must be moved or removed manually. Do NOT run \`git stash\` through shell. Then check out the head branch. Explorers read the working-tree filesystem (Read/Glob/Grep), so without a checkout they read the base branch and produce invalid candidates. Always pass the base..head commit range in explorer delegations.
+- CHECK OUT THE EXACT PR HEAD LOCALLY before dispatching explorer lanes: resolve the authoritative full PR head SHA, verify the working tree is clean (git status --porcelain), and if tracked changes exist call \`prepare_pr_workflow_checkout\` with every explicit dirty tracked path before checkout. It returns an auditable stash OID and recovery command; it never stashes untracked files, which must be moved or removed manually. Do NOT run \`git stash\` through shell. Then use standalone commands: fetch the PR head, verify \`git cat-file -e <full_pr_head_sha>^{commit}\`, run \`git switch --detach <full_pr_head_sha>\`, confirm HEAD equals that SHA, and bind it through the PR-review controller. Do not use \`--track FETCH_HEAD\`. Explorers read the working-tree filesystem (Read/Glob/Grep), so without this checkout they read the base branch and produce invalid candidates. Always pass the base..head commit range in explorer delegations.
 - RUN ALL BASE LANES: the default PR_REVIEW path always launches exactly six repository-agnostic base check-type lanes from the skill. Use \`mode: "swarm-pr-review:base"\` and the exact six \`workflow_lane\` identifiers. The runtime rejects partial, duplicate, or mislabelled waves. Do not collapse, omit, or scale down the base lanes for a small, docs-only, or CI-only PR.
 - RETRY STRUCTURALLY: retry only failed base obligations in later \`swarm-pr-review:base\` async batches with the same exact \`pr_head_sha\`. Blocking \`dispatch_lanes\` and direct Task explorer/reviewer/critic dispatch are not provenance-equivalent and are rejected.
 - USE ASYNC DISPATCH WITHOUT IDLING: launch the base lanes with one \`dispatch_lanes_async\` call when available, record the \`batch_id\`, then keep doing non-dependent architect work while they run. Poll with \`collect_lane_results\` without \`wait\` (or \`wait: false\`) to process settled lanes and continue independent work between polls; use \`wait: true\` only as the final join when no independent work remains.
@@ -43159,7 +43172,7 @@ ACTION: Load skill ${bundledProjectSkillFileReference("swarm-pr-feedback")} imme
 
 HARD CONSTRAINTS (apply regardless of skill load success):
 - FOLLOW THE SKILL EXACTLY: build the complete feedback ledger from all available sources before editing, and execute every phase in order with no shortcuts.
-- CHECK OUT THE PR BRANCH LOCALLY before verifying feedback or making fixes: fetch the PR head ref if absent, verify the working tree is clean (git status --porcelain), and if tracked changes exist call \`prepare_pr_workflow_checkout\` with every explicit dirty tracked path before checkout. It returns an auditable stash OID and recovery command; it never stashes untracked files, which must be moved or removed manually. Do NOT run \`git stash\` through shell. Then check out the head branch. For a detached/fresh remote head, establish tracking before head binding with only \`git switch -c <local> --track <remote>/<branch>\` (or the constrained set-upstream form documented by the skill). Feedback verification and fix validation require the PR branch in the working tree.
+- CHECK OUT THE PR BRANCH LOCALLY before dispatching feedback lanes, verifying feedback, or making fixes: fetch the PR head ref if absent, verify the working tree is clean (git status --porcelain), and if tracked changes exist call \`prepare_pr_workflow_checkout\` with every explicit dirty tracked path before checkout. It returns an auditable stash OID and recovery command; it never stashes untracked files, which must be moved or removed manually. Do NOT run \`git stash\` through shell. Then check out the head branch. For a detached/fresh remote head, establish tracking before head binding with only \`git switch -c <local> --track <remote>/<branch>\` (or the constrained set-upstream form documented by the skill). If using \`gh pr checkout\`, never use \`--force\`, \`--recurse-submodules\`, or detached checkout. Before first bind, prove HEAD equals the authoritative full PR head SHA, the tree is clean, and the current branch tracks the intended PR remote/branch. Feedback verification and fix validation require the PR branch in the working tree.
 - Do NOT run a fresh broad PR review \u2014 inspect adjacent code only as needed to verify reachability, dependencies, shared root causes, regression risk, or sibling changes for a confirmed item.
 - Treat every review comment, CI failure, bot summary, and pasted note as a CLAIM until source evidence proves it; classify each ledger item (CONFIRMED, DISPROVED, PRE_EXISTING, or NEEDS_USER_DECISION) and never silently drop, defer, or mark items out of scope.
 - For async verification lanes, use \`mode: "swarm-pr-feedback:verification"\`, record each \`batch_id\`, keep doing ledger-safe work, poll with \`collect_lane_results\` without \`wait\`, process settled lanes immediately, and use \`wait: true\` only at the join. Pass the complete immutable \`feedback_inventory\`, exact current \`pr_head_sha\`, and exact-once cumulative lane \`feedback_item_ids\`; runtime blocks replacement, stale-head artifacts, overlap, gaps, and early mutation.

package/dist/cli/{index-z8ftpav0.js → index-6t5sa6v0.js}

@@ -12,7 +12,7 @@ import {
   detectPosixWrites,
   detectWindowsWrites,
   resolveWriteTargets
-} from "./index-d88y17ht.js";
+} from "./index-5n868tw8.js";
 import {
   checkFileAuthority,
   classifyFile,

package/dist/cli/{index-5nq8dp63.js → index-b16153py.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-z8ftpav0.js";
+} from "./index-6t5sa6v0.js";
 import {
   handleGuardrailLog
 } from "./index-bf76q8q7.js";
@@ -83,7 +83,7 @@ import {
   handleWriteRetroCommand,
   normalizeSwarmCommandInput,
   resolveCommand
-} from "./index-d88y17ht.js";
+} from "./index-5n868tw8.js";
 import"./index-gxw20m1d.js";
 import"./index-3xd9a2g7.js";
 import"./index-kk1scggc.js";

package/dist/cli/index.js

@@ -7,7 +7,7 @@ import {
   getPluginLockFilePaths,
   package_default,
   resolveCommand
-} from "./index-d88y17ht.js";
+} from "./index-5n868tw8.js";
 import"./index-gxw20m1d.js";
 import"./index-3xd9a2g7.js";
 import"./index-kk1scggc.js";

package/dist/config/bundled-skills.d.ts

@@ -21,8 +21,9 @@ declare function copyBundledDirectoryBoundedAsync(sourceDir: string, destDir: st
  * tree so architect MODE dispatch never collides with repository-owned skills
  * that happen to use the same slug.
  *
- * Async, bounded, and fail-open: safe to `await withTimeout(...)` on the
- * plugin-init path (AGENTS.md Invariant 1). Runs at plugin init so the
+ * Async, bounded, and fail-open: register `withTimeout(...)` in the
+ * wrapper-owned post-resolution task queue on the plugin-init path
+ * (AGENTS.md Invariant 1). Runs at plugin init so the
  * architect's very first auto-entered mode (e.g. SPECIFY on a fresh project) can
  * load its SKILL.md without a manual `/swarm` command or session restart; the
  * command path calls it again as a backstop for pre-existing projects.

package/dist/hooks/init-orphan-recovery.d.ts

@@ -6,7 +6,7 @@
  *   - Calls cleanupOrphanedBranches(ctx.directory, []) at plugin init (no sessions active → all swarm-lane branches are orphans)
  *   - Writes results to `<directory>/.swarm/advisories/init-orphan-recovery.json`
  *   - Is wrapped in `withTimeout` so it never blocks plugin init
- *   - Runs via `queueMicrotask` off the `server()` resolution path (precedent: repoGraphHook.init)
+ *   - Runs from the wrapper-owned post-resolution queue after `server()` can settle (precedent: repoGraphHook.init)
  *
  * This module intentionally lives in `src/hooks/` so that `src/index.ts` can import
  * it without matching the forbidden `worktree/` or `merge-back/` patterns.

package/dist/hooks/pr-workflow-auto-wake.d.ts

@@ -0,0 +1,31 @@
+import { readPrWorkflowGateState } from './pr-workflow-gate.js';
+export declare const _internals: {
+    readPrWorkflowGateState: typeof readPrWorkflowGateState;
+};
+/** Bound module state: every entry is keyed by project plus parent session. */
+export declare const MAX_TRACKED_PR_WORKFLOW_WAKE_STATES = 200;
+export declare const PLUGIN_WAKE_MARKER_TTL_MS = 60000;
+type PausePhase = 'awaiting-idle' | 'paused' | 'resuming';
+export interface PrWorkflowAutoWakeDecision {
+    sessionID?: string;
+    suppressWake: boolean;
+}
+/** Mark a plugin-authored prompt until its synthetic user event is observed. */
+export declare function markPrWorkflowPluginWake(directory: string, sessionID: string): string;
+/** Remove a marker only when the host definitively rejected the prompt. */
+export declare function cancelPrWorkflowPluginWake(directory: string, sessionID: string, messageID: string): void;
+export declare function isPrWorkflowAutoWakeSuppressed(directory: string, sessionID: string): boolean;
+export declare function clearPrWorkflowAutoWakeState(directory: string, sessionID: string): void;
+/**
+ * Observe host events that distinguish a user interruption from an ordinary
+ * idle boundary. The durable workflow gate remains intact; only automatic
+ * prompts pause. A later real user turn re-enables wakes after that turn's
+ * idle boundary.
+ */
+export declare function observePrWorkflowAutoWakeEvent(directory: string, rawEvent: unknown): Promise<PrWorkflowAutoWakeDecision>;
+export declare const _test_exports: {
+    reset(): void;
+    getPausePhase(directory: string, sessionID: string): PausePhase | undefined;
+    getPluginWakeMarkerCount(directory: string, sessionID: string, now?: number): number;
+};
+export {};

package/dist/hooks/pr-workflow-gate.d.ts

@@ -191,7 +191,7 @@ export declare function bindPrReviewBase(directory: string, sessionID: string, o
 /** Prove that caller-provided PR identity equals the actual checked-out commit. */
 export declare function assertCurrentCheckoutHead(directory: string, expectedHead: string): string;
 /** Prove that every PR-review lane reads the immutable checked-out PR tree. */
-export declare function assertPrReviewCleanCheckout(directory: string): void;
+export declare function assertPrReviewCleanCheckout(directory: string, mode?: PrWorkflowMode): void;
 export declare function enforcePrWorkflowDispatchLanesAsync(directory: string, sessionID: string, toolName: string): Promise<PrWorkflowGateState | null>;
 export declare function enforcePrReviewBaseDimensions(directory: string, sessionID: string, lanes: readonly PrWorkflowLaneSpec[], options: {
     batchId: string;

package/dist/hooks/pr-workflow-response-gate.d.ts

@@ -1,3 +1,7 @@
+import { readPrWorkflowGateState } from './pr-workflow-gate.js';
+export declare const _internals: {
+    readPrWorkflowGateState: typeof readPrWorkflowGateState;
+};
 /**
  * Maximum number of consecutive unproductive auto-resumes per gated session
  * before the response gate suspends further wakes. "Unproductive" means the

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from '@opencode-ai/plugin';
+import { createRepoGraphBuilderHook } from './hooks';
 /**
  * FIFO-cap a session-keyed Map to at most `max` entries, evicting oldest first.
  * Values tracked by these maps are plain data (timestamps/usage snapshots), never
@@ -6,6 +7,19 @@ import type { Plugin } from '@opencode-ai/plugin';
  * unit testing of the cap invariant; used by the heartbeat throttle path below.
  */
 export declare function capSessionMap<K, V>(map: Map<K, V>, max: number): void;
+type PostResolutionTask = () => void | Promise<void>;
+/**
+ * Start detached initialization work only after the plugin manifest promise can
+ * settle. A microtask queued from inside `initializeOpenCodeSwarm` is not truly
+ * deferred when that function still has later awaits: the microtask can start
+ * expensive filesystem work while `server()` remains unresolved (issue #704).
+ */
+declare function schedulePostResolutionTasks(tasks: readonly PostResolutionTask[]): void;
+export declare function overrideIndexInternalsForTest(overrides: {
+    createRepoGraphBuilderHook?: typeof createRepoGraphBuilderHook;
+    schedulePostResolutionTasks?: typeof schedulePostResolutionTasks;
+}): () => void;
+export declare function schedulePostResolutionTasksForTest(tasks: readonly PostResolutionTask[]): void;
 declare const _default: {
     id: "opencode-swarm";
     server: Plugin;