opencode-swarm 7.136.1 → 7.136.3

package/dist/cli/{skill-generator-yyc8zd9j.js → skill-generator-8gtq1ajr.js}

@@ -33,21 +33,21 @@ import {
   sanitizeSlug,
   selectCandidateEntries,
   writeEvalStub
-} from "./index-1sq47n6t.js";
-import"./index-dyy3hvk3.js";
-import"./index-jwrydqjp.js";
+} from "./index-gj5jerzz.js";
+import"./index-79pgzj9a.js";
+import"./index-176zwqcq.js";
 import"./index-rtry5xyf.js";
-import"./index-hzkvbycn.js";
-import"./index-kzc2ygea.js";
+import"./index-wbdxmf1a.js";
+import"./index-mgbpbs1f.js";
 import"./index-ae75rja9.js";
-import"./index-dzyjb33e.js";
-import"./index-ey29aap6.js";
+import"./index-zzhyws9g.js";
+import"./index-b3jfcptk.js";
 import"./index-bk5tah7q.js";
 import"./index-4rhhvd1a.js";
 import"./index-fsrp8wp3.js";
-import"./index-09b9zncg.js";
+import"./index-tncy55bp.js";
 import"./index-7g4c7s5r.js";
-import"./index-7a2hm51h.js";
+import"./index-cze4bq1x.js";
 import"./index-y111zefa.js";
 import"./index-zgwm4ryv.js";
 import"./index-a76rekgs.js";

package/dist/cli/{telemetry-859khp82.js → telemetry-6678gya0.js}

@@ -12,7 +12,7 @@ import {
   startHeartbeatTracking,
   stopHeartbeatTracking,
   telemetry
-} from "./index-7a2hm51h.js";
+} from "./index-cze4bq1x.js";
 import"./index-a76rekgs.js";
 export {
   telemetry,

package/dist/cli/{workspace-snapshot-jmyamqnv.js → workspace-snapshot-h5rzw37b.js}

@@ -31,11 +31,13 @@ import {
   resolvePrReviewDiffStatsAsync,
   resolvePrWorkflowRevisionDigest,
   resolvePrWorkflowRevisionDigestAsync,
+  resolvePrWorkflowRevisionDigestDetailed,
+  resolvePrWorkflowRevisionDigestDetailedAsync,
   resolveRemoteRefsContainingHead,
   resolveRemoteRefsContainingHeadAsync,
   switchPrFeedbackTrackingCandidateAsync,
   workspaceSnapshotMatches
-} from "./index-y6a7gjtj.js";
+} from "./index-wsdnttf4.js";
 import"./index-y111zefa.js";
 import"./index-a76rekgs.js";
 export {
@@ -43,6 +45,8 @@ export {
   switchPrFeedbackTrackingCandidateAsync,
   resolveRemoteRefsContainingHeadAsync,
   resolveRemoteRefsContainingHead,
+  resolvePrWorkflowRevisionDigestDetailedAsync,
+  resolvePrWorkflowRevisionDigestDetailed,
   resolvePrWorkflowRevisionDigestAsync,
   resolvePrWorkflowRevisionDigest,
   resolvePrReviewDiffStatsAsync,

package/dist/cli/{worktree-collision-ownership-13btcj9g.js → worktree-collision-ownership-wt7cc850.js}

@@ -8,13 +8,13 @@ import {
 import {
   scanDelegationFallbacksForRecovery,
   scanDelegationsForRecovery
-} from "./index-45t7w06b.js";
+} from "./index-7t3vjw5e.js";
 import"./index-4qzeef9h.js";
 import"./index-fsrp8wp3.js";
-import"./index-09b9zncg.js";
+import"./index-tncy55bp.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
-import"./index-7a2hm51h.js";
+import"./index-cze4bq1x.js";
 import"./index-z6xqpmqg.js";
 import"./index-zjygnfay.js";
 import {

package/dist/commands/registry.d.ts

@@ -258,6 +258,78 @@ export declare const COMMAND_REGISTRY: {
         readonly category: "diagnostics";
         readonly toolPolicy: "agent";
     };
+    readonly 'skill-opt': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Governed single-skill optimizer (issue #1822). Proposes, validates, and activates one allowlisted SKILL.md candidate at a time with durable lifecycle, serial control, and manual approval.";
+        readonly args: "plan|run|status|diff|approve|reject|rollback|history <slug> [candidateId] [--json] [--confirm] [--expected-content-hash <hash>] [--models <csv>] [--dry-run]";
+        readonly details: "Disabled/proposal-only by default. `run` requires skill_opt.enabled=true AND --confirm (consumes a held-out test set). approve/activate/reject/rollback are human-only and require --expected-content-hash to refuse a stale base. Stores append-only lifecycle under .swarm/evolution/skills/<slug>/<candidateId>/.";
+        readonly category: "utility";
+        readonly toolPolicy: "agent";
+    };
+    readonly 'skill-opt plan': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Propose an optimization round (dry-run; no mutation, no validation)";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> [--json] [--models <csv>]";
+        readonly category: "utility";
+        readonly toolPolicy: "agent";
+    };
+    readonly 'skill-opt run': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Execute the optimization loop (draft→smoke→validate; held-out set is single-use so at most one validation per run). Requires skill_opt.enabled=true and --confirm.";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> --confirm [--json] [--models <csv>]";
+        readonly category: "utility";
+        readonly toolPolicy: "human-only";
+    };
+    readonly 'skill-opt status': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show the current candidate lifecycle state";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> <candidateId> [--json]";
+        readonly category: "utility";
+        readonly toolPolicy: "agent";
+    };
+    readonly 'skill-opt diff': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show baseline-vs-candidate diff summary for a candidate";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> <candidateId> [--json]";
+        readonly category: "utility";
+        readonly toolPolicy: "agent";
+    };
+    readonly 'skill-opt approve': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Activate a pending candidate (human-only; requires --expected-content-hash)";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> <candidateId> --expected-content-hash <hash> [--json]";
+        readonly category: "utility";
+        readonly toolPolicy: "human-only";
+    };
+    readonly 'skill-opt reject': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Record a rejection for a candidate (no active-skill mutation)";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> <candidateId> [--json]";
+        readonly category: "utility";
+        readonly toolPolicy: "human-only";
+    };
+    readonly 'skill-opt rollback': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Restore the pre-activation snapshot (appends a rolled_back event)";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> <candidateId> [--json]";
+        readonly category: "utility";
+        readonly toolPolicy: "human-only";
+    };
+    readonly 'skill-opt history': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show the append-only lifecycle event log for a candidate";
+        readonly subcommandOf: "skill-opt";
+        readonly args: "<slug> <candidateId> [--json]";
+        readonly category: "utility";
+        readonly toolPolicy: "agent";
+    };
     readonly review: {
         readonly handler: typeof handleReviewCommand;
         readonly description: "Run the independent review model against a selected Git diff";

package/dist/commands/skill-opt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `/swarm skill-opt` command group (issue #1822).
+ *
+ * Subcommands: plan | run | status | diff | approve | reject | rollback | history
+ *
+ * - JSON output on `--json` (convention: gate-stats.ts).
+ * - Disabled/proposal-only default: `run` requires `config.skill_opt.enabled === true`
+ *   AND an explicit `--confirm`. `plan`/`status`/`diff`/`history` are always
+ *   available (read-only / proposal-only).
+ * - `approve`/`activate`/`reject`/`rollback` are human-gated
+ *   (`toolPolicy: 'human-only'` on the registry entries) and require an
+ *   explicit `--expected-content-hash` (D6) — slash commands do NOT go through
+ *   scope-guard (which is coder-only), so the hash check is the staleness guard.
+ */
+import { type SkillOptConfig } from '../config/schema.js';
+import type { EvaluationModelDispatcher } from '../evaluation/model-dispatcher.js';
+/** Resolve the skill_opt config from raw plugin config, fail-open to defaults. */
+export declare function resolveSkillOptConfig(input: unknown): SkillOptConfig;
+export interface SkillOptRuntime {
+    dispatcher?: EvaluationModelDispatcher;
+    parentSessionId?: string;
+    config?: SkillOptConfig;
+}
+/** `/swarm skill-opt plan <slug>` — propose a round (dry-run). */
+export declare function handleSkillOptPlan(directory: string, args: string[], runtime?: SkillOptRuntime): Promise<string>;
+/** `/swarm skill-opt run <slug>` — execute a round (requires enabled + --confirm). */
+export declare function handleSkillOptRun(directory: string, args: string[], runtime?: SkillOptRuntime): Promise<string>;
+/** `/swarm skill-opt status <slug> [candidateId]` — current candidate state. */
+export declare function handleSkillOptStatus(directory: string, args: string[]): Promise<string>;
+/** `/swarm skill-opt diff <slug> <candidateId>` — baseline vs candidate diff. */
+export declare function handleSkillOptDiff(directory: string, args: string[]): Promise<string>;
+/** `/swarm skill-opt approve <slug> <candidateId> --expected-content-hash <hash>` — activate. */
+export declare function handleSkillOptApprove(directory: string, args: string[]): Promise<string>;
+/** `/swarm skill-opt reject <slug> <candidateId>` — record rejection (no mutation). */
+export declare function handleSkillOptReject(directory: string, args: string[]): Promise<string>;
+/** `/swarm skill-opt rollback <slug> <candidateId>` — restore snapshot. */
+export declare function handleSkillOptRollback(directory: string, args: string[]): Promise<string>;
+/** `/swarm skill-opt history <slug> <candidateId>` — replay log. */
+export declare function handleSkillOptHistory(directory: string, args: string[]): Promise<string>;
+/** Compute the current content hash of a skill (for the approve hash arg). */
+export declare function computeSkillContentHash(directory: string, skillSlug: string): string;

package/dist/config/schema.d.ts

@@ -527,6 +527,11 @@ export declare const GuardrailsConfigSchema: z.ZodObject<{
     block_destructive_commands: z.ZodDefault<z.ZodBoolean>;
     interpreter_allowed_agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     shell_audit_log: z.ZodDefault<z.ZodBoolean>;
+    gate_denial_warn_threshold: z.ZodDefault<z.ZodNumber>;
+    gate_denial_stop_threshold: z.ZodDefault<z.ZodNumber>;
+    execution_stall_warn_calls: z.ZodDefault<z.ZodNumber>;
+    execution_stall_stop_calls: z.ZodDefault<z.ZodNumber>;
+    execution_stall_episode_minutes: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
 export declare const WatchdogConfigSchema: z.ZodObject<{
@@ -978,6 +983,36 @@ export declare const SkillsConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type SkillsConfig = z.infer<typeof SkillsConfigSchema>;
+/**
+ * Governed skill optimizer configuration (issue #1822 — SkillOpt 3/7).
+ *
+ * Disabled by default. When disabled, `/swarm skill-opt run` refuses to
+ * execute a round (it still allows `plan`/`status`/`diff`/`history` in
+ * proposal-only mode). Enabling does NOT mutate skills autonomously: every
+ * activation requires an explicit human `/swarm skill-opt approve` with a
+ * current content hash. This config is consulted only inside command handlers
+ * (never on the plugin init path — AGENTS.md invariant #1).
+ */
+export declare const SkillOptConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_rounds: z.ZodDefault<z.ZodNumber>;
+    max_candidates_per_round: z.ZodDefault<z.ZodNumber>;
+    max_validations_per_round: z.ZodDefault<z.ZodNumber>;
+    max_round_time_ms: z.ZodDefault<z.ZodNumber>;
+    max_tokens_per_round: z.ZodDefault<z.ZodNumber>;
+    max_rejections: z.ZodDefault<z.ZodNumber>;
+    max_inconclusive_rounds: z.ZodDefault<z.ZodNumber>;
+    max_transient_retries: z.ZodDefault<z.ZodNumber>;
+    convergence_non_improvements: z.ZodDefault<z.ZodNumber>;
+    max_changed_lines: z.ZodDefault<z.ZodNumber>;
+    max_changed_bytes: z.ZodDefault<z.ZodNumber>;
+    max_changed_sections: z.ZodDefault<z.ZodNumber>;
+    deadband: z.ZodDefault<z.ZodNumber>;
+    retirement_min_age_days: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type SkillOptConfig = z.infer<typeof SkillOptConfigSchema>;
+/** Default governed-skill-optimizer config (fully disabled/safe). */
+export declare const DEFAULT_SKILL_OPT_CONFIG: SkillOptConfig;
 export declare const SpecWriterConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -1854,6 +1889,11 @@ export declare const PluginConfigSchema: z.ZodObject<{
         block_destructive_commands: z.ZodDefault<z.ZodBoolean>;
         interpreter_allowed_agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
         shell_audit_log: z.ZodDefault<z.ZodBoolean>;
+        gate_denial_warn_threshold: z.ZodDefault<z.ZodNumber>;
+        gate_denial_stop_threshold: z.ZodDefault<z.ZodNumber>;
+        execution_stall_warn_calls: z.ZodDefault<z.ZodNumber>;
+        execution_stall_stop_calls: z.ZodDefault<z.ZodNumber>;
+        execution_stall_episode_minutes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     watchdog: z.ZodOptional<z.ZodObject<{
         scope_guard: z.ZodDefault<z.ZodBoolean>;
@@ -2691,6 +2731,23 @@ export declare const PluginConfigSchema: z.ZodObject<{
     skills: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    skill_opt: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_rounds: z.ZodDefault<z.ZodNumber>;
+        max_candidates_per_round: z.ZodDefault<z.ZodNumber>;
+        max_validations_per_round: z.ZodDefault<z.ZodNumber>;
+        max_round_time_ms: z.ZodDefault<z.ZodNumber>;
+        max_tokens_per_round: z.ZodDefault<z.ZodNumber>;
+        max_rejections: z.ZodDefault<z.ZodNumber>;
+        max_inconclusive_rounds: z.ZodDefault<z.ZodNumber>;
+        max_transient_retries: z.ZodDefault<z.ZodNumber>;
+        convergence_non_improvements: z.ZodDefault<z.ZodNumber>;
+        max_changed_lines: z.ZodDefault<z.ZodNumber>;
+        max_changed_bytes: z.ZodDefault<z.ZodNumber>;
+        max_changed_sections: z.ZodDefault<z.ZodNumber>;
+        deadband: z.ZodDefault<z.ZodNumber>;
+        retirement_min_age_days: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
 export type { AgentName, PipelineAgentName, QAAgentName, } from './constants';

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

@@ -221,6 +221,14 @@ export interface CoverageMissDiagnostic {
     divergenceOffset: number;
     corruptionHint?: string;
 }
+/**
+ * Issue #2063 (A2): per-body cap, in characters, on the raw requirement body
+ * embedded verbatim in the ACCEPTANCE_FIELD_COVERAGE_MISMATCH error. Keeps the
+ * thrown message bounded even for an unusually long FR/SC body; when a body
+ * exceeds this cap the message states the cap and points at `.swarm/spec.md`
+ * for the remainder rather than growing the error without limit.
+ */
+export declare const ACCEPTANCE_EXPECTED_BODY_CAP = 2000;
 export declare function describeCoverageMiss(params: {
     rawExpectedBody: string;
     rawAcceptanceText: string;
@@ -240,7 +248,9 @@ export declare function describeCoverageMiss(params: {
  *
  * @returns `{ covered: true }` when every id is present-and-covered or skipped;
  *   `{ covered: false, missingId }` naming the FIRST id whose body is not a
- *   substring of the ACCEPTANCE text.
+ *   substring of the ACCEPTANCE text, plus `expectedBody` — the RAW, UNTRIMMED
+ *   requirement body for `missingId` (issue #2063 A2) — so the throw site can
+ *   embed paste-ready remediation text instead of just pointing at a location.
  */
 export declare function checkAcceptanceCoversFrRefs(params: {
     acceptanceText: string;
@@ -250,6 +260,7 @@ export declare function checkAcceptanceCoversFrRefs(params: {
     covered: boolean;
     missingId?: string;
     diagnostic?: CoverageMissDiagnostic;
+    expectedBody?: string;
 };
 interface MessageInfo {
     role: string;

package/dist/hooks/gate-denial-tracker.d.ts

@@ -0,0 +1,175 @@
+/**
+ * GATE DENIAL TRACKER (issue #2063, workstream B1)
+ *
+ * The architect session had no containment for a *denial-retry* loop: every
+ * fail-closed `tool.execute.before` hook throws, the host reports the throw as
+ * a tool rejection, and the model happily re-issues the identical dispatch —
+ * forever. Nothing counted the repeats, so nothing ever escalated.
+ *
+ * This module owns that counter. `noteGateDenial` is called from the single
+ * catch site wrapping the fail-closed chain in `src/index.ts`. It:
+ *   1. classifies the denial by the leading code token of the error message,
+ *   2. increments a per-(sessionID, toolName, discriminator, code) streak,
+ *   3. APPENDS (never rewrites) escalating guidance to the error message so the
+ *      model reads it in the tool-rejection text, and
+ *   4. at the hard rung, pushes an advisory + emits telemetry.
+ *
+ * The DISCRIMINATOR (reviewer round-4 REQUIRED 2) is the canonicalized
+ * `subagent_type` of a `Task` call, and the empty string for every other tool.
+ * Without it the reset was too wide: `resetGateDenialStreaks` drops a whole
+ * (session, tool) prefix on any successful completion of that tool, so ONE
+ * successful `Task` → `explorer` erased a 4-deep `ACCEPTANCE_FIELD_REQUIRED`
+ * streak on `Task` → `coder`. Under the interleaving the loop actually
+ * exhibits — deny coder, delegate an explorer to investigate, deny coder again —
+ * the STOP rung was unreachable. Sub-scoping both the count and the reset by
+ * dispatch target makes a success clear only what plausibly succeeded.
+ *
+ * Invariants this module must not break:
+ *   - The caller ALWAYS rethrows. Decoration is append-only, so the leading
+ *     code token of the original message stays byte-identical and every
+ *     existing consumer that substring-matches a gate code keeps working.
+ *   - Abort/cancel errors are excluded entirely (a user hitting escape three
+ *     times is not a loop) — they neither count nor reset an existing streak.
+ *   - Nothing here may throw. A tracker failure must never convert a
+ *     fail-closed denial into a different error.
+ *
+ * NOT to be confused with `swarmState.gateDenialCounts` (src/state.ts:768),
+ * which counts knowledge-application gate denials keyed by *critical-directive
+ * identity*. Different trigger, different key, different lifecycle.
+ *
+ * Eviction is modelled on `BoundedPendingScopeMap`
+ * (src/hooks/delegation-gate.ts:144-179) — TTL sweep plus a hard size cap — but
+ * deliberately re-implemented here rather than imported, because
+ * `delegation-gate.ts` is itself a member of the chain this module wraps and an
+ * import would create a cycle.
+ */
+/** Default streak length at which the "do not retry" guidance is appended. */
+export declare const DEFAULT_GATE_DENIAL_WARN_THRESHOLD = 3;
+/** Default streak length at which the hard STOP directive is appended. */
+export declare const DEFAULT_GATE_DENIAL_STOP_THRESHOLD = 5;
+/** Classification used when the message carries no recognisable code token. */
+export declare const UNCLASSIFIED_GATE_DENIAL_CODE = "UNCLASSIFIED";
+/**
+ * Sub-scope of a denial streak inside one (session, tool) pair.
+ *
+ * For a `Task` call this is the canonicalized dispatch target, so `mega_coder`
+ * and `coder` share one streak (matching `canonicalDispatchRole` in
+ * `guardrails/execution-stall.ts`). Every other tool — and a `Task` whose
+ * `subagent_type` is absent or not a string — yields `''`, which preserves the
+ * pre-discriminator behavior for them exactly.
+ *
+ * Deliberately reads `subagent_type` ONLY. `parseDelegationArgs`
+ * (`hooks/skill-propagation-gate.ts:400`) additionally falls back to the first
+ * non-empty line of the delegation PROMPT, which would turn arbitrary
+ * model-authored prose into a map key — an unbounded-cardinality hazard
+ * (invariant 8) and a way for the model to shatter its own streak into
+ * singletons by varying one line of text.
+ *
+ * Never throws.
+ */
+export declare function gateDenialDiscriminator(tool: string, args: unknown): string;
+/**
+ * Derive the denial classification from an error message: the leading token up
+ * to the first `:`, trimmed.
+ *
+ * `'ACCEPTANCE_FIELD_COVERAGE_MISMATCH: task 1.1 ...'` -> `'ACCEPTANCE_FIELD_COVERAGE_MISMATCH'`
+ * `'FULL_AUTO_DENY [path_out_of_root]: ...'`           -> `'FULL_AUTO_DENY [path_out_of_root]'`
+ * `'Blocked by skill propagation gate'`                -> `'UNCLASSIFIED'` (no colon)
+ *
+ * The whole point of the classification is that repeats of the SAME cause share
+ * a value, so anything that cannot be a stable code (empty, absent, or longer
+ * than {@link MAX_CODE_LENGTH}) collapses to UNCLASSIFIED rather than producing
+ * a per-occurrence key.
+ */
+export declare function deriveGateDenialCode(message: string): string;
+/**
+ * True when the thrown value is a user/host abort rather than a policy denial.
+ * Aborts must not count toward a denial streak AND must not reset one: a user
+ * cancelling mid-loop does not mean the loop was resolved.
+ */
+export declare function isAbortLikeError(err: unknown): boolean;
+/** The append-only warn rung. Exported so tests assert the exact wording. */
+export declare function gateDenialWarnText(count: number, code: string): string;
+/**
+ * The append-only hard rung, modelled on `nonTransientHardStopMessage`
+ * (src/hooks/guardrails/nontransient-circuit.ts:336-354).
+ */
+export declare function gateDenialStopText(count: number, code: string, tool: string): string;
+export interface GateDenialOptions {
+    /**
+     * `guardrails.enabled`. The thresholds live in the `guardrails` config block
+     * and the loader force-sets `enabled: false` when a user turns guardrails
+     * off, so that flag has to mean "no guardrails behavior" here too — otherwise
+     * the config surface lies. When false the denial is neither counted nor
+     * decorated, and no advisory or telemetry is produced. Defaults to true.
+     */
+    enabled?: boolean;
+    /** `guardrails.gate_denial_warn_threshold` */
+    warnThreshold?: number;
+    /** `guardrails.gate_denial_stop_threshold` */
+    stopThreshold?: number;
+}
+export interface GateDenialOutcome {
+    /** Classification used for the streak key. */
+    code: string;
+    /** Streak length AFTER this denial. `0` when the denial was not counted. */
+    count: number;
+    /** Whether the warn rung fired on this denial. */
+    warned: boolean;
+    /** Whether the hard rung fired on this denial. */
+    stopped: boolean;
+    /** Whether the error message was mutated. */
+    decorated: boolean;
+}
+/**
+ * Count one fail-closed denial and, past the configured rungs, APPEND guidance
+ * to `err.message` in place.
+ *
+ * The caller is responsible for rethrowing the SAME object — mutating in place
+ * preserves `name`, `stack`, and any custom fields a gate attached, which
+ * constructing a replacement Error would destroy.
+ *
+ * `args` are the resolved `tool.execute.before` args of the DENIED call. They
+ * derive the discriminator, so a `Task` → `coder` streak and a `Task` →
+ * `explorer` streak are counted (and reset) separately. Omitting them is safe
+ * and reproduces the pre-discriminator single-bucket behavior.
+ *
+ * Never throws.
+ */
+export declare function noteGateDenial(sessionID: string, tool: string, err: unknown, options?: GateDenialOptions, args?: unknown): GateDenialOutcome;
+/**
+ * Clear every denial streak for one (sessionID, toolName, discriminator) triple.
+ *
+ * Called when the fail-closed chain completes successfully for that tool: the
+ * dispatch that was being denied now passes, so the streak is over.
+ *
+ * Two levels of scoping, both load-bearing:
+ *   - by TOOL, so a successful `read` does not erase an in-progress `Task`
+ *     denial loop; and
+ *   - by DISCRIMINATOR, so a successful `Task` → `explorer` does not erase an
+ *     in-progress `Task` → `coder` denial loop. `args` are the resolved
+ *     `tool.execute.before` args of the call that just SUCCEEDED, which is the
+ *     only thing that can be said to have been resolved. Omitting them clears
+ *     the `''` bucket only.
+ */
+export declare function resetGateDenialStreaks(sessionID: string, tool: string, args?: unknown): void;
+/**
+ * Drop all tracked streaks.
+ *
+ * A test/reset helper only — there is no `/swarm close` (or any other
+ * production) caller. Streak lifetime in production is governed by
+ * {@link GATE_DENIAL_TTL_MS}, the {@link MAX_TRACKED_DENIAL_STREAKS} LRU cap,
+ * and `resetGateDenialStreaks`.
+ */
+export declare function clearGateDenialStreaks(): void;
+export declare const _test_exports: {
+    readonly MAX_TRACKED_DENIAL_STREAKS: 500;
+    readonly GATE_DENIAL_TTL_MS: number;
+    readonly MAX_CODE_LENGTH: 64;
+    readonly MAX_DISCRIMINATOR_LENGTH: 64;
+    readonly streakCount: () => number;
+    /** Read a streak length without mutating it. */
+    readonly peekStreak: (sessionID: string, tool: string, code: string, discriminator?: string) => number;
+    /** Force a streak's TTL into the past so eviction can be tested. */
+    readonly expireStreak: (sessionID: string, tool: string, code: string, discriminator?: string) => void;
+};

package/dist/hooks/guardrails/execution-episode.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Execution-episode seam (issue #2063 B3/B5).
+ *
+ * An "execution episode" is the window in which a session has actually
+ * attempted execution work — a `Task` dispatch to a mutating/verifying role, or
+ * an `update_task_status(..., in_progress)` that succeeded. Containment levers
+ * that would produce false positives during ordinary conversation, planning, or
+ * read-only review are gated on the episode being ARMED.
+ *
+ * This module is deliberately narrow: it owns nothing but the read/write of the
+ * `executionEpisodeArmed` session field, so that
+ *
+ *   - the CONSUMER side (B3's medium-band runaway counting in
+ *     `messages-transform.ts`) has a single, testable predicate, and
+ *   - the PRODUCER side (B5's arming/lapse policy in `execution-stall.ts`)
+ *     has a single, testable mutator to call.
+ *
+ * Keeping the field access behind these two functions is what prevents the
+ * arming policy from being duplicated at each call site as it grows.
+ *
+ * Defaults are fail-open toward "not armed": an unknown session, a session with
+ * no state, and a session whose field was never initialised all read `false`,
+ * so a lever gated on this seam stays silent rather than firing on a session it
+ * knows nothing about.
+ */
+/**
+ * Whether an execution episode is currently armed for `sessionID`.
+ *
+ * Returns `false` for unknown sessions.
+ */
+export declare function isExecutionEpisodeArmed(sessionID: string): boolean;
+/**
+ * Arm or disarm the execution episode for `sessionID`.
+ *
+ * No-ops for an unknown session: arming state is meaningless without a session
+ * to hang it on, and creating one here would let a containment lever
+ * materialise session state as a side effect.
+ *
+ * @returns `true` when the field was written, `false` when the session is unknown.
+ */
+export declare function setExecutionEpisodeArmed(sessionID: string, armed: boolean): boolean;