@mgiles/perk 2.3.0 → 3.0.0

package/extension/factories/planReview.ts

@@ -34,8 +34,9 @@
 // discarded (the aborted arm wins). Enter submits in the editor dialog (Shift+Enter = newline),
 // so the dialog titles carry the key hints — pi renders no other affordance.
 //
-// THE OBJECTIVE ARM: an objective-author session (read-only, stage
-// `objective-author`) routes through `executeObjectiveReview` instead of the plan path — the
+// THE OBJECTIVE ARM: an objective-authoring session (read-only, stage `objective-author` or
+// `objective-save` — the two stages whose working draft IS the objective draft; neither carries
+// `plan_draft`) routes through `executeObjectiveReview` instead of the plan path — the
 // reviewed bytes are the RENDERED objective draft (`readObjectiveDraft` + `renderObjectiveDraft`,
 // objectiveDraft.ts — never raw JSON, never the `plan` param, never the transcript; no draft
 // soft-skips with `reason: "no_objective_draft"`). Dispatch mirrors the plan path (plannotator
@@ -49,7 +50,11 @@
 // `executeGistReview` the same way — the reviewed bytes are the RENDERED gist draft
 // (`readGistDraft` + `renderGistDraft`, gistDraft.ts), first-party VIEW-ONLY, implement-here
 // never offered, APPROVED → the `gistApprovalSave` seam (gistSave.ts), no draft soft-skips with
-// `reason: "no_gist_draft"`.
+// `reason: "no_gist_draft"`. Plannotator approve-with-Direct-Edits mirrors the objective arm:
+// the save seam re-reads the STRUCTURED gist artifact, so rendered edits cannot be folded back
+// mechanically — the arm SKIPS the save and returns one model-mediated revise round (fold each
+// hunk into the matching `gist_draft` field — title heading → `title`, `Scope:` line → `scope`,
+// prose → `prose` — then re-review to confirm).
 //
 // INVARIANTS HELD: never calls `setActiveTools`, never registers a `tool_call` handler, never
 // restamps `cache.plan-ref.provider`. The door composes the gate AND the save EXCLUSIVELY
@@ -75,7 +80,11 @@ import { implementHereExit, implementHereGuidance } from "./implementHere.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 import { readObjectiveDraft, renderObjectiveDraft } from "./objectiveDraft.ts";
 import { readNodeClaim } from "./objectivePlan.ts";
-import { type ObjectiveApprovalSaveOutcome, objectiveApprovalSave } from "./objectiveSave.ts";
+import {
+  OBJECTIVE_SAVE_STAGE,
+  type ObjectiveApprovalSaveOutcome,
+  objectiveApprovalSave,
+} from "./objectiveSave.ts";
 import { writePlanDraft } from "./planDraft.ts";
 import { type ApprovalSaveOutcome, approvalSave, resolvePlanSource } from "./planSave.ts";
 
@@ -410,9 +419,62 @@ export function implementHereResult(
   };
 }
 
+// ------------------------------------------------------ the plannotator Direct-Edits apply
+
+/**
+ * The shared plannotator APPROVE mechanical-apply path (contracts.md §8.23): inspect an
+ * APPROVED outcome's feedback for a `# Direct Edits` section and mechanically apply the
+ * reviewer's diff to the exact bytes reviewed (`basePlan`), writing the patched bytes back to
+ * the draft (reviewed bytes == artifact bytes == saved bytes). Consumed by `executePlanReview`'s
+ * plannotator arm AND the `/plan-review-browser` door — one apply path, byte-identical
+ * semantics:
+ *
+ * - only an `approved` outcome WITH feedback is inspected (anything else passes through
+ *   verbatim);
+ * - a clean extract + apply + write-back swaps `reviewedPlan` to the patched bytes, sets
+ *   `edited: true`, and strips the applied section from the returned outcome's feedback (only
+ *   the annotation remainder survives — the applied diff must never render as "apply these
+ *   exact changes" guidance);
+ * - a seen-but-unhonorable heading (or a failed apply / write-back) sets
+ *   `directEditsFailed: true` with the plan left verbatim (the caller renders the loud warning;
+ *   the diff stays in the surfaced feedback for a manual follow-up).
+ */
+export function applyPlannotatorDirectEdits(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+  basePlan: string,
+): {
+  outcome: Extract<ReviewOutcome, { status: "completed" }>;
+  reviewedPlan: string;
+  edited: boolean;
+  directEditsFailed: boolean;
+} {
+  if (!outcome.approved || outcome.feedback === undefined) {
+    return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: false };
+  }
+  const section = extractDirectEdits(outcome.feedback);
+  if (section !== null) {
+    const patched = applyUnifiedDiff(basePlan, section.diff);
+    if (patched !== null && writePlanDraft(pi, ctx, patched).details.ok) {
+      return {
+        outcome: { ...outcome, feedback: section.remainder },
+        reviewedPlan: patched,
+        edited: true,
+        directEditsFailed: false,
+      };
+    }
+    return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: true };
+  }
+  if (hasDirectEditsHeading(outcome.feedback)) {
+    return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: true };
+  }
+  return { outcome, reviewedPlan: basePlan, edited: false, directEditsFailed: false };
+}
+
 // ----------------------------------------------------------------- the first-party review core
 
-/** The minimal structural `ctx.ui` subset the first-party review needs (the askUser.ts recipe). */
+/** The minimal structural `ctx.ui` subset the first-party review needs (the ciExecutor.ts pure-core + injected-fakes recipe). */
 export interface PlanReviewUI {
   editor(title: string, prefill?: string): Promise<string | undefined>;
   select(
@@ -444,7 +506,7 @@ const REVIEW_EDITOR_TITLE =
 const DENY_FEEDBACK_TITLE = "Deny feedback (optional) — Enter to send";
 
 /**
- * The first-party in-TUI review core, pure over injected seams (the askUser.ts recipe) — fully
+ * The first-party in-TUI review core, pure over injected seams (the ciExecutor.ts pure-core + injected-fakes recipe) — fully
  * offline-testable. Flow: (1) display the plan in the editor dialog (Esc = dismissed; the human
  * may edit, incl. via Ctrl+G/$EDITOR); (2) a non-blank edit differing from the displayed plan is
  * written back to the draft BEFORE the verdict (reviewed bytes == artifact bytes == saved bytes;
@@ -721,7 +783,12 @@ export function approvedGistSaveResult(
  * run VIEW-ONLY (edits are never written back; deny+feedback is the change channel); the
  * implement-here verdict is never offered (a gist is not implementable — it has no strategy).
  * An APPROVED outcome wires into the `gistApprovalSave` seam (re-read the artifact → `saveGist`
- * → D1a gate exit → terminating); every other outcome maps via `gistReviewOutcomeResult`.
+ * → D1a gate exit → terminating); every other outcome maps via `gistReviewOutcomeResult`. ONE
+ * carve-out (plannotator only, mirroring the objective arm): an approval whose feedback opens a
+ * Direct Edits section SKIPS the save — rendered edits cannot be folded back into the
+ * structured draft mechanically — and returns a NON-terminating revise round with the gate
+ * untouched (fold each hunk into the matching `gist_draft` field, re-review to confirm); perk
+ * never saves a gist the reviewer explicitly edited away from.
  */
 export async function executeGistReview(
   pi: ExtensionAPI,
@@ -762,6 +829,42 @@ export async function executeGistReview(
   let outcome: ReviewOutcome;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(rendered, sig);
+    // APPROVE + Direct Edits (browser edits of the RENDERED markdown), checked BEFORE the
+    // approved-save routing (the approved-first discipline; mirrors the objective arm): the
+    // save seam re-reads the STRUCTURED artifact, so rendered edits cannot be folded back
+    // without model judgment. Skip the save, keep the gate read-only, and route ONE revise
+    // round: the model folds each hunk into the matching `gist_draft` field, then re-reviews
+    // to confirm. The heading check suffices (extraction success is irrelevant here — the diff
+    // goes to the model verbatim either way).
+    if (
+      outcome.status === "completed" &&
+      outcome.approved &&
+      outcome.feedback !== undefined &&
+      hasDirectEditsHeading(outcome.feedback)
+    ) {
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "gist APPROVED with direct browser edits — these cannot be auto-applied to the " +
+              "structured draft, so nothing was saved. Fold each Direct Edits hunk below into " +
+              "the matching gist_draft field (a `# <title>` heading hunk → title, a `Scope:` " +
+              "line hunk → scope, prose hunks → prose), then call plan_review again to " +
+              `confirm.\n\nReviewer feedback:\n${outcome.feedback}`,
+          },
+        ],
+        details: {
+          ok: true,
+          status: "revise",
+          reason: "direct_edits",
+          approved: true,
+          feedback: outcome.feedback,
+          reviewId: outcome.reviewId,
+          subject: "gist",
+        },
+      };
+    }
   } else {
     const fp = await runFirstPartyReview({
       ui: ctx.ui,
@@ -790,8 +893,9 @@ export async function executeGistReview(
 /**
  * The `plan_review` execute core, extracted pure-over-its-seams (the bridge, the gating, the
  * ctx) so the resolution + dispatch + approved-save paths are unit-testable offline. Arm order:
- * param decode → the objective-author arm (`executeObjectiveReview` — the rendered objective
- * draft is the review subject there) → headless skip → file-first resolution → backend
+ * param decode → the objective arm (`executeObjectiveReview` — the rendered objective draft is
+ * the review subject in BOTH objective-authoring stages) → headless skip → file-first
+ * resolution → backend
  * dispatch (plannotator-selected → the event-bus bridge; ANY other selection → the first-party
  * in-TUI editor review) → approved → `approvalSave`.
  */
@@ -825,11 +929,14 @@ export async function executePlanReview(
       },
     };
   }
-  // 1. Objective-author session → the objective review arm: the rendered
-  //    objective draft is the sole review source; a well-typed `plan` param is ignored here.
-  //    A gist-author session likewise routes to the gist arm (the rendered gist draft).
+  // 1. An objective-authoring session (objective-author OR objective-save — both stages'
+  //    working draft is the objective draft, and neither carries `plan_draft`) → the objective
+  //    review arm: the rendered objective draft is the sole review source; a well-typed `plan`
+  //    param is ignored here — the plan-arm fallthrough could otherwise review/save an
+  //    unrelated plan param from an objective session. A gist-author session likewise routes to
+  //    the gist arm (the rendered gist draft).
   const launchedStage = rebuildWorkflowState(branchOf(ctx)).stage;
-  if (launchedStage === OBJECTIVE_AUTHOR_STAGE) {
+  if (launchedStage === OBJECTIVE_AUTHOR_STAGE || launchedStage === OBJECTIVE_SAVE_STAGE) {
     return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
   }
   if (launchedStage === GIST_AUTHOR_STAGE) {
@@ -869,29 +976,17 @@ export async function executePlanReview(
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(src.plan, sig);
     // APPROVE + Direct Edits (browser plan edits, contracts.md §8.23): mechanically apply the
-    // reviewer's diff to the exact bytes reviewed, write it back to the draft (reviewed bytes ==
-    // artifact bytes == saved bytes — the first-party pre-verdict write-back, replayed here
-    // post-verdict because the bridge only reports the diff), and save the EDITED bytes. Every
-    // rung fails open to the verbatim path: no section → untouched; a heading that cannot be
-    // parsed / applied / written back → verbatim save + a loud warning (never save bytes the
-    // artifact doesn't carry). DENY stays model-mediated — the feedback (diff included) passes
-    // through for the plan_draft rewrite.
-    if (outcome.status === "completed" && outcome.approved && outcome.feedback !== undefined) {
-      const section = extractDirectEdits(outcome.feedback);
-      if (section !== null) {
-        const patched = applyUnifiedDiff(src.plan, section.diff);
-        if (patched !== null && writePlanDraft(pi, ctx, patched).details.ok) {
-          reviewedPlan = patched;
-          edited = true;
-          // The applied diff must NOT survive into the result as "apply these exact changes"
-          // guidance — only the annotation remainder (when any) stays reviewer feedback.
-          outcome = { ...outcome, feedback: section.remainder };
-        } else {
-          directEditsFailed = true;
-        }
-      } else if (hasDirectEditsHeading(outcome.feedback)) {
-        directEditsFailed = true;
-      }
+    // reviewer's diff via the shared helper (the first-party pre-verdict write-back, replayed
+    // here post-verdict because the bridge only reports the diff), and save the EDITED bytes.
+    // Every rung fails open to the verbatim path (never save bytes the artifact doesn't carry).
+    // DENY stays model-mediated — the feedback (diff included) passes through for the
+    // plan_draft rewrite.
+    if (outcome.status === "completed") {
+      const applied = applyPlannotatorDirectEdits(pi, ctx, outcome, src.plan);
+      outcome = applied.outcome;
+      reviewedPlan = applied.reviewedPlan;
+      edited = applied.edited;
+      directEditsFailed = applied.directEditsFailed;
     }
   } else {
     // The 4th verdict (implement-here, the no-save exit) is offered UNLESS this is an

package/extension/factories/planTitle.ts

@@ -92,16 +92,35 @@ export async function generatePlanTitle(
 ): Promise<string | null> {
   if (!llmTitlesEnabled()) return null;
 
-  let auth: Awaited<ReturnType<typeof resolveModelAuth>>;
-  try {
-    auth = await resolveModelAuth(ctx);
-  } catch {
-    return null;
+  const model = ctx.model;
+  if (!model) return null; // silent: no model configured (fail-safe).
+
+  // Primary path (pi ≥ 0.84): registry dispatch — pi owns final request assembly (resolved auth,
+  // nullable headers, credential-resolved baseUrl, provider env). Feature-detected: the method is
+  // absent on older hosts, where the widened resolveModelAuth fallback keeps the old shape.
+  const registry = ctx.modelRegistry;
+  const registryComplete = registry.complete;
+  let authOptions: Pick<
+    Parameters<typeof completeStructured>[0],
+    "dispatch" | "apiKey" | "headers" | "env"
+  >;
+  if (typeof registryComplete === "function") {
+    authOptions = {
+      dispatch: (m, context, options) => registryComplete.call(registry, m, context, options),
+    };
+  } else {
+    let auth: Awaited<ReturnType<typeof resolveModelAuth>>;
+    try {
+      auth = await resolveModelAuth(ctx);
+    } catch {
+      return null;
+    }
+    if (!auth.ok) return null; // silent: no auth configured (fail-safe).
+    authOptions = { apiKey: auth.apiKey, headers: auth.headers, env: auth.env };
   }
-  if (!auth.ok) return null; // silent: no model / no auth configured (fail-safe).
 
   const outcome = await completeStructured({
-    model: auth.model,
+    model,
     schema: PlanTitleSchema,
     toolName: "set_plan_title",
     toolDescription: "Provide the chosen title and category for the plan.",
@@ -110,8 +129,7 @@ export async function generatePlanTitle(
       "Read this implementation plan and choose a title and category. The title must be a concise, " +
       "imperative phrase, at most ~70 characters, with no trailing period and no markdown.",
     input: planMarkdown.slice(0, TITLE_INPUT_CHAR_CAP),
-    apiKey: auth.apiKey,
-    headers: auth.headers,
+    ...authOptions,
     signal,
   });
   if (!outcome.ok || !outcome.value) {

package/extension/hunkFeedback/inbox.ts

@@ -0,0 +1,389 @@
+// The hunk watch feedback inbox (contracts.md §8.58): the single-flight delivery machine that
+// drains the worktree outbox into the one eligible implement session.
+//
+//   idle → dispatching → awaiting-observation → acknowledged → idle
+//                                 └→ backoff → dispatching
+//
+// Exactly ONE unacknowledged batch exists between injection and acknowledgement; while it awaits
+// observation no new batch is injected — triggers (watch events, poll ticks, overflow) only mark
+// the inbox dirty. Acknowledgement requires transcript OBSERVATION (`transport.isInjected`), not
+// call-return: Pi's `sendUserMessage` is a void wrapper over in-memory queues an abort discards.
+// Backoff resets ONLY on observation, so persistent asynchronous rejection backs off
+// exponentially instead of retrying every poll tick — and unconfirmed messages can never
+// accumulate (one in flight, ever). Duplicates possible, silent loss not.
+//
+// Failure containment: every background callback is wrapped — nothing ever escapes into the
+// host session. Watcher failure degrades permanently to poll-only (polling is the correctness
+// path); a failed lease verification closes the inbox fail-closed (misdelivery is never the
+// fallback). Diagnostics route through `deps.report`, never into the model conversation.
+//
+// All effects arrive through `deps` (clock, timers, watch factory, report sink) — deterministic
+// under test, no hidden globals.
+
+import {
+  hunkConsumerLockDir,
+  hunkDeliveredPath,
+  hunkOutboxPath,
+  hunkWatchDir,
+} from "../substrate/cache.ts";
+import { lsFiles } from "../substrate/git.ts";
+import {
+  acquireLease,
+  appendAcks,
+  type DeliveryAck,
+  type FeedbackRecord,
+  HEARTBEAT_MS,
+  readDeliveredIds,
+  readOutbox,
+  releaseLease,
+  renewHeartbeat,
+  sweepQuarantine,
+  verifyLease,
+} from "./store.ts";
+
+// Implementation constants (§8.58) — code constants, deliberately not config.
+export const DEBOUNCE_MS = 500;
+export const POLL_MS = 10_000;
+export const BATCH_MAX_RECORDS = 10;
+export const BATCH_MAX_BYTES = 49_152;
+export const BACKOFF_BASE_MS = 1_000;
+export const BACKOFF_CAP_MS = 60_000;
+/** An in-flight batch is only demotable once it has had ≥ one poll interval to land. */
+export const IN_FLIGHT_MIN_AGE_MS = POLL_MS;
+
+export interface ConsumerIdentity {
+  cwd: string;
+  runId: string;
+  piSessionId: string;
+  /** The worktree plan-ref's `pr_id` — records for any other plan are held, never delivered. */
+  planId: string;
+}
+
+export interface FeedbackTransport {
+  /** Render + sendUserMessage (idle vs steer). A synchronous throw = refusal (records stay pending). */
+  inject(batch: readonly FeedbackRecord[]): void;
+  /** True when the batch's injected message is observed as a persisted user-message entry on the branch. */
+  isInjected(batch: readonly FeedbackRecord[]): boolean;
+  isIdle(): boolean;
+}
+
+export interface FeedbackInboxHandle {
+  close(): void;
+}
+
+/** The lease was foreign and fresh — this session stays passive (and says so, once). */
+export interface PassiveClaim {
+  passive: true;
+  reason: string;
+}
+
+export interface InboxTimers {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+  setInterval(fn: () => void, ms: number): unknown;
+  clearInterval(handle: unknown): void;
+}
+
+export interface InboxWatcher {
+  close(): void;
+}
+
+/** An `fs.watch` factory seam; construction may throw (degrades to poll-only). */
+export type WatchFactory = (
+  dir: string,
+  onChange: () => void,
+  onError: (error: unknown) => void,
+) => InboxWatcher;
+
+export interface InboxDeps {
+  now(): number;
+  timers: InboxTimers;
+  watch: WatchFactory;
+  report(severity: "info" | "warning" | "error", message: string): void;
+}
+
+export interface HunkFeedbackInbox {
+  open(
+    identity: ConsumerIdentity,
+    transport: FeedbackTransport,
+  ): FeedbackInboxHandle | PassiveClaim;
+}
+
+export function createHunkFeedbackInbox(deps: InboxDeps): HunkFeedbackInbox {
+  return {
+    open(identity, transport) {
+      const lockDir = hunkConsumerLockDir(identity.cwd);
+      const outboxPath = hunkOutboxPath(identity.cwd);
+      const deliveredPath = hunkDeliveredPath(identity.cwd);
+      const watchDir = hunkWatchDir(identity.cwd);
+      const { now, timers, report } = deps;
+
+      // Provenance fence (§8.58): the family is DISPOSABLE LOCAL state — a git-TRACKED entry
+      // under it means checkout-supplied bytes (a force-added outbox/symlink) are posing as
+      // live watch feedback. Refuse to open, loudly; nothing under the family is read.
+      const tracked = lsFiles(identity.cwd, watchDir);
+      if (tracked.length > 0) {
+        const reason =
+          "tracked file(s) under .perk/workflow/hunk-watch — repository-supplied feedback is " +
+          `refused (untrack them to re-enable the bridge): ${tracked.join(", ")}`;
+        report("error", reason);
+        return { passive: true, reason };
+      }
+
+      // Quarantine sweep first (leftovers from a crashed reclaimer are harmless but dirty),
+      // then the lease: a fresh foreign holder means this session never inspects the stream.
+      for (const warning of sweepQuarantine(lockDir)) report("warning", warning);
+      const lease = acquireLease(
+        lockDir,
+        {
+          runId: identity.runId,
+          piSessionId: identity.piSessionId,
+        },
+        now,
+      );
+      if (!lease.owned) return { passive: true, reason: lease.reason };
+      const token = lease.token;
+
+      // Accepted-but-unacknowledged suppression lives here too: an id whose ack append failed
+      // stays in this set for the rest of the session (may redeliver in a later one — §8.58).
+      const deliveredRead = readDeliveredIds(deliveredPath);
+      const delivered = deliveredRead.ids;
+
+      type Phase = "idle" | "awaiting" | "backoff";
+      let phase: Phase = "idle";
+      let dirty = false;
+      let closed = false;
+      let inFlight: { batch: readonly FeedbackRecord[]; injectedAt: number } | null = null;
+      /** The CURRENT backoff delay; 0 = no failures since the last observation (the only reset). */
+      let backoffMs = 0;
+      let backoffTimer: unknown = null;
+      let debounceTimer: unknown = null;
+      let pollHandle: unknown = null;
+      let heartbeatHandle: unknown = null;
+      let watcher: InboxWatcher | null = null;
+      const reportedOnce = new Set<string>();
+      const heldPlanIds = new Set<string>();
+
+      const reportOnce = (severity: "warning" | "error", message: string): void => {
+        if (reportedOnce.has(message)) return;
+        reportedOnce.add(message);
+        report(severity, message);
+      };
+
+      const close = (): void => {
+        if (closed) return;
+        closed = true;
+        if (debounceTimer !== null) timers.clearTimeout(debounceTimer);
+        if (backoffTimer !== null) timers.clearTimeout(backoffTimer);
+        if (pollHandle !== null) timers.clearInterval(pollHandle);
+        if (heartbeatHandle !== null) timers.clearInterval(heartbeatHandle);
+        try {
+          watcher?.close();
+        } catch {
+          // disposal is best-effort
+        }
+        watcher = null;
+        inFlight = null;
+        releaseLease(lockDir, token); // removes only on token match
+      };
+
+      /** Fail-closed shutdown: the lease is no longer provably ours — stop, loudly, once. */
+      const closeFailClosed = (): void => {
+        reportOnce(
+          "error",
+          "feedback lease verification failed — closing the hunk feedback inbox (records stay queued for the next eligible session)",
+        );
+        close();
+      };
+
+      const enterBackoff = (): void => {
+        // Never resets on dispatch: consecutive failures double toward the cap.
+        backoffMs = backoffMs === 0 ? BACKOFF_BASE_MS : Math.min(backoffMs * 2, BACKOFF_CAP_MS);
+        phase = "backoff";
+        dirty = true;
+        backoffTimer = timers.setTimeout(() => {
+          backoffTimer = null;
+          if (closed) return;
+          phase = "idle";
+          guard(dispatch);
+        }, backoffMs);
+      };
+
+      const acknowledge = (batch: readonly FeedbackRecord[]): void => {
+        const at = new Date(now()).toISOString();
+        const acks: DeliveryAck[] = batch.map((record) => ({
+          schema: 1,
+          feedback_id: record.feedback_id,
+          delivered_at: at,
+          run_id: identity.runId,
+          pi_session_id: identity.piSessionId,
+        }));
+        try {
+          appendAcks(identity.cwd, acks);
+        } catch (error) {
+          // The message IS on the transcript — suppress same-session redelivery in memory; a
+          // later session may redeliver (at-least-once, stated plainly).
+          report(
+            "warning",
+            `could not append feedback acknowledgements (${error}) — delivery stands; the records may redeliver in a later session`,
+          );
+        }
+        for (const record of batch) delivered.add(record.feedback_id);
+        backoffMs = 0; // the ONLY reset site: transcript observation
+        inFlight = null;
+        phase = "idle";
+        if (dirty) dispatch();
+      };
+
+      /** One dispatch pass — only ever entered from `idle`. */
+      const dispatch = (): void => {
+        if (closed || phase !== "idle") return;
+        dirty = false;
+        const read = readOutbox(outboxPath);
+        for (const warning of read.warnings) reportOnce("warning", warning);
+        const pending: FeedbackRecord[] = [];
+        for (const record of read.records) {
+          if (delivered.has(record.feedback_id)) continue;
+          if (record.plan_id !== identity.planId) {
+            if (!heldPlanIds.has(record.feedback_id)) {
+              heldPlanIds.add(record.feedback_id);
+              report(
+                "warning",
+                `holding feedback ${record.feedback_id} addressed to plan ${record.plan_id} — this session implements plan ${identity.planId}`,
+              );
+            }
+            continue; // held: never delivered, never acked
+          }
+          pending.push(record);
+        }
+        if (pending.length === 0) return;
+
+        // Bounded batch, append order retained; the remainder re-marks dirty.
+        const batch: FeedbackRecord[] = [];
+        let bytes = 0;
+        for (const record of pending) {
+          const size = Buffer.byteLength(record.body, "utf8");
+          if (
+            batch.length > 0 &&
+            (batch.length >= BATCH_MAX_RECORDS || bytes + size > BATCH_MAX_BYTES)
+          ) {
+            break;
+          }
+          batch.push(record);
+          bytes += size;
+        }
+        if (batch.length < pending.length) dirty = true;
+
+        // The delivery fence: verify the lease immediately before every injection.
+        if (!verifyLease(lockDir, token)) {
+          closeFailClosed();
+          return;
+        }
+        if (transport.isInjected(batch)) {
+          // A prior injection survives on this branch — acknowledge without re-injecting.
+          acknowledge(batch);
+          return;
+        }
+        try {
+          transport.inject(batch);
+        } catch (error) {
+          report("warning", `feedback injection refused synchronously (${error}) — backing off`);
+          enterBackoff();
+          return;
+        }
+        inFlight = { batch, injectedAt: now() };
+        phase = "awaiting";
+      };
+
+      /** Wrap a background callback: report, never throw into the host session. */
+      const guard = (fn: () => void): void => {
+        try {
+          fn();
+        } catch (error) {
+          reportOnce("error", `hunk feedback inbox error: ${error}`);
+        }
+      };
+
+      const pollTick = (): void => {
+        if (closed) return;
+        if (phase === "awaiting" && inFlight !== null) {
+          const flight = inFlight;
+          if (transport.isInjected(flight.batch)) {
+            acknowledge(flight.batch);
+            return;
+          }
+          if (transport.isIdle() && now() - flight.injectedAt >= IN_FLIGHT_MIN_AGE_MS) {
+            // The session went idle again without the message landing (an abort-discarded
+            // steer queue or a failed turn) — demote: the records return to pending (they are
+            // still in the outbox and not delivered) and backoff owns the next dispatch.
+            inFlight = null;
+            enterBackoff();
+          }
+          return;
+        }
+        if (phase === "idle") {
+          dispatch(); // polling is the correctness path — the watcher may be dead
+          return;
+        }
+        dirty = true; // backoff owns the next dispatch; triggers only mark dirty
+      };
+
+      const onWatchEvent = (): void => {
+        if (closed) return;
+        dirty = true;
+        if (debounceTimer !== null) timers.clearTimeout(debounceTimer);
+        debounceTimer = timers.setTimeout(() => {
+          debounceTimer = null;
+          if (closed) return;
+          if (phase === "idle") guard(dispatch);
+        }, DEBOUNCE_MS);
+      };
+
+      const heartbeatTick = (): void => {
+        if (closed) return;
+        try {
+          renewHeartbeat(lockDir, token, now);
+        } catch (error) {
+          // The pre-injection verifyLease remains the delivery fence — report, keep going.
+          reportOnce("warning", `feedback lease heartbeat failed: ${error}`);
+        }
+      };
+
+      for (const warning of deliveredRead.warnings) reportOnce("warning", warning);
+
+      // The immediate initial drain, then low-latency watch + poll fallback + heartbeat.
+      guard(dispatch);
+      if (closed) return { close }; // the drain closed fail-closed — install nothing
+      try {
+        watcher = deps.watch(
+          watchDir,
+          () => guard(onWatchEvent),
+          (error) => {
+            guard(() => {
+              reportOnce(
+                "warning",
+                `hunk feedback watcher failed (${error}) — continuing on the polling fallback`,
+              );
+              try {
+                watcher?.close();
+              } catch {
+                // best-effort
+              }
+              watcher = null;
+            });
+          },
+        );
+      } catch (error) {
+        reportOnce(
+          "warning",
+          `could not watch the feedback outbox (${error}) — continuing on the polling fallback`,
+        );
+        watcher = null;
+      }
+      pollHandle = timers.setInterval(() => guard(pollTick), POLL_MS);
+      heartbeatHandle = timers.setInterval(() => guard(heartbeatTick), HEARTBEAT_MS);
+
+      return { close };
+    },
+  };
+}