borgmcp 3.11.1 → 3.12.0

package/docs/RELEASING.md

@@ -8,8 +8,9 @@ npm Trusted Publishing; no long-lived npm token is stored or exposed.
 ## Release Integrity
 
 Release provenance is established by protected annotated tags, GitHub build
-provenance, and npm Trusted Publishing. Tags and publication workflows are
-immutable: never move, replace, reuse, or rerun them.
+provenance, and npm Trusted Publishing. Never move, replace, or reuse a tag.
+A failed workflow may be rerun until npm accepts a stage; stage acceptance
+consumes the version.
 
 ## Release Prerequisites
 
@@ -20,19 +21,15 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.11.0` remains locked to
+- the exact audited registry dependency `borgmcp-shared@0.12.2` remains locked to
   its canonical tarball and integrity
-  `sha512-I8mixCbSrLKyOAAyqEI/HZJ8cML2rz3r812Up8pr547OdAk9LxZevdCo7ojG42ZwrUmS5u7iKQPg7Vk1XvtX1g==`;
-- the coupled shared/server/client candidates have all been built against the
-  same exact `borgmcp-shared` version and passed the complete local dogfood gate
-  before any stage is approved;
+  `sha512-l459XEeqk0cSz1+Z8yk8cCVWik4/CX4OBTRZqj6n1SZYvDpzWJksUz82FA9k4taf//rs43Tfl1tpWXnRHAqxOQ==`;
+- the coupled shared/server/client candidates use the same exact
+  `borgmcp-shared` version;
 - the selected stable client version is unused and the exact release commit is
   on protected `main`;
 - the repository and protected npm environment settings pass an operator audit;
-- the exact release source passes Code Review, Security Review, Release Quality,
-  extraction, and package gates; and
-- the immutable annotated tag and publication receive explicit release
-  authorization.
+- the exact release source passes exact-SHA CI and one Code Review.
 
 `scripts/verify-release-readiness.mjs` makes the source-side blockers
 machine-checkable. A release tag created before they are resolved fails before
@@ -41,18 +38,19 @@ dependency installation or publication.
 ### Release branches
 
 Release branches use the `release/` prefix and enter protected `main` through a
-pull request. Direct pushes only update staging branches; publication still
-requires the complete protected release gate.
+pull request. After exact-SHA CI and one Code Review, merge the preparation and
+create its annotated version tag. The tag automatically verifies and stages the
+package.
 
 ## Repository Controls
 
 Repository settings are operator-owned and are not changed by this workflow.
 Before preparing a candidate, independently verify:
 
-1. The `npm-publish` environment disables administrator bypass, requires the
-   reviewed human approver, and allows only the protected release refs. Its
-   `NPM_EXPECTED_OWNER` variable must match the sole reviewed maintainer of the
-   existing `borgmcp` package. It must contain no npm token.
+1. The `npm-publish` environment disables administrator bypass, has no required
+   reviewer, and allows only `v*.*.*` tags. Its `NPM_EXPECTED_OWNER` variable
+   must match the sole reviewed maintainer of the existing `borgmcp` package.
+   It must contain no npm token.
 2. npm Trusted Publishing is configured for organization `Byte-Ventures`,
    repository `borg-mcp-client`, workflow `publish.yml`, and environment
    `npm-publish`. Its allowed actions enable `npm stage publish` and disable
@@ -69,212 +67,8 @@ Before preparing a candidate, independently verify:
 
 ## Release Workflow
 
-### Clean-environment rig lifecycle
-
-Every clean-environment verification rig has an explicit identity and an
-explicit end-of-life. Run it from a Borg-launched session and keep filesystem
-workspaces under the exact disposable scratch root Borg exports. Give each
-workspace a name beginning with `borg-rig-` followed by its owner, purpose, and
-a unique suffix. Before the first command that can create files, anchor the rig
-as its own npm project:
-
-```sh
-BORG_SCRATCH_ROOT="${BORG_LAUNCH_SCRATCH:?run from a Borg-launched session}"
-RIG_OWNER="$(basename "$BORG_SCRATCH_ROOT")"
-RIG_NONCE="${RIG_NONCE:-$(date +%Y%m%d%H%M%S)-$$}"
-RIG_ID="borg-rig-${RIG_OWNER}-release-${RIG_NONCE}"
-RIG_ROOT="$BORG_SCRATCH_ROOT/$RIG_ID"
-mkdir -p "$RIG_ROOT"
-printf '%s\n' '{"private":true}' > "$RIG_ROOT/package.json"
-```
-
-The manifest anchor is required before any `npm install`, `npm update`, or
-other npm command. Without it, npm can walk up from an empty scratch directory
-and write the operator's `package.json` instead of creating project-local
-state. In a source checkout, the committed `release:exercise` follows this rule
-for its temporary consumer; other QA scripts and manual rigs must do the same.
-
-The system temporary root is shared with the whole machine, so an unbounded
-listing there is not an inspectable cleanup check. Bound that leg by the
-invoking user and the run-window markers, which select directories whose
-timestamps fall within this run window without requiring a prefix inventory.
-New `mkdtemp` prefixes therefore require no documentation change. Keep both
-time predicates and the ownership predicate: removing the run-window bound
-turns a populated shared temp root back into an uninspectable listing.
-
-On a machine where several runs share one user account, this listing can
-include another run's live workspace. Removal is scoped to paths created by
-this run; anything else in the output is reported, not deleted. Unrelated
-same-user temporary directories created during the window can therefore
-appear in the result, so never remove a path merely because this listing found
-it.
-
-```sh
-TEMP_ROOT="${TMPDIR:-/tmp}"
-TEMP_OWNER="$(id -un)"
-TEMP_SCAN_START="$TEMP_ROOT/.${RIG_ID}-temp-scan-start"
-TEMP_SCAN_END="$TEMP_ROOT/.${RIG_ID}-temp-scan-end"
-
-list_recent_owned_temp_rigs() {
-  find "$TEMP_ROOT" -mindepth 1 -prune \
-    -type d \
-    -user "$TEMP_OWNER" \
-    -newer "$TEMP_SCAN_START" \
-    ! -newer "$TEMP_SCAN_END" \
-    -print
-}
-
-touch "$TEMP_SCAN_START"
-```
-
-Container-backed rigs use the same `RIG_ID` as the container name and carry
-both labels below. Register exact-target cleanup before launching the rig:
-
-```sh
-list_owned_rig_containers() {
-  docker container ls --all \
-    --filter label=borg-rig=1 \
-    --filter "label=borg-rig-owner=${RIG_OWNER:?}" \
-    --format '{{.ID}}\t{{.Names}}\t{{.Status}}'
-}
-
-cleanup_done=0
-cleanup() {
-  [ "$cleanup_done" -eq 0 ] || return
-  cleanup_done=1
-  trap - EXIT HUP INT TERM
-  docker container rm --force "$RIG_ID" >/dev/null 2>&1 || true
-  rm -rf -- "$RIG_ROOT"
-  list_owned_rig_containers
-  find "$BORG_SCRATCH_ROOT" -mindepth 1 -print
-  find "$BORG_SCRATCH_ROOT" -name 'borg-rig-*' -print
-  if [ -e "$TEMP_SCAN_START" ]; then
-    touch "$TEMP_SCAN_END"
-    list_recent_owned_temp_rigs
-  fi
-  rm -f -- "$TEMP_SCAN_START" "$TEMP_SCAN_END"
-}
-trap cleanup EXIT
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-```
-
-List containers and scratch paths before starting. The filters distinguish this
-session's rigs from unrelated containers on a shared host:
-
-```sh
-list_owned_rig_containers
-find "$BORG_SCRATCH_ROOT" -mindepth 1 -print
-find "$BORG_SCRATCH_ROOT" -name 'borg-rig-*' -print
-```
-
-Only after the cleanup traps and pre-launch listings are in place, launch a
-container-backed rig. `--rm` is preferred; a runtime without automatic removal
-must remove the exact `RIG_ID` in its cleanup path and retain the labels for a
-bounded sweep:
-
-```sh
-RIG_IMAGE="${RIG_IMAGE:?set the rig image}"
-docker run --rm \
-  --name "$RIG_ID" \
-  --label borg-rig=1 \
-  --label "borg-rig-owner=$RIG_OWNER" \
-  "$RIG_IMAGE"
-```
-
-The unfiltered filesystem listings expose legacy names as well as conforming
-rigs. The bounded temporary-directory function reports same-user directories
-created during the run window, including unrelated work; it does not establish
-which process owns them. The cleanup path runs the container and scratch
-listings after removing this rig, then runs the bounded temporary-directory
-listing between the start and end markers. Inspect and report its results. If a
-rig creates an exact system-temporary path, record that path when it is created
-and remove that exact path during cleanup; never remove a path solely because
-the bounded listing found it.
-
-Register cleanup before launching any process, run it on success and failure,
-and do not deliver a verdict until the container listing and both scratch
-listings show no rig owned by this run, every exact system-temporary path
-recorded by the rig has been removed, and the bounded temporary-directory
-listing has been inspected and reported. For a non-`--rm` container runtime,
-remove only the named rig or the same owner label; never prune unrelated
-containers. A completed verification
-therefore implies zero running or stopped rig containers and no rig workspace
-created by this run left in either the session scratch root or any exact
-system-temporary path the rig recorded.
-
-### Pre-tag composed exercise
-
-Before creating a release tag, exercise the packed client against the selected
-server artifact:
-
-```sh
-npm run release:exercise -- \
-  --server /absolute/path/to/borgmcp-server.tgz \
-  --server-integrity 'sha512-...'
-```
-
-The server integrity must come from the reviewed producer of that artifact. Run
-the command once with the published counterpart. When the client and server are
-being released together, run it again with the co-releasing server candidate.
-The default path builds and packs the current client; `--client-tarball` exists
-only for reproducing a reviewed packed client or running a negative control.
-
-This harness exercises reviewed release candidates and their published
-counterparts. It is not a containment sandbox for hostile or otherwise untrusted
-packages and must not be used as one. The temporary install and data directories
-isolate the reviewed exercise from normal product state; they are not an
-operating-system security boundary.
-
-The harness requires Node.js 22, npm 11.18.0, Python 3, and macOS or Linux. It
-installs both tarballs into a private temporary project, bootstraps isolated
-server data, and starts the installed server directly. It never uses
-`borg server setup`, because registry-backed activation would select the
-previously published server instead of a candidate.
-
-Both composed terminal journeys run under a real PTY:
-
-- `borg server dashboard` must render the attached-viewer footer, exit cleanly
-  on Ctrl-C, restore the cursor and alternate screen, and leave the server's
-  pinned-TLS process healthy at `GET /healthz` (204, empty body).
-- `borg server start` must render the foreground-server footer, exit cleanly on
-  Ctrl-C, restore the terminal, stop the server, and release its health endpoint.
-
-The client facade resolves `borg-mcp-server` by bare name. The harness therefore
-uses a controlled shim only to arrange resolution, then verifies the outcome:
-before trusting a frame, it reads the live process command and requires the
-absolute installed server entry. Every client or server executable must resolve
-inside the installed package root covered by the SRI cited for that role. Its
-JSON report records the absolute path, version, and independently supplied
-integrity for the client, dashboard listener, dashboard viewer, and foreground
-listener/viewer roles. PATH ordering alone is never accepted as identity evidence.
-
-The harness is a fail-closed release gate. A missing frame, non-PTY execution,
-wrong journey footer, substituted artifact, nonzero exit, absent terminal
-restore sequence, failed post-exit health assertion, timeout, or oversized
-transcript fails the command. Its controls must remain demonstrably bidirectional:
-the current client/server pairing passes; and a deliberately wrong server
-integrity fails before either journey starts.
-
-The terminal-restore negative control is specifically the packed pre-#146 client
-from commit `81da7b970ffb4e76a35c7bc551c419fec702a3b6` composed with published
-`borgmcp-server@0.2.0`, registry integrity
-`sha512-squb0+vdy0q7l/4FeV7OTvSm7OiFWGsAjGhcVEXYrQc9K/8jJYduqPS90VBwaJRT6z221Gxf3xQ5SeZe/Qoncw==`.
-That composition must fail on the missing cursor-restore sequence. A newer server
-candidate can mask the old client's defect and is not a valid counterpart for
-this negative control.
-
-```sh
-npm run release:exercise -- \
-  --server borgmcp-server@0.2.0 \
-  --server-integrity 'sha512-squb0+vdy0q7l/4FeV7OTvSm7OiFWGsAjGhcVEXYrQc9K/8jJYduqPS90VBwaJRT6z221Gxf3xQ5SeZe/Qoncw==' \
-  --client-tarball /absolute/path/to/pre-146-borgmcp-2.1.1.tgz
-```
-
 The only trigger is a protected annotated `v<package version>` tag. Manual
-dispatch is intentionally absent so a second run cannot rebuild or publish an
-existing tag. The workflow rejects reruns, root `.npmrc`
+dispatch is intentionally absent. The workflow rejects root `.npmrc`
 configuration, non-tag events, lightweight or malformed tags, version mismatch,
 source/tag mismatch, and tags whose commits are not on protected `main`.
 
@@ -283,7 +77,8 @@ The unprivileged `verify` job performs one sequence:
 1. Verify the public-source boundary, extraction readiness, exact shared-package
    pin, and canonical registry lock metadata.
 2. Install the lockfile once with lifecycle scripts disabled and audit it.
-3. Run type checks, tests, and one readable build; reject generated `dist` drift.
+3. Run one readable build and reject generated `dist` drift. Tests already ran
+   in CI on the exact source.
 4. Produce one npm tarball.
 5. Verify that tarball once for package identity, license/notice, source and map
    completeness, executable bins, archive safety, dependency integrity, and
@@ -294,14 +89,6 @@ The unprivileged `verify` job performs one sequence:
 7. Upload only the tarball and its verifier-generated report as the same-run
    release artifact.
 
-After `verify` succeeds, the designated Queen operator alone approves the
-`npm-publish` environment. There is no separate pre-stage exact-artifact
-Security gate: the verify job is the mechanical authority for the exact bytes
-that the stage job consumes. Environment approval authorizes submitting those
-bytes to npm's private staged-publishing service; it does not make the version
-public, permit a rerun or rebuilt artifact, or authorize approval by another
-actor.
-
 The protected `publish` job alone receives `id-token: write`. It downloads the
 same-run artifact and rejects a report whose package name or version differs
 from the release, a version that already exists, an unclaimed package, or an
@@ -313,48 +100,15 @@ package.
 
 Successful completion of the workflow means npm accepted the immutable staged
 tarball. It does not mean the version is public. Stage acceptance consumes the
-tagged attempt and version under the burned-version rule, but must not trigger
+version, but must not trigger
 release announcements, issue closure, consumer pins, site synchronization, or
 claims that the version was published. There is no workflow registry readback:
 stage inspection and approval require an interactive npm identity and cannot use
 the workflow's OIDC credential.
 
-### Coupled stage approval
-
-Before approving anything, the operator requires successful stage workflows for
-`borgmcp-shared`, `borgmcp-server`, and `borgmcp`. Use authenticated
-`npm stage list` and `npm stage view <UUID>` to record and inspect all three stage
-UUIDs and verify each package, version, and eventual `latest` tag. For every
-package, `npm stage download <UUID>` is mandatory; compute its SHA-512 SRI and
-require an exact match with that workflow run's same-run artifact report. Bind
-the source annotated tag object, commit, and workflow run separately from GitHub
-evidence, because npm stage inspection does not expose them. Exercise the exact
-downloaded coupled set before approval. Confirm that public `latest`, public
-`versions`, and client update resolution still expose the prior coherent release
-set. If a pending stage appears on any public surface, approve nothing and halt
-this mechanism before consumers can observe it.
-
-Approve the verified UUIDs in one operator session, using interactive 2FA, in
-this exact order:
-
-1. `npm stage approve <shared-stage-uuid>`
-2. `npm stage approve <server-stage-uuid>`
-3. `npm stage approve <client-stage-uuid>`
-
-The approvals are not atomic. Shared approval leaves existing client and server
-pins coherent. Server approval opens a bounded mismatch window between public
-server `latest` and client `latest`; client approval closes it. After an approval
-returns successfully, continue only while the next stage remains valid. For an
-ambiguous result, inspect authenticated stage state and canonical public package
-version/integrity before acting; never repeat an approval blindly.
-
-The terminal release boundary is successful interactive stage approval followed
-by canonical registry visibility, integrity verification, and registry
-provenance-attestation inspection. Stage inspection cannot establish provenance
-before approval; Trusted Publishing carries it to the live package, where the
-registry attestation is authoritative. Only then may the release be announced,
-issues closed, consumer pins or site data synchronized, or the version described
-as published.
+Inspect the npm stage, then approve it interactively. This stage approval is the
+sole human publication boundary. Confirm canonical live package visibility and
+integrity before announcing the release or updating dependent packages.
 
 After all three packages cross that boundary, create their GitHub Releases in
 the same shared → server → client operator session. In each package repository,
@@ -364,46 +118,16 @@ run:
 GITHUB_TOKEN="$(gh auth token)" node scripts/create-github-release.mjs <version>
 ```
 
-The script binds the annotated tag, merged release pull request, successful tag
-workflow artifact, and live npm integrity before creating the Release. It copies
-the merged release pull request body verbatim and refuses an existing Release.
-
-Separately, once the release is installable from the canonical registry, install
-it into an isolated prefix and exercise the real user update path end to end.
-This is product verification, not candidate validation: failure routes a new
-reviewed fix and never invalidates, rebuilds, retags, or reruns the immutable
-release. Do not repeat byte comparisons, packed-version checks, source-tree
-verification, dist-tag readback, or provenance reconstruction that the
-exact-artifact `verify` and stage jobs already completed. The canonical
-live-version integrity check is required because it establishes the approval
-boundary; it is not a duplicate candidate verification.
-
-No separate checksum file is needed: the tarball verifier records canonical
-SHA-512 SRI in the artifact report. GitHub's same-run artifact transport and the
-report bind the reviewed candidate without repeated SHA512 choreography.
-
-Rely on npm Trusted Publishing. Perform the one authoritative registry
-provenance-attestation inspection at the approved-live boundary; do not
-reconstruct DSSE, in-toto, SLSA, workflow-ref, or builder statements locally or
-add redundant provenance readback.
-Do not add cross-run tuple variables, cross-run artifact selection, duplicate
-builds, duplicate package verification, checksum bundles, or SBOM ceremony.
+The script binds the annotated tag, live npm package and integrity, and Release
+absence before creating the Release. It reads
+the curated `docs/releases/<version>.md` notes from the exact tagged commit,
+renders them under `News and fixes`, and refuses missing or blank notes and an
+existing Release.
 
 ## Stop And Recovery Conditions
 
-Stop when source, settings, ownership, tag, artifact, test, audit, review, or
-authorization evidence is missing or inconsistent. Never move or reuse a failed
-tag, rerun a failed release workflow, overwrite an npm version, unpublish to hide
-a failure, or substitute a local rebuild. Recovery starts from a fresh reviewed
-source change and, after any registry mutation, a separately authorized version.
-
-Before any approval, missing or inconsistent stage evidence means approve none.
-Reject all three stages only when abandoning the coupled candidate; Borg treats
-every rejected or unusable tagged stage as burned, even though npm permits some
-re-staging. Replacement versions require fresh review, tags, and stage runs.
-After shared approval but before server approval, stopping is compatibility-safe
-for the existing client/server pair, but shared is immutable and any repair uses
-fresh versions. After server approval, prioritize the already-verified client
-approval because the public pair is mismatched. If that client stage cannot be
-approved, do not reject it or rerun the tag; prepare newly reviewed matching
-server/client recovery versions and state the live mismatch window explicitly.
+Stop when source, settings, ownership, tag, artifact, test, audit, or review
+evidence is missing or inconsistent. Never move or reuse a tag,
+overwrite an npm version, unpublish to hide a failure, or substitute a local
+rebuild. A pre-stage workflow failure may be rerun against the same immutable
+tag. After npm accepts a stage, recovery uses a fresh reviewed version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,6 +48,7 @@
     "README.md",
     "LICENSE",
     "NOTICE",
+    "THIRD_PARTY_NOTICES.md",
     "SECURITY.md",
     "CONTRIBUTING.md"
   ],
@@ -71,7 +72,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.11.0",
+    "borgmcp-shared": "0.12.2",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/assimilate-deps.ts

@@ -40,6 +40,7 @@ import {
   resumeLocalBorgServerEnrollment,
   sendBorgServerAttach,
 } from './server-handshake.js';
+import { advanceLocalServerCursor } from './local-server-cursor.js';
 import {
   findIncompleteSiblingAttempt,
   observeSeat,
@@ -483,6 +484,16 @@ export function buildDefaultAssimilateDeps(
             );
           }
         }
+        if (prepared.initialLogCursor) {
+          const binding = {
+            origin: apiUrl,
+            trustIdentity: serverTrustIdentity,
+            cubeId: prepared.cube.id,
+            droneId: prepared.drone.id,
+          };
+          await advanceLocalServerCursor(binding, prepared.initialLogCursor);
+          await advanceLocalServerCursor({ ...binding, purpose: 'stream' }, prepared.initialLogCursor);
+        }
         return {
           cube_id: prepared.cube.id,
           drone_id: prepared.drone.id,

package/src/codex-app-wake.ts

@@ -6,7 +6,7 @@ import {
 } from './cubes.js';
 import { CodexAppServerClient } from './codex-app-server.js';
 import { checkCodexBridgeHealthy } from './codex-remote.js';
-import { hasPendingWakeActivity } from './remote-client.js';
+import { hasPendingWakeActivity, hasPendingWakeEntry } from './remote-client.js';
 import {
   BORG_CODEX_REMOTE_WAKE_ENV,
   resolveSessionAgentKind,
@@ -98,6 +98,7 @@ let wakeInFlight = false;
 const pendingWakeRequests: Array<{
   reason: string;
   deliveryIdentity?: string;
+  sourceEntryId?: string;
   deps: CodexWakeDeps;
 }> = [];
 const deliveredWakeKeys = new Set<string>();
@@ -108,6 +109,8 @@ const DELIVERED_WAKE_KEY_CAP = 100;
 // (mid-turn thread) or missed (transient error) into ONE retried-until-delivered
 // drain. The coalesce gate means a burst collapses to one poller, not N.
 let retryDrainInFlight = false;
+const retryDrainSourceEntryIds = new Set<string>();
+let retryDrainHasUnscopedWork = false;
 
 // gh#857 WI-2: timestamp of the last SUCCESSFUL wake delivery (per-entry OR
 // retry-drain OR heartbeat). The heartbeat reads this (shouldFireHeartbeat) to
@@ -192,6 +195,7 @@ export interface CodexWakeDeps {
   // Per-entry and retry-drain paths do not use this: their pending obligation is
   // already established by a concrete delivered/deferred event.
   hasPendingWork?: (active: ActiveCube) => Promise<boolean>;
+  hasPendingEntry?: (active: ActiveCube, entryId: string) => Promise<boolean>;
   // gh#861 finding 2: lease-ownership gate for the heartbeat tick — a lease-LOSING
   // duplicate child must NOT tick/inject (symmetry with the per-entry path, which
   // only fires inside an SSE session that holds the stream lease). Heartbeat-only;
@@ -280,10 +284,11 @@ export function wakeCodexViaAppServer(
   env: NodeJS.ProcessEnv = process.env,
   deps: CodexWakeDeps = {},
   deliveryIdentity?: string,
+  sourceEntryId?: string,
 ): void {
   const target = resolveCodexWakeTarget(env);
   if (!target.enabled) return;
-  pendingWakeRequests.push({ reason, deliveryIdentity, deps });
+  pendingWakeRequests.push({ reason, deliveryIdentity, sourceEntryId, deps });
   if (wakeInFlight) return;
 
   wakeInFlight = true;
@@ -295,21 +300,30 @@ export function wakeCodexViaAppServer(
 async function drainCodexWakeQueue(): Promise<void> {
   while (pendingWakeRequests.length > 0) {
     const request = pendingWakeRequests.shift()!;
-    await wakeCodexTargeted(request.reason, request.deliveryIdentity, request.deps);
+    await wakeCodexTargeted(
+      request.reason, request.deliveryIdentity, request.sourceEntryId, request.deps,
+    );
   }
 }
 
-async function wakeCodexTargeted(reason: string, deliveryIdentity: string | undefined, deps: CodexWakeDeps): Promise<void> {
+async function wakeCodexTargeted(
+  reason: string,
+  deliveryIdentity: string | undefined,
+  sourceEntryId: string | undefined,
+  deps: CodexWakeDeps,
+): Promise<void> {
   // gh#861 finding 1: another path (heartbeat/retry-drain) is mid-inject into the
   // same thread — defer to the retry-drain so this entry isn't double-injected nor
   // lost (the drain re-syncs the whole burst via the server read-cursor).
   if (!tryAcquireInjectLock()) {
-    scheduleRetryDrain(deps);
+    scheduleRetryDrain(deps, sourceEntryId);
     return;
   }
   try {
     const active = await (deps.getActiveCube ?? getActiveCube)();
     if (!active) return;
+    const pendingEntry = deps.hasPendingEntry ?? hasPendingWakeEntry;
+    if (sourceEntryId && !(await pendingEntry(active, sourceEntryId))) return;
     // gh#855: resolve FRESH (live env socket + re-resolved thread), falling back
     // to the launch-recorded file only when the env socket is absent.
     const resolved = await resolveFreshCodexWakeTarget(active, deps);
@@ -326,9 +340,10 @@ async function wakeCodexTargeted(reason: string, deliveryIdentity: string | unde
         // now. Schedule the retry-drain (coalesced, retried-until-delivered) so
         // the burst's entries are drained once the thread goes idle; codex has no
         // on-disk tail fallback like Claude's borg-inbox-monitor.
-        scheduleRetryDrain(deps);
+        scheduleRetryDrain(deps, sourceEntryId);
         return;
       }
+      if (sourceEntryId && !(await pendingEntry(active, sourceEntryId))) return;
       await client.startTurn(threadId, reason);
       rememberDeliveredWake(wakeKey);
       markDelivered(deps);
@@ -340,7 +355,7 @@ async function wakeCodexTargeted(reason: string, deliveryIdentity: string | unde
     // swallowed (the old best-effort drop let a single blip lose an entry).
     // Schedule the retry-drain so the wake is retried-until-delivered; the SSE
     // stream is never broken (this is fire-and-forget).
-    scheduleRetryDrain(deps);
+    scheduleRetryDrain(deps, sourceEntryId);
   } finally {
     releaseInjectLock();
   }
@@ -357,7 +372,9 @@ async function wakeCodexTargeted(reason: string, deliveryIdentity: string | unde
  * (wakeRetryExpired); the gh#857 WI-2 heartbeat is the backstop beyond that.
  * Never throws into the SSE path (fire-and-forget).
  */
-function scheduleRetryDrain(deps: CodexWakeDeps): void {
+function scheduleRetryDrain(deps: CodexWakeDeps, sourceEntryId?: string): void {
+  if (sourceEntryId) retryDrainSourceEntryIds.add(sourceEntryId);
+  else retryDrainHasUnscopedWork = true;
   if (retryDrainInFlight) return; // coalesce: one loop covers all deferred/missed wakes
   retryDrainInFlight = true;
   void runRetryDrainLoop(deps).finally(() => {
@@ -383,6 +400,15 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
     try {
       const active = await (deps.getActiveCube ?? getActiveCube)();
       if (!active) continue; // no active cube yet → keep retrying (until age cap)
+      const pendingEntry = deps.hasPendingEntry ?? hasPendingWakeEntry;
+      for (const entryId of retryDrainSourceEntryIds) {
+        try {
+          if (!(await pendingEntry(active, entryId))) retryDrainSourceEntryIds.delete(entryId);
+        } catch {
+          // Retain the obligation until unread state can be checked.
+        }
+      }
+      if (!retryDrainHasUnscopedWork && retryDrainSourceEntryIds.size === 0) return;
       // gh#855: same FRESH resolution as the per-entry wake, so a stale launch
       // probe can't defeat the retry-drain either.
       const resolved = await resolveFreshCodexWakeTarget(active, deps);
@@ -395,7 +421,13 @@ async function runRetryDrainLoop(deps: CodexWakeDeps): Promise<void> {
         if (thread?.status?.type === 'active') {
           continue; // re-defer: still mid-turn (backoff before next poll)
         }
+        for (const entryId of retryDrainSourceEntryIds) {
+          if (!(await pendingEntry(active, entryId))) retryDrainSourceEntryIds.delete(entryId);
+        }
+        if (!retryDrainHasUnscopedWork && retryDrainSourceEntryIds.size === 0) return;
         await client.startTurn(threadId, CODEX_CATCHUP_PROMPT);
+        retryDrainSourceEntryIds.clear();
+        retryDrainHasUnscopedWork = false;
         markDelivered(deps);
         return; // drain delivered → server read-cursor drains all unread → done
       } finally {
@@ -515,6 +547,8 @@ export function resetCodexWakeForTests(): void {
   deliveredWakeKeys.clear();
   deliveredWakeKeyOrder.length = 0;
   retryDrainInFlight = false;
+  retryDrainSourceEntryIds.clear();
+  retryDrainHasUnscopedWork = false;
   lastDeliveredAt = null;
   heartbeatInFlight = false;
   injectInFlight = false;

package/src/cube-activity-wake-copy.ts

@@ -1,5 +1,5 @@
 export const CUBE_ACTIVITY_RESUME_WAKE_MESSAGE =
-  'Borg cube activity arrived while you were busy. Reading cube messages does not end your current task. Drain `borg_read-log unread_only=true` until caught up, handle actionable entries, then RESUME the interrupted work.';
+  'Borg cube activity arrived while you were busy. Reading cube messages does not end your current task. Drain `borg_read-log unread_only=true` until caught up, handle actionable entries, then RESUME the interrupted work. If the unread drain is empty, resume silently without a liveness post or full regen.';
 
 export function formatCubeActivityWakeMessage(detail: string): string {
   return `${CUBE_ACTIVITY_RESUME_WAKE_MESSAGE}\n${detail}`;