opencode-swarm 7.135.2 → 7.135.4

package/dist/config/lane-permissions.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Scoped `external_directory` permission rules for swarm worktree-lane
+ * instances.
+ *
+ * ## The problem this solves
+ *
+ * A lane session is created against a new directory, so OpenCode builds it a
+ * fresh directory-keyed permission universe with an empty `approved` list. The
+ * host's default agent ruleset ends in `external_directory: { "*": "ask" }`, and
+ * a lane instance has no TUI attached to answer an ask — `Permission.ask` parks
+ * on a deferred with no timeout and the lane hangs forever.
+ *
+ * ## The mechanism
+ *
+ * The plugin `config` hook runs once per OpenCode instance (`Plugin.state` is
+ * built through the same directory-keyed `InstanceState` cache as
+ * `Permission.state`), so in a lane instance it runs with `ctx.directory` set to
+ * the lane path. Rules merged into the top-level `permission` block there are
+ * folded by the host into **every** agent's ruleset:
+ *
+ * ```js
+ * // opencode host, Agent.state
+ * l = a.fromConfig(p.permission ?? {})            // top-level config permission
+ * r = { build: { permission: a.merge(c, ..., l) }, plan: {...}, general: {...},
+ *       explore: {...}, compaction: {...}, title: {...}, summary: {...} }
+ * for (const [n, s] of Object.entries(p.agent ?? {})) {
+ *   let e = r[n];
+ *   if (!e) e = r[n] = { ..., permission: a.merge(c, l), ... };   // swarm agents
+ *   e.permission = a.merge(e.permission, a.fromConfig(s.permission ?? {}));
+ * }
+ * ```
+ *
+ * Top-level is therefore strictly broader than per-agent injection: it reaches
+ * the host-native agents (`build`, `plan`, `general`, `explore`, ...) that a
+ * lane can also run, and it lands *before* any per-agent block so explicit
+ * per-agent user config still wins. Injecting the same rules per-agent as well
+ * would duplicate every rule in every ruleset and would make our injected rules
+ * outrank the user's own top-level entries — the wrong precedence.
+ *
+ * ## DISCLOSED ASSUMPTION: hook-before-agents ordering
+ *
+ * This design requires the `config` hook to run before `Agent.state` reads the
+ * config. What is PROVEN: both sides touch the *same* object — `Plugin.state`
+ * does `U = yield* Config.get()` and mutates `U` in place, `Agent.state` does
+ * `p = yield* Config.get()`, and `Config.state` is InstanceState-cached, so
+ * `get()` returns one shared instance. There is no copy; only ordering is in
+ * question.
+ *
+ * What is NOT proven: any static ordering guarantee. Two bounded searches of
+ * the host binary came back negative — the Agent layer's deps
+ * (`deps:[J.node,O.node,P.node,_.node,$.node,Ve]`, offset 100817167) do not
+ * include the Plugin node (the three symbols the Agent chunk imports from the
+ * Plugin chunk are `$G`, `b8`, `r1`, none of which is the Plugin service), and
+ * `Plugin.init` (offset 102128681) has no caller anywhere in the bundle. The
+ * hook therefore fires lazily, when `Plugin.state` is first populated by a
+ * `Plugin.trigger` / `Plugin.list`.
+ *
+ * The evidence that it holds is empirical and strong: opencode-swarm's agents
+ * are registered ONLY by this config hook, and they demonstrably appear in the
+ * TUI, which is impossible unless the hook ran before `Agent.state` was built.
+ * Treat it as a verified-in-practice property of this host build rather than a
+ * contract. If a future OpenCode release reorders layer construction, the
+ * symptom is loud and immediate — no swarm agents at all — not a silent
+ * permission regression.
+ *
+ * ## Rule ordering is load-bearing
+ *
+ * The host evaluates with `findLast` over the flattened rule list:
+ *
+ * ```js
+ * function c(j, J, ...K) {
+ *   return K.flat().findLast((z) => g.match(j, z.permission) && g.match(J, z.pattern))
+ *          ?? { action: "ask", permission: j, pattern: "*" };
+ * }
+ * ```
+ *
+ * and `fromConfig` preserves `Object.entries` order. So **later wins**, and the
+ * catch-all `"*": "deny"` must be emitted FIRST, before the specific allows.
+ * Emitting it last would deny everything. `tests/unit/config/lane-permissions.test.ts`
+ * pins this against a faithful re-implementation of the host's own
+ * `fromConfig`/`merge`/`evaluate`, so the ordering contract is verified rather
+ * than assumed.
+ *
+ * Two further host behaviours matter and are deliberately relied upon:
+ *
+ *  - `Wildcard.match` compiles the rule pattern with `*` -> `.*` under the `s`
+ *    (dotAll) flag, so `<dir>/*` covers the entire subtree, and it normalises
+ *    `\` to `/` on both sides before matching, so native Windows paths are fine.
+ *  - After merging config, the host appends
+ *    `external_directory: { <Global.Path.data>/tool-output/*: "allow" }` to every
+ *    agent unless a rule already matches that exact pattern with `action: "deny"`.
+ *    Our catch-all uses pattern `"*"`, which does not satisfy that exact-string
+ *    check, so the append still happens and still lands last. Tool output stays
+ *    readable. The emitted ruleset is intentionally not the final ruleset.
+ *
+ * @module config/lane-permissions
+ */
+import { addDeferredWarning } from '../services/warning-buffer';
+import type { LaneContext } from './lane-context';
+import { resolveLaneContext } from './lane-context';
+/**
+ * Lane permission policy. Mirrors `worktree.lane_permissions` in
+ * `src/config/schema.ts`.
+ */
+export type LanePermissionMode = 'scoped_allow' | 'deny' | 'off';
+/** Permission actions OpenCode understands for a rule. */
+type PermissionAction = 'allow' | 'ask' | 'deny';
+/** Result of assembling a lane's `external_directory` rule map. */
+interface LaneRuleBuild {
+    /** The rule map, in emission (== evaluation) order. */
+    rules: Record<string, PermissionAction>;
+    /**
+     * User-configured patterns whose `"ask"` was coerced to `"deny"` because a
+     * lane has no TUI that could answer an ask. Empty in the common case.
+     */
+    coercedAskPatterns: string[];
+}
+/** An allowlisted directory plus the justification for granting it. */
+interface LaneAllowlistEntry {
+    /** Absolute directory path. */
+    dir: string;
+    /**
+     * The emitted `external_directory` rule pattern for {@link dir}.
+     *
+     * Computed ONCE here and reused by both consumers — the rule map and the
+     * `.swarm/events.jsonl` record. Deriving it twice meant a second round of
+     * `realpathSync.native` per entry on the config-hook path and, more
+     * importantly, left room for the two to disagree: if they ever did, the
+     * event log would misreport the rule that was actually emitted, which is
+     * precisely the observability this subsystem exists to provide.
+     */
+    pattern: string;
+    /** Why this directory is justified — recorded in `.swarm/events.jsonl`. */
+    reason: string;
+}
+/**
+ * Converts an absolute directory into the `external_directory` rule pattern
+ * that covers it and everything beneath it.
+ *
+ * The literal part of the directory is escaped for the host's matcher. The host
+ * compiles a rule pattern as:
+ *
+ * ```js
+ * o.replace(/[.+^${}()|[\]\\]/g,"\\$&").replace(/\*​/g,".*").replace(/\?/g,".")
+ * // then: new RegExp("^"+compiled+"$","si")
+ * ```
+ *
+ * Note what is NOT escaped: `*` and `?`. A directory legitimately named `a*`
+ * (legal on POSIX) would compile to `a.*` and silently grant every sibling
+ * starting with `a`; `?` becomes a single-character wildcard the same way. The
+ * matcher offers no escape syntax for either, so such a directory cannot be
+ * expressed exactly. {@link isExpressibleDirectory} therefore drops it from the
+ * allowlist rather than emitting an over-broad grant: dropping fails safe (the
+ * path is denied, and its absence is visible in the event log), emitting would
+ * fail open.
+ *
+ * The matcher also uses the `i` flag, so patterns are case-insensitive even on
+ * case-sensitive filesystems. `/home/u/Work/*` will therefore also match
+ * `/home/u/work/...`. That widening is inherent to the host and cannot be
+ * avoided from a rule pattern; it is recorded here so it is a known, reviewed
+ * property rather than a surprise.
+ */
+declare function laneDirectoryPattern(dir: string): string;
+/**
+ * Builds the justified `external_directory` allowlist for a lane.
+ *
+ * Every entry is a directory the lane provably needs in order to do the work it
+ * was created for. Nothing is added "just in case" — an over-broad allowlist
+ * here is the security cost of this fix, so each entry carries its reason and
+ * is asserted in tests.
+ *
+ * @param lane - Resolved lane context.
+ * @returns Deduplicated absolute directories with justifications.
+ */
+declare function buildLaneAllowlist(lane: LaneContext, configuredSkillPaths?: readonly string[], configuredSkillUrls?: readonly string[]): LaneAllowlistEntry[];
+/**
+ * Builds the `external_directory` rule map to write into the top-level
+ * `permission` block of a lane instance's config.
+ *
+ * Emission order (which IS the evaluation order, later-wins):
+ *
+ *  1. `"*": "deny"` — our catch-all, so nothing can be left pending in a lane
+ *     that has no TUI to answer it. This is the only mechanism that delivers
+ *     the approved policy's "answered, not hung" guarantee now that the host's
+ *     `permission.ask` plugin hook is confirmed dead (never triggered by
+ *     opencode 1.18.10).
+ *  2. Our justified allowlist — beats the catch-all because it comes later.
+ *  3. Whatever the user already configured — beats everything, because explicit
+ *     user configuration must always outrank a plugin default. A user entry
+ *     keyed `"*"` replaces our catch-all's value in place (same key), so
+ *     `external_directory: "allow"` in `opencode.json` still means allow-all.
+ *
+ * ## Why `"ask"` is coerced to `"deny"` INSIDE A LANE
+ *
+ * A user's `allow` and `deny` are honoured verbatim. `ask` is not, and that is
+ * deliberate: a lane instance has no TUI attached, so `ask` cannot be answered
+ * by anyone. It is not a third policy choice there — it is a guaranteed
+ * indefinite hang, which is the exact defect this module exists to remove.
+ * Honouring it literally would let a top-level `external_directory: "ask"` (or
+ * any `"ask"` pattern) silently reinstate the bug while this code reported
+ * success. Coercion resolves to the fail-safe direction (`deny`, never
+ * `allow`), the affected patterns are named in the advisory, and they are
+ * recorded under `coercedAskPatterns` in the `.swarm/events.jsonl` entry so the
+ * decision is auditable rather than silent. Users who genuinely want the
+ * prompting behaviour back have `worktree.lane_permissions: "off"`.
+ *
+ * @param mode     - Configured lane permission policy.
+ * @param lane     - Resolved lane context.
+ * @param existing - Current `external_directory` value from the config being
+ *                   mutated, if any.
+ * @returns The rule map plus any patterns whose `ask` was coerced, or `null`
+ *          when the policy is `off` (the caller must then touch nothing).
+ */
+declare function buildLaneExternalDirectoryRules(mode: LanePermissionMode, lane: LaneContext, existing?: unknown, precomputedAllowlist?: readonly LaneAllowlistEntry[]): LaneRuleBuild | null;
+/**
+ * Renders the operator-facing remedy text for a lane whose permissions are
+ * being scoped.
+ *
+ * The permission system itself carries an action, not a message — a `deny` rule
+ * cannot explain itself. So the explanation is delivered out-of-band (a deferred
+ * warning plus a `.swarm/events.jsonl` record) and names the exact
+ * `opencode.json` edit that widens the allowlist.
+ */
+declare function renderLanePermissionAdvisory(mode: Exclude<LanePermissionMode, 'off'>, lane: LaneContext, allowlist: readonly LaneAllowlistEntry[], coercedAskPatterns?: readonly string[]): string;
+/**
+ * Tier-0 test seam (see the writing-tests skill): these are pure functions with
+ * no external dependencies, so they are tested directly rather than mocked.
+ * They are intentionally NOT part of the module's public API — only
+ * {@link applyLanePermissions} is called from production.
+ */
+export declare const _test_exports: {
+    buildLaneAllowlist: typeof buildLaneAllowlist;
+    buildLaneExternalDirectoryRules: typeof buildLaneExternalDirectoryRules;
+    laneDirectoryPattern: typeof laneDirectoryPattern;
+    renderLanePermissionAdvisory: typeof renderLanePermissionAdvisory;
+};
+/**
+ * Test-only dependency-injection seam (AGENTS.md invariant 7). Tests replace
+ * these to assert the event record and advisory without touching the real
+ * filesystem or the process-wide warning buffer. Restore in `afterEach`.
+ */
+export declare const _internals: {
+    resolveLaneContext: typeof resolveLaneContext;
+    addDeferredWarning: typeof addDeferredWarning;
+    appendFileSync: (p: string, data: string, enc: BufferEncoding) => void;
+    mkdirSync: (p: string, opts: {
+        recursive: boolean;
+    }) => string | undefined;
+};
+/** Outcome of {@link applyLanePermissions}, returned for tests and logging. */
+export interface LanePermissionApplication {
+    /** `true` when the directory was recognised as a swarm worktree lane. */
+    lane: boolean;
+    /** Effective policy. `undefined` when `lane` is `false`. */
+    mode?: LanePermissionMode;
+    /** Rules written into `permission.external_directory`, when any. */
+    rules?: Record<string, PermissionAction>;
+}
+/**
+ * Applies scoped lane permissions to an OpenCode config object, in place.
+ *
+ * Called from the plugin `config` hook. When `directory` is not a swarm
+ * worktree lane this returns immediately and mutates NOTHING — ordinary
+ * sessions must be byte-for-byte unaffected, which
+ * `tests/unit/config/lane-permissions-config.test.ts` asserts directly.
+ *
+ * @param opencodeConfig - The live merged config object the host handed to the
+ *                         `config` hook. Mutated in place, as the hook contract
+ *                         requires.
+ * @param directory      - The plugin's own `ctx.directory`. Under this host that
+ *                         IS the instance directory, so in a lane instance it is
+ *                         the lane path.
+ * @param mode           - Configured `worktree.lane_permissions` policy.
+ * @returns What was decided, for logging and tests.
+ */
+export declare function applyLanePermissions(opencodeConfig: Record<string, unknown>, directory: string, mode: LanePermissionMode): LanePermissionApplication;
+export {};

package/dist/config/schema.d.ts

@@ -1197,6 +1197,11 @@ export declare const WorktreeIsolationConfigSchema: z.ZodObject<{
         skip: "skip";
         copy: "copy";
     }>>;
+    lane_permissions: z.ZodDefault<z.ZodEnum<{
+        scoped_allow: "scoped_allow";
+        deny: "deny";
+        off: "off";
+    }>>;
     serialization_release_after_dispatches: z.ZodDefault<z.ZodNumber>;
     serialization_release_after_ms: z.ZodDefault<z.ZodNumber>;
     runtime_isolation: z.ZodOptional<z.ZodObject<{
@@ -2449,6 +2454,11 @@ export declare const PluginConfigSchema: z.ZodObject<{
             skip: "skip";
             copy: "copy";
         }>>;
+        lane_permissions: z.ZodDefault<z.ZodEnum<{
+            scoped_allow: "scoped_allow";
+            deny: "deny";
+            off: "off";
+        }>>;
         serialization_release_after_dispatches: z.ZodDefault<z.ZodNumber>;
         serialization_release_after_ms: z.ZodDefault<z.ZodNumber>;
         runtime_isolation: z.ZodOptional<z.ZodObject<{

package/dist/config/swarm-branch.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The swarm worktree BRANCH GRAMMAR — single source of truth for both building
+ * and recognising the branch names that identify a swarm-owned worktree.
+ *
+ * ## Why a grammar and not a prefix
+ *
+ * Lane detection (`src/config/lane-context.ts`) uses the branch name as its
+ * ownership signal because, unlike the worktree's path, it is invariant across
+ * all three provisioning layouts (default `.swarm-worktrees`, a configured
+ * `worktree.worktree_dir`, and the Windows path-budget fallback that relocates
+ * a lane to `<os.tmpdir()>/swwt/...`).
+ *
+ * Matching a bare `swarm/` PREFIX is not safe. A user running
+ * `git worktree add -b swarm/my-own-experiment ../scratch` would be classified
+ * as a lane, and their ordinary interactive session would then have
+ * `external_directory: { "*": "deny", ... }` injected. That is strictly worse
+ * than the hang this subsystem exists to fix, because the host's
+ * `Permission.ask` short-circuits on a deny before it ever creates a deferred:
+ *
+ * ```js
+ * // opencode 1.18.10, Permission.ask
+ * if (W.action === "deny") return yield* new U.DeniedError({ ... });
+ * ```
+ *
+ * — so no prompt is raised and "Allow always" can never be reached. The user
+ * has no in-session recovery.
+ *
+ * The grammar below therefore matches the COMPLETE shape
+ * `makeWorktreeBranchName` emits, including a session segment constrained to
+ * OpenCode's `ses_`-prefixed identifier form. `tests/unit/config/swarm-branch.test.ts`
+ * holds a round-trip property test over the producer and a negative corpus of
+ * plausible human-authored branch names.
+ *
+ * @module config/swarm-branch
+ */
+/**
+ * True when `sessionId` is a session identifier the lane grammar can encode.
+ *
+ * Tool arguments are LLM-supplied (`sessionID: z.string()`) and the host's own
+ * `SessionID` brand is only `isStartsWith("ses")`, so a value like `ses-run-1`
+ * passes the host but yields a branch the recogniser cannot match — a lane that
+ * silently skips permission scoping and hangs. Callers that accept a session id
+ * from outside should check this before provisioning.
+ */
+export declare function isSwarmSessionId(sessionId: unknown): sessionId is string;
+/**
+ * Builds the branch name for a swarm worktree.
+ *
+ * The ONLY producer of these names. `makeWorktreeBranchName` in
+ * `src/worktree/core.ts` delegates here so the producer and
+ * {@link matchSwarmLaneBranch} cannot drift.
+ *
+ * @param sessionId    - Parent session identifier.
+ * @param id           - Execution-unit identifier (task or lane id).
+ * @param purpose      - Worktree purpose (e.g. `lane`).
+ * @param legacyLane   - Use Lean Turbo's `swarm-lane/<sessionId>/<id>` style.
+ */
+export declare function buildSwarmBranchName(sessionId: string, id: string, purpose: string, legacyLane: boolean): string;
+/**
+ * Recognises the DEFAULT lane PATH shape,
+ * `<base>/.swarm-worktrees/<sessionId>/<id>`.
+ *
+ * This is the fallback ownership signal for a worktree whose HEAD is detached
+ * or unreadable, so its branch cannot be consulted. It must be as tight as the
+ * branch grammar: matching "any path containing a `.swarm-worktrees` segment"
+ * captures a user's own `git worktree add -b my-feature ../.swarm-worktrees/manual-user-wt`,
+ * which then has an unrecoverable deny-by-default injected into an ordinary
+ * interactive session.
+ *
+ * `provisionWorktree` builds this path as
+ * `path.resolve(resolveWorktreeBaseDir(directory), sessionId, id)`, i.e. exactly
+ * two segments after the base, so the shape check requires exactly that — with
+ * the session segment held to the SAME `ses_…` constraint the branch grammar
+ * uses. The directory name comes from the same `SWARM_WORKTREE_DIR_NAME`
+ * constant `resolveWorktreeBaseDir` builds with, so the three definitions
+ * cannot drift.
+ *
+ * KNOWN RESIDUAL (accepted, not a defect to chase): a worktree the USER created
+ * at exactly `<base>/.swarm-worktrees/ses_<alnum>/<id>` on a non-swarm branch
+ * still classifies as a lane. Reaching it requires deliberately creating a
+ * directory literally named `ses_<alnum>` under a `.swarm-worktrees` base, and
+ * the same leniency is what keeps a REAL lane detected after someone checks out
+ * a different branch inside it. Narrowing further would trade a far more likely
+ * false negative (a real lane silently unscoped, i.e. the original hang) for a
+ * far less likely false positive.
+ *
+ * Note this recognises only the DEFAULT layout. A `worktree_dir` override or
+ * the Windows path-budget fallback produces a different path, and a lane in
+ * those layouts with a detached HEAD is a false NEGATIVE — no permission
+ * changes, i.e. today's behaviour. That is the safe direction.
+ *
+ * @param lanePath - An already-resolved absolute path.
+ */
+export declare function matchSwarmLanePath(lanePath: string): {
+    sessionId: string;
+    id: string;
+} | undefined;
+/** A branch name recognised as a swarm worktree lane. */
+export interface SwarmLaneBranch {
+    /** Worktree purpose. `'lane'` for the legacy style, which encodes no purpose. */
+    purpose: string;
+    sessionId: string;
+    id: string;
+    style: 'purpose' | 'legacy-lane';
+}
+/**
+ * Recognises a branch name produced by {@link buildSwarmBranchName}.
+ *
+ * Matches the complete grammar and nothing wider:
+ *   - `swarm/<purpose>/<sessionId>/<id>`   — exactly 4 segments
+ *   - `swarm-lane/<sessionId>/<id>`        — exactly 3 segments
+ *
+ * with `<sessionId>` matching `ses_[A-Za-z0-9]+` and `<purpose>` / `<id>` each
+ * a single non-empty, non-dot segment. Anything else — including a bare
+ * `swarm/my-own-experiment`, or a real lane name with extra trailing segments —
+ * returns `undefined`, which classifies the worktree as NOT swarm-owned and
+ * leaves it completely untouched.
+ *
+ * @returns The parsed branch, or `undefined` when the name is not a swarm lane.
+ */
+export declare function matchSwarmLaneBranch(branch: string): SwarmLaneBranch | undefined;
+/**
+ * Tier-0 test seam (writing-tests skill). The prefix list is an implementation
+ * detail of the grammar — production code goes through
+ * {@link buildSwarmBranchName} / {@link matchSwarmLaneBranch} — but the branch
+ * tests assert that both documented styles are actually exercised.
+ */
+export declare const _test_exports: {
+    SWARM_WORKTREE_BRANCH_PREFIXES: readonly ["swarm/", "swarm-lane/"];
+};

package/dist/hooks/curator-postmortem.d.ts

@@ -36,6 +36,14 @@ interface KnowledgeEventSummary {
     applied: number;
     violated: number;
     ignored: number;
+    /**
+     * Shown to a delegate that ended its Task without any ack marker or receipt.
+     * Audit-only silence, NOT a verdict — kept strictly separate from
+     * applied/violated/ignored so it never enters an application- or
+     * violation-rate calculation. Surfaced so a post-mortem can say
+     * "entry X: shown N times, unacknowledged M times" instead of nothing.
+     */
+    unacknowledged: number;
     confidence: number;
     status: string;
 }

package/dist/hooks/delegate-ack-collector.d.ts

@@ -12,6 +12,11 @@
  *   - For every CRITICAL directive that was shown but never acknowledged, emit a
  *     `violated` event with reason `unacknowledged` and append an audit line to
  *     `.swarm/unacknowledged-criticals.jsonl`.
+ *   - For every NON-CRITICAL directive that was shown but never acknowledged,
+ *     emit a neutral, audit-only `unacknowledged` event (reason
+ *     `no_ack_marker`). Silence is not a violation for non-criticals — it is a
+ *     visibility signal, so it is never escalated, never audited to the
+ *     criticals file, and never mutates a counter.
  *
  * Stateless by design: it re-parses the prompt rather than relying on
  * cross-hook mutable state, so it is safe under parallel delegations. Fail-open:
@@ -31,7 +36,23 @@ export interface CollectDelegateAcksResult {
         id: string;
         type: string;
     }>;
+    /**
+     * CRITICAL directives shown to the delegate that it never acknowledged. Each
+     * one is a contract violation: emitted as `violated`/`unacknowledged`, audited
+     * to `.swarm/unacknowledged-criticals.jsonl`, and fed to the repeat-mistake
+     * escalator.
+     */
     unacknowledgedCriticals: string[];
+    /**
+     * NON-critical directives shown to the delegate that it never acknowledged.
+     * These are NOT contract violations — the ack contract only obliges the
+     * delegate to answer for criticals. Each is emitted as a neutral,
+     * audit-only `unacknowledged` event so silent non-critical delivery is
+     * visible to the curator post-mortem instead of vanishing. They are never
+     * escalated, never written to the criticals audit file, and never produce
+     * promotion evidence.
+     */
+    unacknowledgedNonCritical: string[];
 }
 /**
  * Core reconciliation used by both the runtime hook and tests. Returns a summary

package/dist/hooks/delegation-gate.d.ts

@@ -265,11 +265,50 @@ interface MessageWithParts {
     info: MessageInfo;
     parts: MessagePart[];
 }
+declare function extractPlanCriticVerdict(output: unknown): 'APPROVED' | 'NEEDS_REVISION' | 'REJECTED' | null;
 /**
  * Returns whether the plan in the given directory has a valid plan-critic
  * approval. Does not throw — returns `false` for any failure (fail-closed).
  */
 export declare function isPlanCriticApproved(directory: string): Promise<boolean>;
+/**
+ * Escape hatch for the ratchet-tighter `critic_pre_plan` gate (issue #2012).
+ *
+ * When the critic returns APPROVED but the mechanical snapshot recorder
+ * ({@link recordPlanCriticApprovalSnapshotIfApplicable}) fails to persist it
+ * (verdict-format mismatch, dispatch-signal miss, or a plan.json read race),
+ * the gate permanently blocks ALL coder delegations because `critic_pre_plan`
+ * defaults to `true` and cannot be disabled (ratchet-tighter). This records a
+ * manual `plan_critic_gate` approval snapshot so the gate unblocks, with a
+ * distinct `method: 'manual_override'` audit marker so a human or downstream
+ * review can distinguish a manual approval from a mechanical critic approval.
+ *
+ * This mirrors the established escape-hatch pattern (PR_REVIEW gate #1898:
+ * `abortPrWorkflow` + `/swarm abort-pr-workflow` + `abort_pr_workflow` tool).
+ *
+ * Fail-closed preconditions:
+ * - The session must be an active **architect** session. The escape hatch is an
+ *   escalation; non-architect callers are rejected so a coder/reviewer cannot
+ *   self-unblock.
+ * - A plan.json must exist; you cannot approve a non-existent plan.
+ *
+ * @param directory - Project root containing `.swarm/`
+ * @param sessionID - The caller's session id (must be an architect session)
+ * @param options.reason - Optional human/agent-supplied reason (audited)
+ * @param options.userConfirmed - `true` only when invoked via the restricted
+ *   `/swarm approve-plan-critic` command (human-run); `false` when invoked via
+ *   the `approve_plan_critic` tool (agent-initiated). Recorded in the audit so a
+ *   self-approve is visible.
+ */
+export declare function forceRecordPlanCriticApproval(directory: string, sessionID: string, options?: {
+    reason?: string;
+    userConfirmed?: boolean;
+}): Promise<{
+    planId: string;
+    recordedAt: string;
+    reason?: string;
+    userConfirmed: boolean;
+}>;
 export declare function resolveDelegatedPlanTaskId(args: Record<string, unknown>, knownPlanTaskIds?: ReadonlySet<string>): string | null;
 /**
  * Builds a cause-specific diagnostic for `prepareCoderScope`'s SCOPE_NOT_DECLARED
@@ -332,7 +371,9 @@ export declare const _internals: {
     bindBackgroundCoderReservationForDispatch: typeof import("../background/pending-delegations.js").bindBackgroundCoderReservation;
     releaseBackgroundCoderReservationForDispatch: typeof import("../background/pending-delegations.js").releaseBackgroundCoderReservation;
     resetStandardWorktreeIsolationState: typeof resetStandardWorktreeIsolationState;
-    PLAN_CRITIC_TASK_SIGNALS: readonly ["critic-gate", "plan critic", "review plan", "review the plan", "plan.md", "approve the plan", "plan approval"];
+    PLAN_CRITIC_TASK_SIGNALS: readonly ["critic-gate", "plan critic", "review plan", "review the plan", "plan.md", "approve the plan", "plan approval", "pre-implementation review", "evaluate this plan", "evaluate the plan", "assess this plan", "assess the plan", "plan soundness", "before implementation", "review the plan below"];
+    extractPlanCriticVerdict: typeof extractPlanCriticVerdict;
+    forceRecordPlanCriticApproval: typeof forceRecordPlanCriticApproval;
     provisionWorktree: typeof _wtiInternals.provisionWorktree;
     removeWorktree: typeof _wtiInternals.removeWorktree;
     attemptMergeBackFromDirty: typeof _wtiInternals.attemptMergeBackFromDirty;

package/dist/hooks/knowledge-events.d.ts

@@ -74,7 +74,20 @@ export interface ReceiptEvent {
      * counter (there is no `knowledge_id` to credit; this is a trace-level
      * tombstone, not application credit).
      */
-     | 'no_relevant';
+     | 'no_relevant'
+    /**
+     * A shown non-critical directive reached the end of a delegate Task with no
+     * ack marker and no receipt. Audit-only visibility signal; never penalizes
+     * the entry's outcome/violation counters.
+     *
+     * Motivation: before this event, only CRITICAL silence produced a signal (a
+     * `violated`/`unacknowledged` event). Non-critical silence was invisible, so
+     * a corpus with 1 critical entry out of 103 reported ~4% receipt compliance
+     * with no way to see where the other 96% went. This is the missing
+     * observation, NOT a verdict: the delegate filed nothing, so there is no
+     * terminal to credit or penalize.
+     */
+     | 'unacknowledged';
     schema_version?: number;
     event_id: string;
     trace_id: string;
@@ -213,11 +226,30 @@ export declare function newEventId(): string;
  * {@link recordKnowledgeEvent}, which swallows errors.
  */
 export declare function appendKnowledgeEvent(directory: string, event: KnowledgeEventInput): Promise<KnowledgeEvent>;
+/**
+ * Append several events under ONE lock acquisition and ONE cap-trim pass.
+ * Multi-event emitters on awaited paths (e.g. the delegate ack-collector's
+ * per-directive `unacknowledged` loop, up to `delegate_max_inject_count`
+ * events per delegation) must use this instead of N sequential
+ * {@link appendKnowledgeEvent} calls — each of those takes the directory
+ * lock and re-reads the whole log for the FIFO trim, which is material on
+ * cold filesystems and under parallel delegations.
+ *
+ * Throws on I/O failure — hot paths should prefer
+ * {@link recordKnowledgeEventsBatch}, which swallows errors.
+ */
+export declare function appendKnowledgeEventsBatch(directory: string, events: KnowledgeEventInput[]): Promise<KnowledgeEvent[]>;
 /**
  * Fail-open variant of {@link appendKnowledgeEvent} for hot paths (hooks, tool
  * execution). Never throws; logs a warning and returns null on failure.
  */
 export declare function recordKnowledgeEvent(directory: string, event: KnowledgeEventInput): Promise<KnowledgeEvent | null>;
+/**
+ * Fail-open variant of {@link appendKnowledgeEventsBatch} for hot paths.
+ * Never throws; logs a warning and returns null on failure (all-or-nothing:
+ * the batch is a single append, so there are no partial writes to report).
+ */
+export declare function recordKnowledgeEventsBatch(directory: string, events: KnowledgeEventInput[]): Promise<KnowledgeEvent[] | null>;
 /**
  * Append one event to the shared, cross-project hive events log. Use for audit
  * tombstones of mutations to the hive store so any project can read why a hive

package/dist/hooks/skill-propagation-gate.d.ts

@@ -29,6 +29,16 @@ import { appendSkillUsageEntry, readSkillUsageEntries, readSkillUsageEntriesTail
 export declare function loadRoutingSkills(directory: string, targetAgent: string): string[];
 /** Agents that should receive skill context in delegations. */
 export declare const SKILL_CAPABLE_AGENTS: Set<string>;
+/**
+ * Skill root directories to scan for SKILL.md files.
+ *
+ * Exported because `src/config/lane-permissions.ts` resolves these same
+ * project-relative roots to absolute directories when building the
+ * `external_directory` allowlist for a worktree-lane instance. Keeping one
+ * definition means a new skill root cannot be added here and silently become
+ * an unanswerable permission prompt inside a lane.
+ */
+export declare const SKILL_SEARCH_ROOTS: string[];
 /**
  * Maximum number of session-scoped skill-usage tail entries to process for
  * skill scoring. This applies to the bounded tail-read window only.