@coreplane/switchboard 1.255.0 → 1.257.0

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

@@ -343,7 +343,16 @@ import {
 } from "../../src/execution/residentDepsStore.js";
 import { buildId, injectedBuildStamp } from "../../src/deploy/buildStamp.js";
 import { createRefreshInstance, createRefreshInstanceNow, type RefreshInstanceParams } from "./refresh";
-import { drainRefusal, liveDrain, parseDrainRequest, type DrainRecord } from "./drain";
+import {
+  drainRefusal,
+  holdDrain,
+  liftDrain,
+  liveDrain,
+  parseDrainRequest,
+  reportImageCurrent,
+  staleHolds,
+  type DrainRecord,
+} from "./drain";
 import {
   CGROUP_READ_ARGV,
   MEMORY_PRESSURE_REASON,
@@ -1434,6 +1443,10 @@ const TEST_OVERRIDES_KEY = "testOverrides";
  *  counts as a slot; it survives the isolate swap a deploy performs, which is
  *  why the record carries its own end. */
 const DRAIN_KEY = "drain";
+/** Resident-DO key (issue 1931): set when a deploy's reconcile could not
+ *  verify this resident's container on the new image; the next reconcile that
+ *  finds it current reports to the registry and clears it. */
+const IMAGE_REPORT_PENDING_KEY = "imageReportPending";
 
 type OnboardResult = { ok: true; record: ResidentRecord } | { ok: false; status: number; error: string };
 
@@ -1568,12 +1581,56 @@ export class ResidentRegistryDO extends DurableObject<Env> {
     return record;
   }
 
-  /** Admin-only by construction (POST /undrain): true when a record was there.
-   *  A cleared drain posts `below` — the plane's resident-drain window lifts. */
-  async clearDrain(): Promise<boolean> {
+  /** Admin-only by construction (POST /undrain): `cleared` when a record was
+   *  there and was lifted — a cleared drain posts `below`, the plane's
+   *  resident-drain window lifts. With holds outstanding (issue 1931: a
+   *  container still to report the deploy's image) the fleet STAYS closed:
+   *  the record stands with `liftAsked` and the last container's report lifts
+   *  it (`reportContainerImageCurrent`); `until` remains the backstop. */
+  async clearDrain(): Promise<{ cleared: boolean; held: string[] }> {
+    const record = liveDrain(await this.ctx.storage.get(DRAIN_KEY), systemClock());
+    if (record !== null) {
+      const lift = liftDrain(record);
+      if (!lift.cleared) {
+        await this.ctx.storage.put(DRAIN_KEY, lift.record);
+        return { cleared: false, held: lift.record.holds ?? [] };
+      }
+    }
     const had = await this.ctx.storage.delete(DRAIN_KEY);
     if (had) await this.pushDrainPost("below");
-    return had;
+    return { cleared: had, held: [] };
+  }
+
+  /** The deploy's reconcile could not verify these residents' containers on
+   *  the new image (issue 1931): hold the drain for each — the fleet must not
+   *  reopen onto them until they report. No live drain, nothing to hold. */
+  async holdDrainFor(resources: string[]): Promise<void> {
+    const now = systemClock();
+    const record = liveDrain(await this.ctx.storage.get(DRAIN_KEY), now);
+    if (record === null || resources.length === 0) return;
+    const held = holdDrain(record, resources, now);
+    await this.ctx.storage.put(DRAIN_KEY, held);
+    // The hold's liveness alarm (issue 2044): the cycle bound is the earlier
+    // end, so the alarm fires there — reopening the fleet with the stale
+    // containers named — instead of at `until`, the last resort.
+    if (held.holdsUntil !== undefined) await this.ctx.storage.setAlarm(Date.parse(held.holdsUntil));
+  }
+
+  /** One resident's word that its running container is on the deploy's image:
+   *  its hold drops, and when it was the last hold of a lift already asked the
+   *  drain lifts here — the reopen fires on the last container's report. */
+  async reportContainerImageCurrent(resource: string): Promise<{ lifted: boolean }> {
+    const record = liveDrain(await this.ctx.storage.get(DRAIN_KEY), systemClock());
+    if (record === null) return { lifted: false };
+    const report = reportImageCurrent(record, resource);
+    if (report.record === null) {
+      await this.ctx.storage.delete(DRAIN_KEY);
+      await this.pushDrainPost("below");
+      console.log(`[drain] fleet reopened — ${resource} was the last container to report the deploy's image`);
+      return { lifted: true };
+    }
+    await this.ctx.storage.put(DRAIN_KEY, report.record);
+    return { lifted: false };
   }
 
   /** The one alarm, at the drain's `until` (record 0064): a drain past
@@ -1585,11 +1642,25 @@ export class ResidentRegistryDO extends DurableObject<Env> {
     const stored = await this.ctx.storage.get(DRAIN_KEY);
     if (stored === undefined) return;
     if (liveDrain(stored, now) === null) {
+      // The hold's liveness (issue 2044): a reopen past the cycle bound names
+      // the containers whose post-deploy cycle never landed — a warning, never
+      // a silence; each restarts on its own next quiet attach or refresh.
+      const stale = staleHolds(stored, now);
+      if (stale !== null)
+        console.log(
+          `[drain] fleet reopened with ${stale.join(", ")} still on the pre-deploy image — the post-deploy cycle did not land within its bound; a stale container restarts on its next quiet attach or refresh`,
+        );
       await this.ctx.storage.delete(DRAIN_KEY);
       await this.pushDrainPost("below");
     } else {
-      // Replaced with a later end under an already-armed alarm: re-arm at it.
-      await this.ctx.storage.setAlarm(Date.parse((stored as DrainRecord).until));
+      // Replaced with a later end under an already-armed alarm: re-arm at the
+      // record's own earlier end — the hold's cycle bound when one stands.
+      const record = stored as DrainRecord;
+      const ends = [
+        Date.parse(record.until),
+        ...(record.holdsUntil !== undefined ? [Date.parse(record.holdsUntil)] : []),
+      ];
+      await this.ctx.storage.setAlarm(Math.min(...ends.filter(Number.isFinite)));
     }
   }
 
@@ -3211,6 +3282,14 @@ export class ResidentDO extends Sandbox<Env> {
       await this.writeDiskMarkers({ ready: sha, depsKey: lockfileHash, builtSha: sha });
       this.deleteSchedules(PROVISIONING_CALLBACK);
       await this.setResidentState("warm");
+      // A fresh provision runs on the image the deployed Worker pins, so it IS
+      // the cycle a held drain waits for (issue 2044): report it — a rebuild
+      // mid-drain reopens the fleet instead of leaving the hold standing on a
+      // report `reconcileImage` would never send for a container it never saw
+      // as stale. The marker is cleared with the report; a failure keeps both
+      // for the next reconcile, and the hold's cycle bound is the backstop.
+      await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
+      await this.reportPendingImageCurrent("provision");
       // The first refresh instance is the cron's: the row now reads `warm`
       // with no instance recorded, so the next firing creates it (item 9).
     } catch (err) {
@@ -4936,41 +5015,121 @@ export class ResidentDO extends Sandbox<Env> {
    *  registration whose release never came defers it only until the clean-idle
    *  sweep drains that registration. Answers `restarted` when a stop was
    *  issued, else why not. */
-  private async reconcileImage(where: string): Promise<ImageReconcileResult> {
-    if (!(await this.isRuntimeActive().catch(() => false))) return "inactive";
+  private async reconcileImage(where: string, force = false): Promise<ImageReconcileResult> {
+    if (!(await this.isRuntimeActive().catch(() => false))) {
+      // An inactive container's next start is on the deployed image by
+      // construction — and a held resident whose container idled out has no
+      // other reporter left: new attaches are refused by the very drain the
+      // hold keeps standing, so without this report the fleet stays closed
+      // until the drain's `until` backstop (issue 1931).
+      await this.reportPendingImageCurrent(where);
+      return "inactive";
+    }
     const last = THREAD_USERS[THREAD_USERS.length - 1];
-    const probe = await this.run(["id", "-u", last]);
-    if (probe.exitCode === 0) return "current";
+    // A pending report marker (issue 1931) means a deploy could not verify this
+    // container on its image: the probe shortcut below is a POOL-USER check the
+    // pre-deploy image passes when the pool did not change, so it can never
+    // satisfy the marker — the container is treated as stale until it is cycled
+    // post-deploy and the fresh start reported.
+    const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
+    if (!force && pending === undefined) {
+      const probe = await this.run(["id", "-u", last]);
+      if (probe.exitCode === 0) return "current";
+    }
+    const stale = force
+      ? "the container predates the deploy"
+      : pending !== undefined
+        ? "a deploy's new-image report is pending, so the running container cannot be trusted current"
+        : `${last} missing in the running container`;
     const busy = this.inFlightCount();
     if (busy > 0) {
-      console.log(
-        `image-stale (${where}): ${last} missing but ${busy} operation(s)/attach(es) in flight — deferring restart`,
-      );
+      console.log(`image-stale (${where}): ${stale} but ${busy} operation(s)/attach(es) in flight — deferring restart`);
       return "deferred";
     }
     const registered = await this.registeredRunsBeyondOps();
     if (registered > 0) {
       console.log(
-        `image-stale (${where}): ${last} missing but ${registered} run registration(s) live — deferring restart until the resident is quiet`,
+        `image-stale (${where}): ${stale} but ${registered} run registration(s) live — deferring restart until the resident is quiet`,
       );
       return "deferred";
     }
-    console.log(
-      `image-stale (${where}): ${last} missing in the running container — stopping so it restarts on the current image`,
-    );
+    console.log(`image-stale (${where}): ${stale} — stopping so it restarts on the current image`);
     this.swapIncarnation(); // deliberate incarnation swap
     await this.stop().catch((err) => console.log(`image-stale: stop failed: ${errMsg(err)}`));
+    if (pending !== undefined) {
+      // The post-deploy cycle just happened: probe the FRESH container — the
+      // SDK boots it for this command on the image the deployed Worker pins,
+      // so a fresh start answering after the deploy is the verified fact
+      // (issue 1931), never the pool-user probe on the old process. A failed
+      // probe keeps the marker: the next reconcile tries the cycle again.
+      const fresh = await this.run(["id", "-u", last])
+        .then((p) => p.exitCode === 0)
+        .catch(() => false);
+      if (fresh) await this.reportPendingImageCurrent(where);
+      else
+        console.log(`image-stale (${where}): the fresh container's probe failed — the new-image report stays pending`);
+    }
     return "restarted";
   }
 
+  /** The report a held drain waits for (issue 1931): when the deploy's
+   *  reconcile could not verify this resident's fresh container on the new
+   *  image, a marker stays in storage and the registry holds the drain. The
+   *  fact the report stands on is a fresh container start AFTER the deploy —
+   *  the marker makes `reconcileImage` treat the container as stale until the
+   *  cycle happens, so this is called only behind that fresh start (or on an
+   *  inactive resident, whose next start is on the new image by construction).
+   *  The marker is deleted only after a successful report: a transient failure
+   *  keeps it for the next reconcile, and the drain's `until` is the backstop
+   *  for a report that never lands. */
+  private async reportPendingImageCurrent(where: string): Promise<boolean> {
+    const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
+    if (pending === undefined) return true;
+    try {
+      const { lifted } = await registryStub(this.env).reportContainerImageCurrent(pending.resource);
+      await this.ctx.storage.delete(IMAGE_REPORT_PENDING_KEY);
+      console.log(
+        `[reconcile] ${pending.resource} reports the deploy's image (${where})${lifted ? " — drain lifted" : ""}`,
+      );
+      return true;
+    } catch (err) {
+      console.log(
+        `[reconcile] ${pending.resource}: the new-image report failed (${where}): ${errMsg(err)} — retried on the next reconcile`,
+      );
+      return false;
+    }
+  }
+
   /** The deploy's reconcile, inside the drain window (item 69's order: the
    *  runs in flight end, the swap lands, the containers reconcile, the fleet
    *  reopens): `POST /reconcile` calls this on every resident after the Worker
-   *  deploy landed and BEFORE the drain is lifted, so a container that
-   *  predates the new image restarts while nothing can be admitted onto it —
-   *  never under the first run the reopened fleet admits. */
-  async reconcileForDeploy(): Promise<{ result: ImageReconcileResult }> {
-    return { result: await this.reconcileImage("deploy") };
+   *  deploy landed and BEFORE the drain is lifted. The pool-user probe cannot
+   *  tell the pre-deploy image from the new one when the pool did not change,
+   *  and the platform replaces the container processes asynchronously after an
+   *  image-changing deploy (issue 1931) — so this path never trusts "current":
+   *  an active, quiet container is always cycled, and the fresh start —
+   *  necessarily on the deploy's image, which landed before this call — is
+   *  probed. `verified` true is the fact the reopen may stand on; anything
+   *  else (deferred, a failed fresh probe) leaves a hold on the drain, cleared
+   *  by this resident's later report (`reportPendingImageCurrent`), never by a
+   *  timer.
+   *
+   *  The hold lands BEFORE the marker: the marker is what lets any concurrent
+   *  attach/refresh reconcile report, and a report that reaches the registry
+   *  before the hold is a no-op — the marker would be consumed and the hold
+   *  added afterwards would wait for a report nothing sends (until the drain's
+   *  `until`). Held first, every report finds its hold. */
+  async reconcileForDeploy(resource: string): Promise<{ result: ImageReconcileResult; verified: boolean }> {
+    await registryStub(this.env).holdDrainFor([resource]);
+    await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
+    const result = await this.reconcileImage("deploy", true);
+    if (result === "deferred") return { result, verified: false };
+    // Inactive: the inactive early-return reported (the next start is on the
+    // new image by construction). Restarted: the cycle's fresh probe and
+    // report ran inside reconcileImage. Either way the marker gone is the
+    // verification.
+    const verified = (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) === undefined;
+    return { result, verified };
   }
 
   // -- watchdog (the sparse cron; it re-arms nothing) --------------------------
@@ -7467,6 +7626,19 @@ export class ResidentDO extends Sandbox<Env> {
   }
 
   private async runOpTraced(op: "test" | "build", refArg: string | null, t0: number): Promise<OpRunOk | ThreadErr> {
+    // The fleet drain (item 69; issue 2044): a typed op is a new piece of work
+    // like a new run's attach, and during the incident one waited silently at
+    // the drain — so it is answered with the drain's own record at once, a
+    // deterministic refusal the command surfaces as its reason, never a wait.
+    const drain = await this.fleetDrain();
+    if (drain !== null) {
+      return {
+        error: `op-refused: the resident fleet is drained for ${drain.reason} (asked by ${drain.by}, ends by ${drain.until}) — re-run the command when the fleet reopens`,
+        status: 503,
+        reason: "draining",
+        cause: "system",
+      };
+    }
     try {
       await this.ensureHydrated();
     } catch (err) {
@@ -7940,6 +8112,7 @@ export class ResidentDO extends Sandbox<Env> {
       AUTO_REBUILDS_KEY,
       INFRA_STREAK_KEY,
       MEMORY_KEY,
+      IMAGE_REPORT_PENDING_KEY,
     ]);
     const facts = map.get(FACTS_KEY) as RepoFacts | undefined;
     const snap = map.get(SNAPSHOT_KEY) as SnapshotRecord | undefined;
@@ -8017,6 +8190,11 @@ export class ResidentDO extends Sandbox<Env> {
       inFlight: this.inFlightCount() + registeredRuns,
       // The runs alone (no refresh cycle): what the deploy preflight refuses on.
       runsInFlight: this.runsInFlightCount() + registeredRuns,
+      // Issue 2044: whether this container's new-image report is still owed —
+      // `pending` names a resident a held drain waits on, so `repo list` and
+      // the deploy's readers never print a bare "warm" for a repository whose
+      // running container the last deploy could not verify.
+      imageReport: map.get(IMAGE_REPORT_PENDING_KEY) !== undefined ? "pending" : "current",
       // Item 22: who holds what, as the rows say — the mirror mutex and the
       // cycle/hydration leases, each judged against this incarnation.
       incarnation: this.incarnation,
@@ -9118,32 +9296,47 @@ async function handleDrain(env: Env, body: Record<string, unknown>): Promise<Res
   return json({ draining: record, planeOutbox: await registryStub(env).getDrainOutbox() });
 }
 
-/** POST /undrain (admin): reopen the fleet. Idempotent — `cleared` says whether
- *  a drain stood. */
+/** POST /undrain (admin): reopen the fleet. Idempotent — `cleared` says
+ *  whether a drain stood and was lifted. With containers still to report the
+ *  deploy's image (issue 1931) the fleet STAYS closed: `held` names them, the
+ *  record stands with the lift asked, and the last container's report reopens
+ *  the fleet — a fact, never a timer; the drain's `until` is the backstop. */
 async function handleUndrain(env: Env): Promise<Response> {
-  const cleared = await registryStub(env).clearDrain();
-  console.log(`[drain] fleet reopened (${cleared ? "a drain stood" : "no drain stood"})`);
-  return json({ draining: null, cleared, planeOutbox: await registryStub(env).getDrainOutbox() });
+  const lift = await registryStub(env).clearDrain();
+  if (!lift.cleared && lift.held.length > 0) {
+    console.log(`[drain] fleet stays closed — containers still to report the deploy's image: ${lift.held.join(", ")}`);
+    const draining = liveDrain(await registryStub(env).getDrain(), systemClock());
+    return json({ draining, cleared: false, held: lift.held, planeOutbox: await registryStub(env).getDrainOutbox() });
+  }
+  console.log(`[drain] fleet reopened (${lift.cleared ? "a drain stood" : "no drain stood"})`);
+  return json({ draining: null, cleared: lift.cleared, planeOutbox: await registryStub(env).getDrainOutbox() });
 }
 
 /** POST /reconcile (drain scope): reconcile every resident's container onto
  *  the current image — the deploy runner posts it after its Worker deploy
  *  landed and BEFORE its `/undrain`, so a stale container restarts inside the
  *  drain window (item 69's order) and never under a run the reopened fleet
- *  admits. Each resident answers what its reconcile decided; a failing one
- *  degrades to `error` without touching its neighbors, and a `deferred` or
- *  failed one restarts on its own next quiet attach or refresh cycle. */
+ *  admits. Each resident answers what its reconcile decided and whether its
+ *  fresh container was VERIFIED on the deploy's image (issue 1931); one not
+ *  verified — deferred, a failed fresh probe, an error — leaves a hold on the
+ *  drain, so the fleet reopens only on that container's later report. */
 async function handleReconcile(env: Env): Promise<Response> {
   const residents = await registryStub(env).list();
   const settled = await Promise.allSettled(
-    residents.map((record) => residentStub(env, record.resource).reconcileForDeploy()),
+    residents.map((record) => residentStub(env, record.resource).reconcileForDeploy(record.resource)),
   );
   const reconciled = residents.map((record, i) => {
     const s = settled[i];
     return s.status === "fulfilled"
-      ? { resource: record.resource, result: s.value.result }
-      : { resource: record.resource, result: "error" as const, error: errMsg(s.reason) };
+      ? { resource: record.resource, result: s.value.result, verified: s.value.verified }
+      : { resource: record.resource, result: "error" as const, verified: false, error: errMsg(s.reason) };
   });
+  // Each resident held ITSELF before its marker (reconcileForDeploy), so no
+  // report can outrun its hold; this pass is the backstop for a resident whose
+  // call rejected before it could — holdDrain deduplicates, so re-holding a
+  // deferred resident changes nothing.
+  const unverified = reconciled.filter((r) => !r.verified).map((r) => r.resource);
+  if (unverified.length > 0) await registryStub(env).holdDrainFor(unverified);
   console.log(`[reconcile] deploy image reconcile: ${JSON.stringify(reconciled)}`);
   return json({ reconciled });
 }

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.255.0",
+  "version": "1.257.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.255.0",
+      "version": "1.257.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -20445,7 +20445,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.255.0",
+      "version": "1.257.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@earendil-works/pi-ai": "0.85.1",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.255.0",
+  "version": "1.257.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",
@@ -39,9 +39,9 @@
     "cli": "tsx src/cli.ts",
     "verify": "npm run verify:root && npm run verify --workspaces --if-present && npm run check:site",
     "verify:root": "npm run check:consistency && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:dist",
-    "check:consistency": "npm run check:lockfile && npm run check:sandbox-pair && npm run skills:check && npm run check:deps-drift && npm run licenses:check && npm run docs:check && npm run pr-title:check && npm run specs:check && npm run decisions:check && npm run hygiene:check && npm run check:project-facts && npm run check:registry-drift && npm run agents:check && npm run clock:check && npm run screenshots:check",
+    "check:consistency": "npm run check:lockfile && npm run check:sandbox-pair && npm run skills:check && npm run check:deps-drift && npm run licenses:check && npm run docs:check && npm run pr-title:check && npm run specs:check && npm run decisions:check && npm run hygiene:check && npm run vocabulary:check && npm run check:project-facts && npm run check:registry-drift && npm run agents:check && npm run clock:check && npm run screenshots:check",
     "ci:gate": "node scripts/ci-gate.mjs",
-    "fix": "npm run docs:gen && npm run pr-title:gen && npm run agents:gen && npm run clock:gen && npm run hygiene:gen && npm run deploy:gen && npm run skills:sync && npm run lint:fix && npm run format",
+    "fix": "npm run docs:gen && npm run pr-title:gen && npm run agents:gen && npm run clock:gen && npm run hygiene:gen && npm run vocabulary:gen && npm run deploy:gen && npm run skills:sync && npm run lint:fix && npm run format",
     "deploy:gen": "npm run --silent cli -- deploy init",
     "deploy:check": "npm run --silent cli -- deploy init --check",
     "check:lockfile": "node scripts/check-lockfile.mjs",
@@ -73,6 +73,8 @@
     "decisions:check": "tsx scripts/decisions-check.ts",
     "hygiene:check": "node scripts/public-hygiene.mjs",
     "hygiene:gen": "node scripts/public-hygiene.mjs --write",
+    "vocabulary:check": "node scripts/vocabulary-check.mjs",
+    "vocabulary:gen": "node scripts/vocabulary-check.mjs --write",
     "docs:changed": "node scripts/docs-changed.mjs",
     "deploy:targets": "node scripts/deploy-targets.mjs",
     "docs:dev": "npm run dev -w docs --",

package/dist/assets/project.json

@@ -32,7 +32,7 @@
   "commands": {
     "$comment": "What each root npm script does and when to run it — the source of the Commands table in AGENTS.md (npm run agents:gen). A script without an entry fails agents:check, so a new script cannot ship undocumented.",
     "verify": {
-      "does": "The whole gate: every root check, every workspace's verify, the site check — exactly what CI runs.",
+      "does": "The whole gate: every check, every workspace — exactly what CI runs.",
       "when": "Local sessions, before requesting review. ~4 min. A pipeline agent leaves it to CI."
     },
     "verify:root": {
@@ -40,11 +40,11 @@
       "when": "When only the bot changed."
     },
     "check:consistency": {
-      "does": "The sub-second checks that generated and declared things equal the code (lockfile, sandbox pairs, skills, licenses, docs tables, specs, project facts, this table).",
+      "does": "The sub-second checks that generated and declared things equal the code, this table included.",
       "when": "After touching a generated or declared artifact; one CI leg."
     },
     "test": {
-      "does": "The whole vitest suite (bot, web, the plain-Node Worker tests) from one entry, after `deploy:gen`.",
+      "does": "The whole vitest suite from one entry, after `deploy:gen`.",
       "when": "Local sessions, before pushing; a pipeline agent runs the changed set — the full suite is CI's."
     },
     "typecheck": {
@@ -160,21 +160,29 @@
       "when": "After renaming a test or editing a spec; `-- --fix` makes truncated titles explicit."
     },
     "specs:coverage": {
-      "does": "Maps a change's paths to the specs whose `Code`/`Tests` headers cover them, then lists changed source paths no spec covers.",
+      "does": "Maps a change's paths to the specs whose headers cover them, then lists paths no spec covers.",
       "when": "`-- --changed origin/main...HEAD [--test-guard]` before review; `-- --require` fails on an uncovered path; `-- --json` for machines."
     },
     "decisions:check": {
-      "does": "Every record under `docs/decisions/` and `docs/plans/` has a valid `status`, a superseded one names its successor, an accepted body only gains an appended `## Amended`.",
-      "when": "Part of `check:consistency`; a failing record is superseded or amended by appending, never edited."
+      "does": "Every record under `docs/decisions/` and `docs/plans/` has a valid `status`, a superseded one names its successor, an accepted body only gains `## Amended`.",
+      "when": "Part of `check:consistency`; a failing record is superseded or amended, never edited."
     },
     "hygiene:check": {
       "does": "The public tree's imprint (company, people, trackers, plan ids, ids, dates) equals the recorded list, which only shrinks.",
-      "when": "Part of `check:consistency`. New hit: rewrite the line or allow it in `scripts/public-hygiene.allow`."
+      "when": "Part of `check:consistency`. New hit: rewrite the line or allow it by name."
     },
     "hygiene:gen": {
       "does": "Records the tree's remaining imprint after a scrub; refuses growth unless `-- --force`.",
       "when": "Part of `fix`; new imprint fails it like `hygiene:check`."
     },
+    "vocabulary:check": {
+      "does": "No internal word prints on a user surface; the baseline only shrinks.",
+      "when": "Part of `check:consistency`; a hit is rewritten in the user's nouns."
+    },
+    "vocabulary:gen": {
+      "does": "Records the remaining internal words; refuses growth unless `-- --force`.",
+      "when": "Part of `fix`."
+    },
     "agents:gen": {
       "does": "Writes the Commands table in AGENTS.md from `package.json` and this file.",
       "when": "After adding or changing a script; part of `fix`."
@@ -220,8 +228,8 @@
       "when": "After a `web/` change."
     },
     "screenshots:gen": {
-      "does": "Renders the dashboard screenshots whose inputs changed, both themes, recording each surface's input hashes in `docs/public/screenshots/manifest/` (`--force`: all).",
-      "when": "After a `web/` or fixture change, once `screenshots:check` names it; needs `npx playwright-core install chromium`, so not in `fix`."
+      "does": "Renders the dashboard screenshots whose inputs changed, both themes, recording input hashes in the manifest (`--force`: all).",
+      "when": "After a `web/` or fixture change; needs `npx playwright-core install chromium`, so not in `fix`."
     },
     "screenshots:check": {
       "does": "Each surface's inputs still hash to what its screenshots were rendered from — no browser.",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.255.0",
-  "commit": "b19caf8a347aca9f78503cac8525f3b3206ba2ff",
-  "builtAt": "2026-09-20T02:32:25.817Z"
+  "version": "1.257.0",
+  "commit": "222646c5fe1a6686c238020f6571c69c3ab87e43",
+  "builtAt": "2026-09-20T15:27:11.679Z"
 }

package/dist/assets/src/agents/registry.ts

@@ -254,6 +254,48 @@ Keep notes with the \`notes\` tool: one short document, replaced whole each time
 // classes are by duration, the project's own scripts and CI say which is which.
 export const CHECKS_BY_COST = `CHECKS BY COST — push before the expensive ones. Every check you might run has a cost class: seconds (a formatter or a linter on the files you touched, one test file, a docs, link or spec check, the typecheck of one package) or minutes (the whole test suite, a build, a dependency install, an end-to-end or full verification). Know a command's class before you run it — from the project's own scripts and CI configuration, from how long it took last time, or by the class above when you have nothing better. Prove each change with the cheapest check that can prove it, matched to the change's scope and scoped to the changed set — the tests nearest your change, the touched project's typecheck, the changed files' formatting, never the whole tree: a documentation change gets the documentation checks, one module gets its own tests, a shared type gets the typecheck. Every CI pipeline runs the tests, the types, the formatting and the full verification on your push, so you never run them again: you validate and fix your own change before pushing, at the changed-set scope. Passing the full test suite and the full typecheck is NOT part of your criteria: CI is that gate and the only place they run — on a shared machine they cost minutes that every other run pays for. As soon as the change exists and those checks pass, commit and push — the pushed branch is the deliverable, and an unpushed tree does not survive the run's end. Beyond the changed set, use judgement about what this change needs rather than a checklist, fixing forward with further commits and pushes. Never start an operation whose expected duration does not fit the time you have left minus what a commit, a push and the description need: push what there is and say plainly what is unverified instead. At the wind-down note, commit and push what compiles, say what does not, then answer. ${TIMEOUT_ON_LONG_COMMANDS} The description's validation names exactly what ran; what did not run is CI's to gate, and you say so.`;
 
+// Every coding prompt carries this verbatim, right after the checks-by-cost
+// rule (docs/reference/specs/agent-coding.md item 13; issue 1796): the fast
+// gates before every push, each the changed-set form with its command named,
+// and the full verification named as CI's gate. The paragraph lived in the
+// ship contract's first instruction alone, so every ask that was not a plan
+// unit had to repeat it by hand or watch the run spend most of its budget on
+// the whole suite or the full verification before its first push (issue 1909
+// measured three such command shapes at 85–95 % of a child's life). One
+// constant, one text: the three coding variants carry the same bytes, the
+// contract's first instruction points here instead of re-stating it
+// (src/core/ship/contract.ts), and no requester repeats it. Unlike the
+// checks-by-cost rule above, this paragraph names its commands on purpose —
+// children handed only the classes chose wrong in both directions — and a
+// repository on another stack maps each gate by its class.
+export const TOUCHED_TESTS_COMMAND = "`npx vitest run` on the test files you touched, by name,";
+
+export const FAST_GATES_BEFORE_PUSH =
+  "THE FAST GATES, before every push — each scoped to the changed set, never the whole project: " +
+  `${TOUCHED_TESTS_COMMAND} once (never \`--changed\`, never a directory: on a moving base that is most of the suite), ` +
+  "`tsc --noEmit -p` the touched tsconfig under `NODE_OPTIONS=--max-old-space-size=6144`, " +
+  "`npx prettier --check` on the changed files, `npm run hygiene:check` and `npm run specs:check` — " +
+  "then your judgement on what else this change needs, not a longer checklist. The full verification is " +
+  "CI's gate — `npm run verify` runs there on your push, never here: push a head early and let CI judge it, " +
+  "fixing forward with further commits and pushes.";
+
+// Every coding prompt carries this verbatim, right after the fast gates
+// (agent-coding item 13; record 0071 mechanism one, issue 1747): the rebase
+// before every push, always and never configurable. Approved pull requests
+// went stale behind sibling merges and each needed a hand-posted rebase; a
+// rebase against a base the run just fetched, with the change's context still
+// in its window, is the cheapest rebase the system will ever run, so it is
+// unconditional. One constant, one text: the three coding variants carry the
+// same bytes — a ship fix round's child runs these same prompts — and the ship
+// contract's first instruction points here instead of re-stating it
+// (src/core/ship/contract.ts).
+export const REBASE_BEFORE_PUSH =
+  "REBASE BEFORE EVERY PUSH — always, not configurable. Immediately before each push: fetch your base branch, " +
+  "rebase your branch onto it, resolve any conflict with the context you already have (the repository's " +
+  "AGENTS.md says how a generated file is regenerated — regenerate it, never hand-merge it), re-run THE FAST " +
+  "GATES on the rebased tree, and only then push. Every head that reaches review is then current with its " +
+  "base when it lands, and no unit ends merge-ready behind a sibling that merged first.";
+
 const CODING_SYSTEM = `You are Switchboard's coding agent, operating from a Slack request.
 
 You work inside a dedicated workspace directory with bash, read_file, and write_file tools. ${SANDBOX_TOOLCHAIN}
@@ -276,6 +318,10 @@ Workflow for shipping a PR:
 
 ${CHECKS_BY_COST}
 
+${FAST_GATES_BEFORE_PUSH}
+
+${REBASE_BEFORE_PUSH}
+
 ${NEVER_MERGE}
 
 ${UNIT_CONTRACT}
@@ -323,6 +369,10 @@ Workflow for shipping a change:
 
 ${CHECKS_BY_COST}
 
+${FAST_GATES_BEFORE_PUSH}
+
+${REBASE_BEFORE_PUSH}
+
 ${NEVER_MERGE}
 
 ${UNIT_CONTRACT}
@@ -366,6 +416,10 @@ Workflow for shipping a change:
 
 ${CHECKS_BY_COST}
 
+${FAST_GATES_BEFORE_PUSH}
+
+${REBASE_BEFORE_PUSH}
+
 ${NEVER_MERGE}
 
 ${UNIT_CONTRACT}
@@ -558,7 +612,7 @@ Your tools work without a workspace: the GitHub tools — \`github_repos\` (the
 
 ${statusCardRule('"Read the issue and its thread", "Post the comment"')} A one-step answer needs no checklist; post one when the request has steps the person would wait on.
 
-You cannot run commands, clone repositories, edit code, or review pull requests, and you cannot search the web — and you cannot hand off, route, forward or start another run: never say you will hand off, route, forward or start anything, because you cannot start another agent's run. Other Switchboard agents can do those things, and a plain message reaches them by itself — but only a new top-level message in the channel reaches the router; a reply in this thread comes back to you. For a code change or a pull request, say what you found and that the change is not yours to make, and that asking for it in plain words in a new top-level message in the channel — not a reply in this thread — like "in acme/api: fix the failing login test" starts the agent that makes the change, opens the PR and loops review; the same for a PR review ("review <PR URL>") and a web-research question ("compare X and Y on the web"). Never hand back a command or an \`agent:…\` line for the person to type: describe the ask in their words. Delete an issue only when the user explicitly asked to delete it (closing is an update).`;
+You cannot run commands, clone repositories, edit code, or review pull requests, and you cannot search the web — and you cannot hand off, route, forward or start another run: never say you will hand off, route, forward or start anything, because you cannot start another agent's run. Other Switchboard agents can do those things, and a plain message reaches them by itself: Switchboard's door reads every message — a reply in this thread included — and starts the right agent from the person's own words. For a code change or a pull request, say what you found and that the change is not yours to make, and that asking for it in plain words — right here in the thread or anywhere in the channel, like "in acme/api: fix the failing login test" — starts the agent that makes the change, opens the PR and loops review; the same for a PR review ("review <PR URL>") and a web-research question ("compare X and Y on the web"). NEVER tell the person to post a new top-level message, re-post, re-ask elsewhere or retype their request — their words have already been said and the door reads thread replies; and never hand back a command or an \`agent:…\` line to type: describe the ask in their words. Delete an issue only when the user explicitly asked to delete it (closing is an update).`;
 
 // The explore agent (docs/reference/specs/agent-explore.md): a long, read-only
 // investigation — "run our CI locally and validate the claims", "how long does

package/dist/assets/src/core/authz/grants.ts

@@ -13,6 +13,18 @@ import { NO_GRANTS, type Grants, type GrantSet } from "./types.js";
 /** Every grant, on every axis. What admins and the local CLI hold. */
 export const ALL_GRANTS: Grants = Object.freeze({ actions: "all", channels: "all", repos: "all" });
 
+/** The plane's system actor (record 0064; record 0057 as amended): the run
+ *  ledger object steers write-preset runs itself — the checkpoint steer and the
+ *  held turn's reissue land as `run_inbox` rows with sender `plane` — under
+ *  this one standing grant. Recorded here so the table stays the whole story:
+ *  the write happens on the object, which holds no other authority. */
+export const PLANE_ACTOR_ID = "plane";
+export const PLANE_GRANTS: Grants = Object.freeze({
+  actions: new Set(["steer:write"]),
+  channels: "all",
+  repos: "all",
+});
+
 /** The namespaces a native `grants` key may use (invariant 4). `cli:` is not
  *  configurable (the local CLI always holds everything) and `agent:` actors
  *  derive their grants from their principal, so neither is listed. */