@coreplane/switchboard 1.250.0 → 1.252.0

package/dist/assets/config/config.example.yaml

@@ -87,6 +87,14 @@ defaults:
   # provider default. Skipped for models without effort support.
   # efforts:
   #   coding: medium
+  # How much the bot says about its own doing (docs/reference/specs/routing-and-config.md
+  # item 28): quiet (default) — only what needs the person: answers, verdicts,
+  # refusals, questions, results, the card's progress; verbose — plus every
+  # acknowledgement (a follow-up folded into a live run, a plan handed to the
+  # runner, the workspace and budget on the card); debug — plus the router's
+  # reason and the ledger's word. Same layering as effort: per-channel/user
+  # `verbosity` and a per-request `verbosity:<level>` directive override it.
+  # verbosity: quiet
   # A boundary caps what ANY run in a scope may have — never grants — on the
   # three axes of a run's profile (docs/reference/specs/routing-and-config.md item 2):
   # maxMinutes (the wall-clock budget; at least 2), maxIdentity (the credential
@@ -156,6 +164,7 @@ defaults:
 # users:
 #   slack:U012345:
 #     model: openai/gpt-5
+#     verbosity: verbose          # hear every acknowledgement of what the bot does for you
 #     harness:
 #       coding: opencode
 
@@ -316,8 +325,10 @@ workspaceDir: ./workspaces
 #   # and — when the run is bound to a repo — that repo's scope (repo:owner/name)
 #   # plus the requesting user's own scope (user:slack:U…) — a
 #   # person's records never surface for anyone else.
-#   limit: 8            # max records retrieved/injected per request (default 8)
-#   maxTokens: 800      # hard token budget for the injected block (default 800)
+#   limit: 32           # max records retrieved/injected per request (default 32)
+#   maxTokens: 3000     # hard token budget for the injected block (default 3000)
+#   repoWindow: 24      # newest repo facts injected ahead of the keyword hits when
+#                       # the run is bound to a repo (default 24; 0 disables the window)
 #   maxRecordsPerScope: 500
 #                       # per-scope cap on ACTIVE records (default 500): a write
 #                       # that would exceed it evicts the least recently used

package/dist/assets/deploy/cloudflare/preflight.mjs

@@ -1,23 +1,22 @@
 #!/usr/bin/env node
 // Deploy preflight for the bot Worker (docs/reference/specs/slack-channel.md item 8).
 //
-// `wrangler deploy` rolls the bot container. Cloudflare's rollout sends SIGTERM
-// and the container is gone at the drain's end, whatever it was still driving:
-// the run ledger's handoff (docs/reference/specs/run-history.md item 39) lets the
-// next generation resume a run, but a resume is a recovery, not a guarantee —
-// one that fails costs the run — so a deploy never rolls over a live run.
-// `npm run deploy` runs this first and refuses while
-//   - the bot reports runs in flight (`GET /healthz` `inFlight > 0`): the
-//     runner retries every minute up to its budget, then fails by name;
+// `wrangler deploy` rolls the bot container. Cloudflare's rollout sends SIGTERM;
+// since the run ledger's handoff (docs/reference/specs/run-history.md item 39) the bot
+// hands every resumable run to the next generation and exits within seconds,
+// and the next generation continues the runs under their own cards — so a
+// deploy no longer waits on runs, and this preflight no longer refuses for
+// them. `npm run deploy` runs it first and refuses only while
 //   - the container application is not in a settled state (a rollout is still
 //     provisioning/updating — `wrangler containers list --json`): a second
 //     rollout on top of one in progress replaces the instance the first put
 //     into its graceful drain and kills whatever it was running (two deploys
 //     90 s apart once killed a review at 153 s).
-// It WARNS (never refuses) when the bot is already draining with nothing in
-// flight (`draining: true` — the instance exits on its own), and when /healthz
-// says the reconnect catch-up is failing or the bot token lacks required
-// scopes (`catchUp.error`, `catchUp.missingScopes`).
+// It WARNS (never refuses) when the bot reports runs in flight (`inFlight > 0`
+// — they hand off) or is already draining (`draining: true` — its resumable
+// runs were handed off; a ship pipeline still in flight would be killed), and
+// when /healthz says the reconnect catch-up is failing or the bot token lacks
+// required scopes (`catchUp.error`, `catchUp.missingScopes`).
 //
 // Fail closed: unreachable bot, a body without the JSON shape (a bot whose
 // /healthz answers a bare `ok` is not one this preflight can read), a wrangler failure, or an app
@@ -41,7 +40,7 @@ export const APP_NAME = "switchboard-switchboardserver";
 const SETTLED_APP_STATES = new Set(["active", "ready"]);
 
 const HOW_TO_FORCE =
-  "to deploy anyway (over the runs in flight — this kills them —, over a rollout in progress, or blind when the bot cannot be consulted): `SWITCHBOARD_DEPLOY_FORCE=1 npm run deploy` (`node preflight.mjs --force` checks alone)";
+  "to deploy anyway (over a rollout in progress, or blind when the bot cannot be consulted): `SWITCHBOARD_DEPLOY_FORCE=1 npm run deploy` (`node preflight.mjs --force` checks alone)";
 
 /** GET /healthz. Never throws: `{ok:true,payload}` (parsed JSON, or the raw text when not JSON) or `{ok:false,error}`. */
 export async function fetchHealth(baseUrl, { timeoutMs = 20_000 } = {}) {
@@ -165,16 +164,15 @@ export function decide({ health, apps }, { force = false } = {}) {
       if (!Number.isInteger(p.inFlight) || p.inFlight < 0) {
         problems.push(`bot reports an impossible inFlight=${JSON.stringify(p.inFlight)} (counter bug or old Worker)`);
       } else if (p.inFlight > 0) {
-        // A refusal: the rollout rolls the container under these runs. A
-        // handoff (run-history item 39) may resume them on the next generation,
-        // but a resume that fails costs the run — the deploy waits instead.
-        problems.push(
-          `${p.inFlight} run(s) in flight — the rollout would roll the bot container under them (a handoff is a recovery, not a guarantee)`,
+        // Not a refusal since the handoff (run-history item 39): SIGTERM hands
+        // every resumable run to the next generation, which continues it.
+        warnings.push(
+          `${p.inFlight} run(s) in flight — handed to the next generation on SIGTERM (run-history item 39); they continue there under their own cards`,
         );
       }
       if (p.draining === true) {
         warnings.push(
-          "bot is already draining from a previous deploy — the draining instance exits on its own; this rollout replaces it at once",
+          "bot is already draining from a previous deploy — its resumable runs are handed off; a ship pipeline still in flight would be killed when this rollout replaces the draining instance",
         );
       }
     }
@@ -211,7 +209,7 @@ export function decide({ health, apps }, { force = false } = {}) {
       forced: true,
       problems,
       warnings,
-      message: `preflight WARNING: deploying by force despite —\n${detail}\n  this WILL kill the runs in flight that no resume recovers, and a rollout landing on one in progress can disrupt it${warningText}`,
+      message: `preflight WARNING: deploying by force despite —\n${detail}\n  a rollout landing on one in progress can disrupt it; in-flight runs hand off regardless (run-history item 39)${warningText}`,
     };
   }
   return {
@@ -219,7 +217,7 @@ export function decide({ health, apps }, { force = false } = {}) {
     forced: false,
     problems,
     warnings,
-    message: `preflight REFUSED: a Worker deploy rolls the bot container —\n${detail}\n  wait for them to finish and retry; ${HOW_TO_FORCE}${warningText}`,
+    message: `preflight REFUSED: a Worker deploy rolls the bot container —\n${detail}\n  wait and retry; ${HOW_TO_FORCE}${warningText}`,
   };
 }
 

package/dist/assets/deploy/cloudflare/worker.ts

@@ -197,8 +197,10 @@ export class SwitchboardServer extends Container<Env> {
    * and exits, and the NEXT request through `fetch` starts the container again
    * (`startBot`, env computed then). The keep-alive cron GETs /healthz every
    * minute and the CLI's live gate polls it every 15 s, so the next request is
-   * never more than seconds away. Refuses (the deploy preflight's rules) while
-   * runs are in flight or a drain is already under way unless `force`.
+   * never more than seconds away. Refuses (the deploy preflight's rules) only the
+   * fail-closed cases — no JSON body, an impossible `inFlight` — unless
+   * `force`; runs in flight or a drain under way warn and the stop proceeds
+   * (the handoff rule).
    */
   async restart(opts: { force: boolean }): Promise<RestartOutcome> {
     if (!this.ctx.container?.running) return { kind: "not-running" };
@@ -265,7 +267,8 @@ export class SwitchboardServer extends Container<Env> {
  *  `deploy:write` in the bot's config). The Worker authenticates the bearer
  *  against the map it holds — an unknown bearer never touches the container —
  *  and the Container DO asks the bot for the grant before stopping anything.
- *  Body `{ "force": true }` bypasses the in-flight/draining refusal. */
+ *  Body `{ "force": true }` bypasses the fail-closed refusals (no JSON body,
+ *  impossible `inFlight`); runs in flight or a drain warn and never refuse. */
 async function handleAdminRestart(request: Request, env: Env): Promise<Response> {
   const json = (status: number, body: Record<string, unknown>) =>
     new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -7,6 +7,7 @@ import {
   planEviction,
   planWrite,
   rankRecords,
+  rejectionMarkers,
 } from "../../src/core/memory/engine.ts";
 import { tokenize } from "../../src/core/memory/scorer.ts";
 import { FIRING_DETAIL_MAX, isScheduleFiring, type ScheduleFiring } from "../../src/core/schedules.ts";
@@ -148,6 +149,7 @@ const traceSinks = [workerLogSink((line) => console.log(line))];
 // Route surface (JSON in/out; bearer MEMORY_TOKEN on everything but /healthz):
 //   POST /retrieve {scopeKey, query, limit} → {records: MemoryRecord[]}
 //   POST /write    {scopeKey, records: MemoryCandidate[]} → {ok, inserted, deduped, superseded}
+//   POST /sweep    {scopeKey, dryRun?} → {ok, swept} (+ ids under dryRun — the marked rows, flipped to `swept`)
 //   GET  /healthz  → {ok:true}  (deploy wake ping; touches no DO)
 // Scheduled-firing routes (the record behind the /runs Scheduled panel;
 // written by the bot's Worker shim after every cron firing, read by the bot's
@@ -463,14 +465,19 @@ export class MemoryDO extends DurableObject<Env> {
     return counts;
   }
 
-  /** Human view (docs/reference/specs/memory.md item 24): the scope's ACTIVE rows, newest first, no usage
-   *  bump. With `query`, only rows an FTS token hits (the same quoted-OR MATCH
-   *  as retrieve, so user text never reaches the FTS parser as syntax); a
-   *  query with no tokens lists nothing. */
-  async list(_scopeKey: string, limit: number, query?: string): Promise<MemoryRecord[]> {
+  /** Human view and the repository window's read (docs/reference/specs/memory.md items 22, 26): the
+   *  scope's ACTIVE rows, newest first, no usage bump. With `query`, only rows
+   *  an FTS token hits (the same quoted-OR MATCH as retrieve, so user text
+   *  never reaches the FTS parser as syntax); a query with no tokens lists
+   *  nothing. With `kind`, only rows of that kind (the window lists facts). */
+  async list(_scopeKey: string, limit: number, query?: string, kind?: MemoryRecord["kind"]): Promise<MemoryRecord[]> {
     if (query === undefined) {
       return this.sql
-        .exec<Row>(`SELECT * FROM records WHERE status = 'active' ORDER BY seq DESC LIMIT ?`, limit)
+        .exec<Row>(
+          `SELECT * FROM records WHERE status = 'active'${kind === undefined ? "" : " AND kind = ?"} ORDER BY seq DESC LIMIT ?`,
+          ...(kind === undefined ? [] : [kind]),
+          limit,
+        )
         .toArray()
         .map(toRecord);
     }
@@ -480,9 +487,10 @@ export class MemoryDO extends DurableObject<Env> {
       .exec<Row>(
         `SELECT r.* FROM records r
            JOIN records_fts f ON f.id = r.id
-          WHERE r.status = 'active' AND records_fts MATCH ?
+          WHERE r.status = 'active'${kind === undefined ? "" : " AND r.kind = ?"} AND records_fts MATCH ?
           ORDER BY r.seq DESC
           LIMIT ?`,
+        ...(kind === undefined ? [] : [kind]),
         match,
         limit,
       )
@@ -504,6 +512,33 @@ export class MemoryDO extends DurableObject<Env> {
       return flipped;
     });
   }
+
+  /** Human control (docs/reference/specs/memory.md item 27): retire every
+   *  ACTIVE fact whose text the write gate would reject today — the same
+   *  `rejectionMarkers` the bot's write path runs, imported from the shared
+   *  engine, so the sweep and the gate can never disagree. Summaries are never
+   *  gated, so never swept. The scan, the flips and the FTS deletes run in ONE
+   *  sync transaction (the per-scope cap's atomicity rule): the sweep commits
+   *  whole or not at all. Idempotent — swept rows are no longer active, so a
+   *  second call answers 0. Under `dryRun` nothing flips. */
+  async sweep(_scopeKey: string, dryRun: boolean): Promise<{ swept: number; ids: string[] }> {
+    return this.ctx.storage.transactionSync(() => {
+      const ids = this.sql
+        .exec<Row>(`SELECT * FROM records WHERE status = 'active' AND kind = 'fact'`)
+        .toArray()
+        .filter((row) => rejectionMarkers(row.text).length > 0)
+        .map((row) => row.id);
+      if (!dryRun) {
+        for (const id of ids) {
+          // Soft delete for the record row, hard delete for its FTS entry —
+          // the forget/supersede/evict hygiene rule (§15).
+          this.sql.exec(`UPDATE records SET status = 'swept' WHERE id = ? AND status = 'active'`, id);
+          this.sql.exec(`DELETE FROM records_fts WHERE id = ?`, id);
+        }
+      }
+      return { swept: ids.length, ids };
+    });
+  }
 }
 
 /** Build the FTS5 MATCH expression for a query: each engine token (`[a-z0-9]+`
@@ -779,6 +814,27 @@ export class ConfigDO extends DurableObject<Env> {
     });
   }
 
+  /** The thread's pending row when one exists and is inside its ttl, else
+   *  null. A pure read: expiry is checked here on this object's clock and
+   *  nothing is deleted — nothing sweeps, and a consume still finds the
+   *  expired row to name `expired`. */
+  async pendingConfirmationByThread(threadKey: string, now: number): Promise<ConfirmationRow | null> {
+    const row = this.sql
+      .exec<{ id: string; requester: string; expires_at: number; body: string }>(
+        `SELECT id, requester, expires_at, body FROM confirmations WHERE thread_key = ?`,
+        threadKey,
+      )
+      .toArray()[0];
+    if (!row || row.expires_at <= now) return null;
+    return {
+      id: row.id,
+      threadKey,
+      requester: row.requester,
+      expiresAt: row.expires_at,
+      body: parseStored(row.body, isJsonObject) ?? {},
+    };
+  }
+
   private readConfirmation(id: string): ConfirmationRow | undefined {
     const row = this.sql
       .exec<{ thread_key: string; requester: string; expires_at: number; body: string }>(
@@ -1199,6 +1255,7 @@ const CONFIG_ROUTES = new Set([
   "/config/confirmations/consume",
   "/config/confirmations/cancel",
   "/config/confirmations/cancel-by-thread",
+  "/config/confirmations/pending-by-thread",
 ]);
 const TICKET_STATES: ReadonlySet<string> = new Set<McpTicketState>(MCP_TICKET_STATES);
 /** A confirmation id as the bot mints it (a UUID) — one token, no whitespace, bounded. */
@@ -1284,6 +1341,15 @@ async function handleConfig(pathname: string, body: unknown, env: Env): Promise<
       console.log(`[config/confirmations/cancel] ${click.id} ${"ok" in outcome ? "cancelled" : outcome.refused}`);
       return json(outcome);
     }
+    case "/config/confirmations/pending-by-thread": {
+      if (typeof b.threadKey !== "string" || !b.threadKey) return json({ error: "threadKey required" }, 400);
+      // The stub types this result `never`: workers-types' Serializable rejects
+      // the row's opaque `Record<string, unknown>` body. What arrives is the
+      // object's declared result, so the boundary restates it.
+      const row = (await dO.pendingConfirmationByThread(b.threadKey, systemClock())) as ConfirmationRow | null;
+      console.log(`[config/confirmations/pending-by-thread] ${b.threadKey} ${row === null ? "none" : row.id}`);
+      return json({ row });
+    }
     case "/config/confirmations/cancel-by-thread": {
       if (typeof b.threadKey !== "string" || !b.threadKey) return json({ error: "threadKey required" }, 400);
       if (!Array.isArray(b.actorIds) || !b.actorIds.every((a): a is string => typeof a === "string"))
@@ -3090,8 +3156,10 @@ function parseLimit(v: unknown): Validated<number> {
   return { ok: true, value: v };
 }
 
-/** `POST /list {scopeKey, limit, query?}`. */
-function parseList(body: unknown): Validated<{ scopeKey: string; limit: number; query?: string }> {
+/** `POST /list {scopeKey, limit, query?, kind?}`. */
+function parseList(
+  body: unknown,
+): Validated<{ scopeKey: string; limit: number; query?: string; kind?: MemoryRecord["kind"] }> {
   if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
   const b = body as Record<string, unknown>;
   const scope = parseScopeKey(b.scopeKey);
@@ -3102,12 +3170,29 @@ function parseList(body: unknown): Validated<{ scopeKey: string; limit: number;
     if (typeof b.query !== "string") return invalid("query must be a string");
     if (b.query.length > MAX_QUERY_CHARS) return invalid(`query must be at most ${MAX_QUERY_CHARS} characters`);
   }
+  if (b.kind !== undefined && b.kind !== "fact" && b.kind !== "summary")
+    return invalid('kind must be "fact" or "summary"');
   return {
     ok: true,
-    value: { scopeKey: scope.value, limit: limit.value, ...(typeof b.query === "string" ? { query: b.query } : {}) },
+    value: {
+      scopeKey: scope.value,
+      limit: limit.value,
+      ...(typeof b.query === "string" ? { query: b.query } : {}),
+      ...(b.kind === "fact" || b.kind === "summary" ? { kind: b.kind } : {}),
+    },
   };
 }
 
+/** `POST /sweep {scopeKey, dryRun?}`. */
+function parseSweep(body: unknown): Validated<{ scopeKey: string; dryRun: boolean }> {
+  if (!isJsonObject(body)) return invalid("body must be a JSON object");
+  const b = body;
+  const scope = parseScopeKey(b.scopeKey);
+  if (!scope.ok) return scope;
+  if (b.dryRun !== undefined && typeof b.dryRun !== "boolean") return invalid("dryRun must be a boolean");
+  return { ok: true, value: { scopeKey: scope.value, dryRun: b.dryRun === true } };
+}
+
 /** `POST /forget {scopeKey, id}`: the id is an opaque key, same caps as scopeKey. */
 function parseForget(body: unknown): Validated<{ scopeKey: string; id: string }> {
   if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
@@ -4298,6 +4383,7 @@ const ROUTES = new Set([
   "/write",
   "/list",
   "/forget",
+  "/sweep",
   "/schedules/record",
   "/schedules/latest",
   "/runs/put",
@@ -4391,8 +4477,8 @@ async function handleRequest(request: Request, env: Env, admission: Admission):
   if (url.pathname === "/list") {
     const parsed = parseList(body);
     if (!parsed.ok) return json({ error: parsed.error }, 400);
-    const { scopeKey, limit, query } = parsed.value;
-    const records = await env.MEMORY.get(env.MEMORY.idFromName(scopeKey)).list(scopeKey, limit, query);
+    const { scopeKey, limit, query, kind } = parsed.value;
+    const records = await env.MEMORY.get(env.MEMORY.idFromName(scopeKey)).list(scopeKey, limit, query, kind);
     console.log(`[list] ${scopeKey} -> ${records.length} records`);
     return json({ records });
   }
@@ -4405,6 +4491,16 @@ async function handleRequest(request: Request, env: Env, admission: Admission):
     console.log(`[forget] ${scopeKey} ${id} -> ${forgotten}`);
     return json({ ok: true, forgotten });
   }
+  if (url.pathname === "/sweep") {
+    const parsed = parseSweep(body);
+    if (!parsed.ok) return json({ error: parsed.error }, 400);
+    const { scopeKey, dryRun } = parsed.value;
+    const out = await env.MEMORY.get(env.MEMORY.idFromName(scopeKey)).sweep(scopeKey, dryRun);
+    // Observability: scope + count only (ids carry no record text; they ride
+    // the dryRun answer, not the log).
+    console.log(`[sweep] ${scopeKey} -> ${out.swept}${dryRun ? " (dry run)" : ""}`);
+    return json({ ok: true, swept: out.swept, ...(dryRun ? { ids: out.ids } : {}) });
+  }
 
   const parsed = parseWrite(body);
   if (!parsed.ok) return json({ error: parsed.error }, 400);

package/dist/assets/deploy/cloudflare-resident/memoryGuard.ts

@@ -0,0 +1,212 @@
+// The resident guards its own memory (docs/reference/specs/resident-repos.md
+// item 70) — the PURE half, kept free of the Sandbox SDK and DO storage so it
+// runs under plain-Node vitest (memoryGuard.test.ts) like gc.ts and drain.ts.
+// The Worker owns the one real reader (a single exec of CGROUP_READ_ARGV via
+// its exec choke point) and feeds this module the raw output; tests feed a
+// fake. A container at its cgroup memory cap wedges its own control port and
+// every run on it loses its work, so the resident refuses NEW work by name
+// while it still can: above the soft threshold a new attach is refused like
+// `mirror-busy` (the bot falls back cold or waits, the card says why), above
+// the hard threshold a new exec is refused with the numbers — and a command
+// already running is never touched: the gate sits at each route's start and
+// kills nothing.
+import { MEMORY_PRESSURE_REASON } from "../../src/execution/sandboxErrors.js";
+
+export { MEMORY_PRESSURE_REASON };
+
+/** Above this percent of the cgroup memory cap a NEW `/attach` is refused —
+ *  new runs go elsewhere while the ones already here finish. */
+export const MEMORY_SOFT_LIMIT_PCT = 80;
+
+/** Above this percent a NEW `/exec` is refused too — the resident answers
+ *  nothing but the work already in flight, which always runs to completion. */
+export const MEMORY_HARD_LIMIT_PCT = 90;
+
+/** One reading of the container's cgroup v2 accounting. */
+export interface MemoryReading {
+  /** ISO timestamp the caller supplied (the resident's clock seam). */
+  at: string;
+  /** memory.current — bytes charged to the cgroup now. */
+  usedBytes: number;
+  /** memory.max — the cap in bytes, or null when the file reads `max` (no cap). */
+  capBytes: number | null;
+  /** used/cap rounded to whole percent; null without a cap (nothing to gate on). */
+  percent: number | null;
+  /** cpu.stat's usage_usec, for the same log line; null when absent. */
+  cpuUsageUsec: number | null;
+}
+
+/** The reader seam: one call returns the raw output of `CGROUP_READ_ARGV`.
+ *  A throw of `MemorySampleUnavailable` means "no reading this time" (the
+ *  container busy or replaced under the probe) and never disables the gate;
+ *  any other throw is an unreadable cgroup and disables it (one log line). */
+export interface CgroupReader {
+  read(): Promise<string>;
+}
+
+/** The one transient escape: the reader could not run at all right now.
+ *  `invalidates` says the container the last reading came from is gone (a
+ *  runtime replacement under the probe), so the guard forgets that reading —
+ *  a dead container's numbers must not gate the work that replaces it. */
+export class MemorySampleUnavailable extends Error {
+  constructor(
+    message: string,
+    readonly invalidates = false,
+  ) {
+    super(message);
+  }
+}
+
+/** The separator `CGROUP_READ_ARGV` prints between the three files. */
+export const CGROUP_FILE_SEPARATOR = ":::";
+
+/** One exec, three files: memory.current, memory.max, cpu.stat from the
+ *  container's own cgroup v2 root. `&&` so a missing file is a non-zero exit
+ *  (an unreadable cgroup), never a silently short output. */
+export const CGROUP_READ_ARGV: readonly string[] = [
+  "sh",
+  "-c",
+  `cat /sys/fs/cgroup/memory.current && echo ${CGROUP_FILE_SEPARATOR} && ` +
+    `cat /sys/fs/cgroup/memory.max && echo ${CGROUP_FILE_SEPARATOR} && cat /sys/fs/cgroup/cpu.stat`,
+];
+
+/** Parses one reader output into a reading; throws on anything malformed. */
+export function parseCgroupOutput(raw: string, at: string): MemoryReading {
+  const parts = raw.split(CGROUP_FILE_SEPARATOR).map((p) => p.trim());
+  if (parts.length !== 3) throw new Error(`expected 3 cgroup sections, got ${parts.length}`);
+  const usedBytes = Number(parts[0]);
+  if (!Number.isFinite(usedBytes) || usedBytes < 0) throw new Error(`memory.current is not a byte count: ${parts[0]}`);
+  let capBytes: number | null = null;
+  if (parts[1] !== "max") {
+    capBytes = Number(parts[1]);
+    if (!Number.isFinite(capBytes) || capBytes <= 0) throw new Error(`memory.max is not a byte count: ${parts[1]}`);
+  }
+  const usage = /(?:^|\n)usage_usec (\d+)/.exec(parts[2]);
+  const cpuUsageUsec = usage ? Number(usage[1]) : null;
+  const percent = capBytes === null ? null : Math.round((usedBytes / capBytes) * 100);
+  return { at, usedBytes, capBytes, percent, cpuUsageUsec };
+}
+
+/** The one structured line Workers Logs gets per sample: used bytes, cap
+ *  bytes, percent (and the cpu counter beside them). */
+export function memoryLogLine(r: MemoryReading): string {
+  const cap = r.capBytes === null ? "uncapped" : `${r.capBytes} bytes cap`;
+  const pct = r.percent === null ? "" : ` (${r.percent}%)`;
+  const cpu = r.cpuUsageUsec === null ? "" : ` — cpu usage_usec ${r.cpuUsageUsec}`;
+  return `memory: used ${r.usedBytes} bytes of ${cap}${pct}${cpu}`;
+}
+
+/** Which route asks the gate. */
+export type MemoryGateRoute = "attach" | "exec";
+
+/** A refusal with the numbers on it — the message is the whole story. */
+export interface MemoryRefusal {
+  reason: typeof MEMORY_PRESSURE_REASON;
+  percent: number;
+  usedBytes: number;
+  capBytes: number;
+  message: string;
+}
+
+/** The pure gate over one reading: below both thresholds nothing changes; at
+ *  or above the soft one a new attach is refused (queued — the caller waits or
+ *  falls back, like `mirror-busy`); at or above the hard one a new exec is
+ *  refused too. No reading, or no cap, gates nothing. */
+export function gateMemory(route: MemoryGateRoute, reading: MemoryReading | null): MemoryRefusal | null {
+  if (!reading || reading.percent === null || reading.capBytes === null) return null;
+  const { percent, usedBytes, capBytes } = reading;
+  const refusal = (message: string): MemoryRefusal => ({
+    reason: MEMORY_PRESSURE_REASON,
+    percent,
+    usedBytes,
+    capBytes,
+    message,
+  });
+  if (route === "exec" && percent >= MEMORY_HARD_LIMIT_PCT) {
+    return refusal(
+      `${MEMORY_PRESSURE_REASON}: resident at ${percent}% of its memory cap (${usedBytes} of ${capBytes} bytes) — ` +
+        `a new command is refused above ${MEMORY_HARD_LIMIT_PCT}% while the commands already running finish`,
+    );
+  }
+  if (route === "attach" && percent >= MEMORY_SOFT_LIMIT_PCT) {
+    return refusal(
+      `${MEMORY_PRESSURE_REASON}: resident near its memory cap, ${percent}% used (${usedBytes} of ${capBytes} bytes), ` +
+        `queued — a new attach is refused above ${MEMORY_SOFT_LIMIT_PCT}% until the runs here release memory`,
+    );
+  }
+  return null;
+}
+
+/** The message of whatever was thrown (local: this module stays dependency-free). */
+const causeText = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** The guard one resident holds: samples through the reader, keeps the last
+ *  reading, gates the two routes — and on an unreadable cgroup logs ONCE and
+ *  disables itself for the incarnation instead of refusing everything. */
+export class MemoryGuard {
+  private disabledWhy: string | null = null;
+  private last: MemoryReading | null = null;
+
+  constructor(
+    private readonly reader: CgroupReader,
+    private readonly log: (line: string) => void,
+  ) {}
+
+  /** The last reading taken this incarnation, for `/status` and `/residents`. */
+  get lastReading(): MemoryReading | null {
+    return this.last;
+  }
+
+  /** Whether an unreadable cgroup turned the gate off (the why is logged once). */
+  get disabled(): boolean {
+    return this.disabledWhy !== null;
+  }
+
+  /** Forgets the last reading: the container it measured no longer runs (it
+   *  went inactive, or was replaced under the probe), so nothing gates on it
+   *  until a fresh sample lands. The gate's disabled state is untouched. */
+  invalidate(): void {
+    this.last = null;
+  }
+
+  /** One reader call, one log line. A `MemorySampleUnavailable` keeps the last
+   *  reading and the gate as they were — unless it `invalidates` (the runtime
+   *  was replaced under the probe), which forgets the reading so a stale one
+   *  never masks the route's own runtime-replaced answer; any other failure
+   *  disables the gate. */
+  async sample(at: string): Promise<MemoryReading | null> {
+    if (this.disabledWhy !== null) return null;
+    let raw: string;
+    try {
+      raw = await this.reader.read();
+    } catch (err) {
+      if (err instanceof MemorySampleUnavailable) {
+        if (err.invalidates) this.last = null;
+        return null;
+      }
+      this.disable(causeText(err));
+      return null;
+    }
+    let reading: MemoryReading;
+    try {
+      reading = parseCgroupOutput(raw, at);
+    } catch (err) {
+      this.disable(causeText(err));
+      return null;
+    }
+    this.last = reading;
+    this.log(memoryLogLine(reading));
+    return reading;
+  }
+
+  /** The route's verdict over the last reading; a disabled gate refuses nothing. */
+  gate(route: MemoryGateRoute): MemoryRefusal | null {
+    if (this.disabledWhy !== null) return null;
+    return gateMemory(route, this.last);
+  }
+
+  private disable(why: string): void {
+    this.disabledWhy = why;
+    this.log(`memory: cgroup unreadable — the memory gate is disabled for this incarnation (${why})`);
+  }
+}

package/dist/assets/deploy/cloudflare-resident/refresh.ts

@@ -58,7 +58,7 @@ export interface RefreshInstanceAction {
  *  (`stepTimeoutMs`), so a step timeout and a command timeout agree. */
 const REFRESH_FETCH_STEP_BUDGET_MS = RESTORE_MAX_MS + GIT_NETWORK_TIMEOUT_MS; // a wake's restore, then the fetch
 const REFRESH_INSTALL_STEP_BUDGET_MS = REFRESH_INSTALL_TIMEOUT_MS + DEPS_STEP_OVERHEAD_MS; // the install's own lease
-const REFRESH_BUILD_STEP_BUDGET_MS = GIT_NETWORK_TIMEOUT_MS + REFRESH_BUILD_TIMEOUT_MS; // the build's mutex lease
+const REFRESH_BUILD_STEP_BUDGET_MS = 5 * GIT_NETWORK_TIMEOUT_MS + 2 * REFRESH_BUILD_TIMEOUT_MS; // five git-budgeted commands — stage-clear, stage, the staging fetch (under the stage lock), the checkout update and the swap (under the swap lock) — plus the off-lock reset/clean, deps re-link and build
 const REFRESH_SNAPSHOT_STEP_BUDGET_MS = R2_TRANSFER_TIMEOUT_MS + GIT_NETWORK_TIMEOUT_MS; // the archives, then the reclaim pass
 /** The sweep: one cleanliness check per binding idle past an hour (at most the
  *  pool's worth, one exec budget each), then the removals under the mirror lock. */