@coreplane/switchboard 1.250.0 → 1.252.0

package/dist/assets/src/core/coordinator/driver.ts

@@ -34,6 +34,7 @@
 // the shim Worker imports this by relative path.
 
 import { DEFAULT_GRANT, GRANT_RENEWALS_MAX, type Grant, type GrantSource } from "../budgets.js";
+import { DEFAULT_VERBOSITY, isVerbosity, type Verbosity } from "../verbosity.js";
 import {
   applyReturn,
   cursorFinished,
@@ -52,6 +53,7 @@ import {
   type AddressSeveritySource,
   type PlanGraph,
   type PlanUnitNode,
+  type RoundChecks,
   type ShipCaps,
   type StepReturn,
   type UnitEnding,
@@ -59,7 +61,14 @@ import {
   stepPrefixOf,
   type UnitSession,
 } from "../ship/coordinator.js";
-import { checksSettledEventType, isCoordinatorUnit, runFinishedEventType, type CoordinatorUnit } from "./contract.js";
+import {
+  checksSettledEventType,
+  childInterruptedEventType,
+  childResumedEventType,
+  isCoordinatorUnit,
+  runFinishedEventType,
+  type CoordinatorUnit,
+} from "./contract.js";
 
 const MIN = 60_000;
 
@@ -83,7 +92,17 @@ export interface StepRunner {
 }
 
 export type CoordinatorStepRoute =
-  "plan" | "unit-start" | "branch" | "spawn" | "read-record" | "pr-check" | "round" | "unit-end" | "merge" | "finish";
+  | "plan"
+  | "unit-start"
+  | "branch"
+  | "spawn"
+  | "read-record"
+  | "pr-check"
+  | "round"
+  | "unit-end"
+  | "checks"
+  | "merge"
+  | "finish";
 
 /** What a step stores: the bot's reply as the wire carried it — its status and
  *  its text, read the same way on replay. Two numbers and a string, so the
@@ -170,8 +189,12 @@ interface PlanFacts {
   /** The grant beside them (decision 0046): what a renewal could spend, and which layer granted it. */
   grant: Grant;
   grantSource: GrantSource;
+  /** The request's verbosity as the plan route answers it (routing-and-config item 28): what the unit threads hear. */
+  verbosity: Verbosity;
   /** The instance's mark as the plan route answers it: a generated one-unit plan (a `plan` with no `path`). */
   generated: boolean;
+  /** The runs page base the bot answered: the report links a child's write-up to its run page with it. */
+  runPageBase?: string;
   repo: string;
   base: string;
   caps: ShipCaps;
@@ -216,7 +239,9 @@ function readPlan(a: BotAnswer): PlanFacts {
     grant: readGrant(b.grant),
     grantSource:
       b.grantSource === "run" || b.grantSource === "user" || b.grantSource === "channel" ? b.grantSource : "org",
+    verbosity: isVerbosity(b.verbosity) ? b.verbosity : DEFAULT_VERBOSITY,
     generated: b.generated === true,
+    ...(typeof b.runPageBase === "string" && b.runPageBase.length > 0 ? { runPageBase: b.runPageBase } : {}),
     repo: b.repo,
     base: b.base,
     caps: { maxRounds: b.caps.maxRounds, maxMinutes: b.caps.maxMinutes },
@@ -318,7 +343,7 @@ function isCommitChecks(v: unknown): v is { total: number; pending: string[]; fa
 function prCheckReturn(step: string, a: BotAnswer): StepReturn {
   const { ok, state, prNumber, url, headSha, sha, mergedAt, at } = a.body;
   if (ok === true && state === "none") {
-    const { unrecovered, aheadOfBase } = a.body;
+    const { unrecovered, aheadOfBase, prClosed } = a.body;
     return {
       type: "pr-check",
       step,
@@ -328,6 +353,9 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
         // The branch's commits over the base, when the bot could read them
         // (agent-ship item 12): zero is the `already_landed` ending's fact.
         ...(typeof aheadOfBase === "number" ? { aheadOfBase } : {}),
+        // The followed pull request verified closed unmerged (issue 1799):
+        // the machine must not brief a review round on it.
+        ...(prClosed === true ? { prClosed: true } : {}),
       },
       at,
     };
@@ -343,6 +371,12 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
         ...(typeof headSha === "string" ? { headSha } : {}),
         ...(typeof a.body.autoMergeEnabled === "boolean" ? { autoMergeEnabled: a.body.autoMergeEnabled } : {}),
         ...(isCommitChecks(a.body.checks) ? { checks: a.body.checks } : {}),
+        // The ready-state facts beside the checks (agent-ship item 9): the
+        // pull request's mergeable state and its self-declared fix-up commits.
+        ...(typeof a.body.mergeableState === "string" ? { mergeableState: a.body.mergeableState } : {}),
+        ...(Array.isArray(a.body.fixupCommits) && a.body.fixupCommits.every((s: unknown) => typeof s === "string")
+          ? { fixupCommits: a.body.fixupCommits as string[] }
+          : {}),
       },
       at,
     };
@@ -360,6 +394,31 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
   throw new UnreadableAnswer("pr-check", a, "state");
 }
 
+/** The round's checks read as the bot answered it (record 0055): the runs at
+ *  the reviewed head, or none when GitHub could not be read — the machine
+ *  treats an absent read as pending and asks again at the chunk's end. A retry
+ *  ask's answer carries `retried` instead: whether the re-run was dispatched,
+ *  so the machine never waits on a head an undispatched re-run left unchanged. */
+function checksReturn(step: string, a: BotAnswer): StepReturn {
+  const { ok, checks, retried, at } = a.body;
+  if (ok !== true) throw new UnreadableAnswer("checks", a, "ok");
+  return {
+    type: "checks",
+    step,
+    ...(isRoundChecks(checks) ? { checks } : {}),
+    ...(typeof retried === "boolean" ? { retried } : {}),
+    at,
+  };
+}
+
+const isRoundChecks = (v: unknown): v is RoundChecks =>
+  isRecord(v) &&
+  typeof v.total === "number" &&
+  Array.isArray(v.pending) &&
+  v.pending.every((n: unknown) => typeof n === "string") &&
+  Array.isArray(v.failed) &&
+  v.failed.every((f: unknown) => isRecord(f) && typeof f.name === "string" && typeof f.conclusion === "string");
+
 function mergeReturn(step: string, a: BotAnswer): StepReturn {
   const { ok, outcome, by, sha, mergedAt, reason, at } = a.body;
   // The door found the pull request already merged after the approval: the
@@ -397,17 +456,58 @@ function answerOf(route: CoordinatorStepRoute, reply: BotReply): BotAnswer {
   return read.answer;
 }
 
-/** A wait's outcome: the event, or anything else — the machine confirms either by `read-record`. */
+/** A wait's outcome: the event, or anything else — the machine confirms either by `read-record`.
+ *
+ *  Three waits under one chunk (run-history item 47a): the child's finish
+ *  (`run-finished-<runId>`), its deploy-roll interruption
+ *  (`child-interrupted-<runId>`, the reattach path's word that the child
+ *  closed `interrupted` — settled as the finish is, so the round ends at once
+ *  with the child's own reason once `read-record` confirms it) and its resume
+ *  (`child-resumed-<runId>`, the same run carrying on after a roll — consumed
+ *  and re-armed, never a settlement: a resumed child keeps the wait). The
+ *  chunk times out only once the finish AND the interruption waits both have;
+ *  a resumed wait's own timeout decides nothing. */
 async function waitForRun(
   step: StepRunner,
   action: Extract<CoordinatorAction, { type: "wait" }>,
 ): Promise<"event" | "timeout"> {
-  try {
-    await step.waitForEvent(action.step, { type: runFinishedEventType(action.runId), timeout: action.timeoutMs });
-    return "event";
-  } catch {
-    return "timeout";
-  }
+  return await new Promise((resolve) => {
+    let settled = false;
+    let timeouts = 0;
+    const settle = (outcome: "event" | "timeout") => {
+      settled = true;
+      resolve(outcome);
+    };
+    const settling = (name: string, type: string) =>
+      step.waitForEvent(name, { type, timeout: action.timeoutMs }).then(
+        () => settle("event"),
+        () => {
+          timeouts += 1;
+          // Deferred a microtask so a resume that lands with the chunk's own
+          // end is still consumed (re-armed) before the timeout settles.
+          if (timeouts === 2) queueMicrotask(() => settle("timeout"));
+        },
+      );
+    void settling(action.step, runFinishedEventType(action.runId));
+    void settling(`${action.step}/interrupted`, childInterruptedEventType(action.runId));
+    // Each resumed event re-arms under the next durable name, so a second roll
+    // in the same chunk is still heard; a timeout here ends nothing, and a
+    // settled wait arms no further step.
+    const armResumed = (n: number): void => {
+      void step
+        .waitForEvent(n === 1 ? `${action.step}/resumed` : `${action.step}/resumed/${n}`, {
+          type: childResumedEventType(action.runId),
+          timeout: action.timeoutMs,
+        })
+        .then(
+          () => {
+            if (!settled) armResumed(n + 1);
+          },
+          () => {},
+        );
+    };
+    armResumed(1);
+  });
 }
 
 async function perform(
@@ -453,12 +553,19 @@ async function perform(
     case "pr-check":
       // `recover` rides only after a dead coding child: the bot opens the pull
       // request from the pushed branch itself instead of answering `none`.
+      // `pr` is the machine's adopted pull request (issue 1799): the bot
+      // follows it when nothing heads the unit's branch and answers its live
+      // state instead of `none` over a minutes-old record fact.
       return prCheckReturn(
         action.step,
         answerOf(
           "pr-check",
           await step.do(action.step, STEP_CONFIG, () =>
-            call(bot, "pr-check", { ...tag, ...(action.recover !== undefined ? { recover: action.recover } : {}) }),
+            call(bot, "pr-check", {
+              ...tag,
+              ...(action.recover !== undefined ? { recover: action.recover } : {}),
+              ...(action.pr !== undefined ? { pr: action.pr } : {}),
+            }),
           ),
         ),
       );
@@ -481,6 +588,24 @@ async function perform(
       }
       return { type: "wait-checks", step: action.step, outcome };
     }
+    case "checks":
+      // The round's checks step (record 0055): the bot reads the check runs at
+      // the reviewed head with the merge door's own reading — or, on a retry
+      // ask, re-runs the named failed checks' jobs first.
+      return checksReturn(
+        action.step,
+        answerOf(
+          "checks",
+          await step.do(action.step, STEP_CONFIG, () =>
+            call(bot, "checks", {
+              ...tag,
+              prNumber: action.prNumber,
+              headSha: action.headSha,
+              ...(action.retry !== undefined ? { retry: action.retry } : {}),
+            }),
+          ),
+        ),
+      );
     case "merge":
       return mergeReturn(
         action.step,
@@ -536,7 +661,9 @@ async function runUnit(
       addressSeveritySource: plan.addressSeveritySource,
       grant: plan.grant,
       grantSource: plan.grantSource,
+      verbosity: plan.verbosity,
       generated: plan.generated,
+      ...(plan.runPageBase !== undefined ? { runPageBase: plan.runPageBase } : {}),
       ...(resume !== undefined ? { resume } : {}),
       ...(lastPush !== undefined ? { lastPush } : {}),
       ...(session !== undefined ? { session } : {}),
@@ -586,6 +713,11 @@ async function runUnit(
                 // The checks at the approved head (record 0055): the report's
                 // headline is a claim about them, never "merge-ready" over a red one.
                 ...(check.pr.checks !== undefined ? { checks: check.pr.checks } : {}),
+                // The ready state beside them (agent-ship item 9): a conflicting
+                // head, or one carrying an unsquashed fix-up commit, is reported
+                // approved-but-not-merge-ready, never "merge-ready".
+                ...(check.pr.mergeableState !== undefined ? { mergeableState: check.pr.mergeableState } : {}),
+                ...(check.pr.fixupCommits !== undefined ? { fixupCommits: check.pr.fixupCommits } : {}),
               };
           } catch {
             // the report simply omits the fact
@@ -596,7 +728,13 @@ async function runUnit(
         // ending (agent-ship item 14).
         const body = {
           ...tag,
-          ending: { kind: note.ending.kind, report: renderUnitReport(state, endFacts) },
+          // Two copies (routing-and-config item 28): the full report for the
+          // row and the board, and the thread's at the request's verbosity.
+          ending: {
+            kind: note.ending.kind,
+            report: renderUnitReport(state, endFacts),
+            threadReport: renderUnitReport(state, endFacts, state.input.verbosity ?? DEFAULT_VERBOSITY),
+          },
           ...(state.pr !== undefined ? { pr: state.pr } : {}),
           // A review_pending ending names the child's own last push so the next
           // attempt's pre-check can start at the review round (the row's lastPush).

package/dist/assets/src/core/drain.ts

@@ -19,11 +19,61 @@
  *  (docs/reference/specs/run-history.md item 39); this is the wait for the rest. */
 export const DRAIN_DEADLINE_MS = 15 * 60_000;
 
+/** One run holding a drain: the registry-active run's id and why it holds.
+ *  The drain is held by the RUN REGISTRY's live rows, not by the dispatcher's
+ *  in-flight count — the two can disagree (a registry row whose dispatcher-side
+ *  run is gone still holds the drain for its full deadline) — so the lines an
+ *  operator reads name these rows, never the count from the other ledger. */
+export interface HeldRun {
+  id: string;
+  why: string;
+}
+
+/** Why a registry-active run holds the drain: the handoff (run-history item 39)
+ *  did not mark it for the next generation, so this process must wait for it. */
+export const HELD_NOT_HANDED_OFF = "not handed off";
+
+/** One `id (why)` per held run, comma-separated — shared by the drain's hold
+ *  line here and the deploy CLI's still-draining line (src/deploy/liveGate.ts). */
+export function heldRunsText(held: readonly HeldRun[]): string {
+  return held.map((r) => `${r.id} (${r.why})`).join(", ");
+}
+
+/** The drain's hold line (slack-channel.md item 8): what actually holds the
+ *  exit, by run id and reason — printed once the handoff has settled who stays. */
+export function drainHoldLine(held: readonly HeldRun[]): string {
+  return `[drain] holding for ${held.length} registry-active run(s): ${heldRunsText(held)}`;
+}
+
 /** The handoff's own budget (plan D8): after every resumable run is marked
  *  `handoff`, the drain waits this long for pending history writes and
  *  reflections, then exits — the next generation takes the runs. */
 export const HANDOFF_BUDGET_MS = 6_000;
 
+/**
+ * The drain's wait bound, re-read on every poll of the drain loop
+ * (`src/index.ts`). While a run still holds the drain (registry-active, not
+ * handed off) the bound is the full DRAIN_DEADLINE_MS from the signal — the
+ * deadline is the bound for a run that will not end, never the schedule. The
+ * moment the held count reaches zero the bound collapses to HANDOFF_BUDGET_MS
+ * from that instant (never past the full deadline) — the same grace a drain
+ * that started with nothing held gets — so pending reflections and history
+ * writes, including the steady stream a handed-off run still executing here
+ * produces, get seconds to settle, not the deploy's remaining minutes. Once
+ * collapsed the bound never grows back: the socket is closed, so no new run
+ * can arrive to hold the drain again.
+ */
+export function createDrainDeadline(drainStartedAt: number): (now: number, runsHeld: number) => number {
+  const full = drainStartedAt + DRAIN_DEADLINE_MS;
+  let collapsed: number | undefined;
+  return (now, runsHeld) => {
+    if (collapsed !== undefined) return collapsed;
+    if (runsHeld > 0) return full;
+    collapsed = Math.min(full, now + HANDOFF_BUDGET_MS);
+    return collapsed;
+  };
+}
+
 /** Time budgeted for the replacement container to boot and reach Socket Mode
  *  `connected` (image pull + Node start + Bolt handshake), when the catch-up
  *  scan runs. */

package/dist/assets/src/core/memory/engine.ts

@@ -94,6 +94,104 @@ export function planWrite(
   return { action: "insert", record: mint(cand), ...(target ? { supersede: target } : {}) };
 }
 
+// ---- The write gate (docs/reference/specs/memory.md item 13) -----------------
+// Status — the state of one pull request at one moment — and change
+// descriptions — what one change did, which the spec and the diff already say —
+// must never become facts: the prompt has asked for that since the write path
+// shipped, and a rule a model is asked to follow is a rule it follows on
+// average. The gate is therefore code, pure and total, and lives HERE in the
+// shared engine so the bot's write path and the Worker's sweep run the exact
+// same rule. A summary is never gated (episodic by definition).
+
+/** A delivery predicate: words that say a change LANDED — one moment's news,
+ *  never a lesson. Shared by the `delivery` marker and the reference marker's
+ *  same-clause test. The auxiliary may sit up to two words from the participle
+ *  ("is fixed and pushed"). */
+const DELIVERY_PREDICATE =
+  /\b(?:(?:was|were|is|are)\s+(?:\w+\s+){0,2}?(?:pushed|merged|approved)|all\s+green|lgtm|ready\s+for\s+review|awaits?\s+ci|is\s+complete)\b/i;
+
+/** A pull-request / issue / unit reference in subject position: the fact opens
+ *  with the noun and a number, so the reference is what the fact is ABOUT. */
+const REFERENCE_SUBJECT = /^\s*(?:pr|pull\s+request|issue|unit)s?\s*#?\d+\b/i;
+
+/** A reference elsewhere (`#n`, `pull/n`, `issues/n`) rejects only beside a
+ *  delivery predicate in the same clause — a citation inside a lesson ("the
+ *  staged rebuild (issue 170) must budget the swap") is not status. */
+const REFERENCE_IN_CLAUSE = /#\d+|\b(?:pull|issues)\/\d+/i;
+
+/** A commit sha: 7–40 hex chars with at least one digit AND one letter, bounded
+ *  by non-alphanumerics — the letter keeps a timestamp or a plain count out,
+ *  the digit keeps "defaced" and "accede" out. An all-digit or all-letter sha
+ *  is missed and accepted as the cost. */
+const COMMIT_SHA = /(?<![a-z0-9])(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}(?![a-z0-9])/i;
+
+/** A run id (`run` + 8 hex chars) or a branch by its path-like name. */
+const RUN_OR_BRANCH = /\brun\s+[0-9a-f]{8}\b|\bbranch\s+\S*\/\S+/i;
+
+/** `now` + a present-tense verb (one intervening word allowed): what a change
+ *  "now does" is a change description, not a lesson. */
+const NOW_VERB =
+  /\bnow\s+(?:\w+\s+)?(?:documents|preserves|displays|includes|carries|has|is|supports|shows|maps|controls|applies|uses)\b/i;
+
+/** A passive change participle: "was implemented", "has been fixed", … */
+const CHANGE_PARTICIPLE =
+  /\b(?:was|were|has\s+been|have\s+been)\s+(?:implemented|added|updated|fixed|documented|removed|renamed|introduced|extended)\b/i;
+
+/** A plan-unit reference. */
+const PLAN_UNIT = /\bunit\s+u?\d+\b/i;
+
+/** "spec row" / "spec rows": what a spec row documents is the spec's to say. */
+const SPEC_ROW = /\bspec\s+rows?\b/i;
+
+/** The words that make a nearby number a test/check count… */
+const COUNT_NOUNS = new Set(["test", "tests", "checks", "rows"]);
+/** …and the outcome words that make that count status. */
+const COUNT_OUTCOME = /\b(?:pass(?:es|ing|ed)?|green|fail(?:s|ing|ed)?)\b/i;
+
+/** A clause: the unit within which the reference and count markers look for
+ *  their second half. */
+function clausesOf(text: string): string[] {
+  return text.split(/[;.!?\n—]+/);
+}
+
+/** A number within three words of a count noun, with an outcome word in the
+ *  same clause — in either order ("all 12 tests passing", "green across 12
+ *  checks"). */
+function hasCountMarker(clause: string): boolean {
+  if (!COUNT_OUTCOME.test(clause)) return false;
+  const words = clause
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+  return words.some(
+    (w, i) => /^\d+$/.test(w) && words.slice(Math.max(0, i - 3), i + 4).some((neighbour) => COUNT_NOUNS.has(neighbour)),
+  );
+}
+
+/** The status and change-description markers a fact text carries, by name —
+ *  a table of named patterns, each firing independently. A non-empty answer
+ *  rejects the fact (`parseReflection`) and, later, sweeps the stored row; the
+ *  names are safe to log (never the text). Pure and total: never throws, and
+ *  empty text carries no markers (it is rejected upstream as empty). */
+export function rejectionMarkers(text: string): string[] {
+  const clauses = clausesOf(text);
+  const table: Array<[name: string, hit: boolean]> = [
+    [
+      "reference",
+      REFERENCE_SUBJECT.test(text) || clauses.some((c) => REFERENCE_IN_CLAUSE.test(c) && DELIVERY_PREDICATE.test(c)),
+    ],
+    ["sha", COMMIT_SHA.test(text)],
+    ["count", clauses.some(hasCountMarker)],
+    ["delivery", DELIVERY_PREDICATE.test(text)],
+    ["identifier", RUN_OR_BRANCH.test(text)],
+    ["now", NOW_VERB.test(text)],
+    ["changed", CHANGE_PARTICIPLE.test(text)],
+    ["unit", PLAN_UNIT.test(text)],
+    ["spec-row", SPEC_ROW.test(text)],
+  ];
+  return table.filter(([, hit]) => hit).map(([name]) => name);
+}
+
 /** Build the record a store persists for a candidate. Ids are namespaced per
  *  AGENTS.md invariant 4 (`mem:<scopeKey>:<seq>`); keywords default to the
  *  text's tokens so keyword retrieval always has something to hit. */

package/dist/assets/src/core/memory/scorer.ts

@@ -20,10 +20,18 @@ export const DEFAULT_WEIGHTS: ScoreWeights = { keyword: 0.7, recency: 0.3 };
  *  sweeper job (decay lives in the score). */
 export const RECENCY_TAU_MS = 7 * 24 * 60 * 60 * 1000;
 
-/** Default read budget: at most 8 records / ~800 tokens injected, regardless of
- *  store size — context never bloats. */
-export const DEFAULT_MEMORY_LIMIT = 8;
-export const DEFAULT_MEMORY_TOKENS = 800;
+/** Default read budget: at most 32 records / ~3000 tokens injected, regardless
+ *  of store size — context never bloats. Raised from 8/800 with the repository
+ *  window (docs/decisions/0061-…): the window's 24 facts plus the keyword hits
+ *  must fit in one pool under one budget. */
+export const DEFAULT_MEMORY_LIMIT = 32;
+export const DEFAULT_MEMORY_TOKENS = 3000;
+
+/** Default size of the repository window (`memory.repoWindow`): the newest
+ *  facts of the run's bound repository, rendered ahead of the keyword hits.
+ *  `0` disables the window. At ~320 chars per repository fact, 24 render in
+ *  about 2000 tokens — the rest of the budget is the hits'. */
+export const DEFAULT_REPO_WINDOW = 24;
 
 export interface MemoryBudget {
   maxRecords: number;

package/dist/assets/src/core/memory/types.ts

@@ -36,9 +36,11 @@ export interface MemoryRecord {
   supersedes?: string;
   /** `evicted`: dropped by the per-scope cap (least recently used);
    *  `superseded`: replaced by a newer record; `forgotten`: removed by a human
-   *  via `memory forget`. Both are soft deletes — the row stays for
-   *  provenance but is invisible to retrieval, list, and dedup. */
-  status: "active" | "superseded" | "forgotten" | "evicted";
+   *  via `memory forget`; `swept`: retired by `memory sweep` because the text
+   *  carries a status/change-description marker (`rejectionMarkers`). All are
+   *  soft deletes — the row stays for provenance but is invisible to
+   *  retrieval, list, and dedup. */
+  status: "active" | "superseded" | "forgotten" | "evicted" | "swept";
 }
 
 /** What the reflection extractor emits. The store assigns id/timestamps/useCount/
@@ -54,6 +56,45 @@ export interface MemoryCandidate {
   supersedes?: string;
 }
 
+/** What one `write` batch actually did, per candidate action — the seam's
+ *  receipt (the counters on the `[memory]` outcome line are these plus the
+ *  parse gate's own). `restated` stays 0 until the restate action lands on the
+ *  write plan; it is on the shape now so every store answers the same fields. */
+export interface WriteCounts {
+  /** Candidates minted as new active records. */
+  inserted: number;
+  /** Candidates whose normalized text bumped an existing active record. */
+  deduped: number;
+  /** Candidates that bumped the shown record they restate (no insert). */
+  restated: number;
+  /** Records flipped to `superseded` by a candidate's pointer. */
+  superseded: number;
+  /** Records the per-scope cap evicted inside the same batch. */
+  evicted: number;
+}
+
+/** Narrowing filters for `MemoryStore.list` — each narrows, never ranks. */
+export interface MemoryListOptions {
+  /** Whole-token text/keyword filter (the human command's `<words>`). */
+  query?: string;
+  /** Keep only records of this kind (the repository window lists facts). */
+  kind?: MemoryRecord["kind"];
+}
+
+/** What one sweep did — or, on the durable path, why it could not. The
+ *  failure is a VALUE, never a throw: the one expected failure is an older
+ *  Memory Worker generation without the `/sweep` route (a 404), which the
+ *  command must report as a ⚠️ line, not crash on. */
+export type SweepOutcome =
+  | {
+      ok: true;
+      /** Active facts the gate marked (flipped to `swept`, or merely counted under `dryRun`). */
+      swept: number;
+      /** The marked record ids — always safe to show (ids carry no record text). */
+      ids: string[];
+    }
+  | { ok: false; error: string };
+
 /** A retrieval request: which resource, what to match, how many at most. */
 export interface MemoryQuery {
   scopeKey: string;
@@ -71,19 +112,29 @@ export interface MemoryStore {
   retrieve(q: MemoryQuery, trace?: TraceOptions): Promise<MemoryRecord[]>;
   /** Persist distilled candidates. Dedup (identical normalized text → bump
    *  `useCount`) and supersede (`supersedes` id → old record soft-deleted) live
-   *  inside the store. Driven by the post-run reflection pass (reflection.ts). */
-  write(scopeKey: string, records: MemoryCandidate[]): Promise<void>;
-  /** Human view: a scope's ACTIVE records, newest first, at most
-   *  `limit`. Unlike `retrieve` this never bumps usage. */
-  /** `query`: when given, only records that a query token hits
+   *  inside the store. Driven by the post-run reflection pass (reflection.ts).
+   *  Answers what the batch did (`WriteCounts`), so the caller's outcome line
+   *  reports the store's actions, never a guess. */
+  write(scopeKey: string, records: MemoryCandidate[]): Promise<WriteCounts>;
+  /** Human view and the repository window's read: a scope's ACTIVE records,
+   *  newest first, at most `limit`. Unlike `retrieve` this never bumps usage.
+   *  `opts.query`: when given, only records that a query token hits
    *  (whole-token, text or keywords) are listed — the filter narrows, it
-   *  never ranks or bumps usage. */
-  list(scopeKey: string, limit: number, query?: string): Promise<MemoryRecord[]>;
+   *  never ranks or bumps usage. `opts.kind`: when given, only records of
+   *  that kind (the repository window lists facts, never summaries). */
+  list(scopeKey: string, limit: number, opts?: MemoryListOptions): Promise<MemoryRecord[]>;
   /** Human control: soft-delete one ACTIVE record of this scope
    *  (`status: "forgotten"`, row kept for provenance). Resolves true when a
    *  record was forgotten, false when the id names nothing active in this
    *  scope — a foreign-scope id can never be forgotten through another scope. */
   forget(scopeKey: string, id: string): Promise<boolean>;
+  /** Human control: retire this scope's ACTIVE facts whose text the write
+   *  gate would reject today (`rejectionMarkers`, engine.ts) — `status:
+   *  "swept"`, rows kept for provenance, summaries never touched. Under
+   *  `dryRun` nothing flips and the marked ids are answered. Idempotent: a
+   *  second sweep answers 0. Failures come back as `{ok: false}`, never a
+   *  throw (an older Worker without the route is a reported failure). */
+  sweep(scopeKey: string, opts?: { dryRun?: boolean }): Promise<SweepOutcome>;
 }
 
 /** The resources memory is scoped to. `org` is the shared resource every
@@ -98,10 +149,16 @@ export type MemoryScope = "org" | "user" | "repo" | "channel";
 export interface MemoryConfig {
   /** Master switch. Default false → `NullMemoryStore` → zero behavior change. */
   enabled?: boolean;
-  /** Max records retrieved/injected per request. Default 8. */
+  /** Max records retrieved/injected per request. Default 32. */
   limit?: number;
-  /** Hard token budget for the injected block. Default ~800. */
+  /** Hard token budget for the injected block. Default ~3000. */
   maxTokens?: number;
+  /** The repository window: a run bound to a repository leads its block with
+   *  that repository's newest facts — at most this many, read with
+   *  `list(repoScope, repoWindow, { kind: "fact" })` — ahead of the keyword
+   *  hits, under the same budget. Default 24; `0` disables the window (the
+   *  repository scope is retrieved by keyword like the others). */
+  repoWindow?: number;
   /** Per-scope cap on ACTIVE records. A write that would leave a scope
    *  over the cap evicts the least recently used records (soft delete, status
    *  `evicted`) down to it, inside the same write. Default 500. */