@stravica-ai/digital-operator-pa 0.1.21 → 0.1.22

package/dist/engineering-pa-cli/docs/estate-sync.md

@@ -128,11 +128,74 @@ id/tag is estate-side work, not part of this package.
    proceeds to push. The audit record adds
    `autoResolved: <N>` + `autoResolvedPaths: [...]` to the `ok` line.
 
-   If **any** conflicted path is outside the allowlist,
-   `git rebase --abort` runs and sync exits 2 with status `fail-rebase`
-   as before. Real content conflicts still surface for human resolution;
-   the audit record includes `conflictedPaths: [...]` for the disallowed
-   paths so the on-call has a starting point.
+   If **any** conflicted path is outside the allowlist, the tool
+   attempts **self-heal on rebase-abort** (R2, w-2026-08-12-004, replaces
+   the pre-R2 "abort and wedge" behaviour): estate-sync's own version of
+   each conflicting path is queued to
+   `<repoRoot>/.cache/estate-sync/pending/<pathSlug>__<firstSeenTs>` with
+   a JSON sidecar carrying `originalPath`, `conflictingUpstreamCommitSha`,
+   `upstreamBlobShaAtQueue`, `attemptCount`, `firstSeen`, and
+   `alertLevel`. The pending content is fsynced BEFORE any git mutation
+   runs, so a queue failure never triggers a reset. Then four cascading
+   guards fire (HEAD sha equals the sha recorded immediately after
+   `git commit`; HEAD^ exists; exactly one commit in `HEAD^..HEAD`;
+   exactly one commit ahead of `origin/<branch>`); on any guard failure
+   the tool falls through to the classic `fail-rebase` behaviour and
+   stays wedged loudly. When all guards pass, `git reset --soft HEAD^`
+   drops estate-sync's own commit while leaving BOTH the index and the
+   working tree untouched — every non-conflicting path in the dropped
+   commit stays staged and its bytes stay on disk for the next tick to
+   recommit. Then surgically per conflicting path: newly-added paths get
+   `git rm --cached -- <path>` + `fs.unlink` (unstaged and removed from
+   disk; their bytes live in pending); modified paths get
+   `git checkout HEAD -- <path>` (restored to the parent's version in
+   both index and working tree). The audit record uses one of
+   `fail-rebase-queued` (alertLevel `warn`, attempts < 5),
+   `fail-rebase-stuck` (alertLevel `error`, attempts >= 5), or
+   `fail-rebase-needs-human` (divergence detected during drain) with
+   exit code **0** — the process exits healthy because the workspace
+   itself is fast-forwardable again, while the `fail-*` status routes
+   through librarian-alerts (when wired to estate-sync's runs.jsonl).
+
+   > **Why `--soft` and not `--keep`** (correction landed 2026-08-12 via
+   > the PR-120 fresh-context review): `--keep <ref>` updates the
+   > working tree to match `<ref>` on every file that differs between
+   > HEAD and `<ref>`. In a multi-file estate-sync commit (which is the
+   > design — step 6 scoops every in-scope dirty path), that means
+   > every non-conflicting path in the dropped commit would be silently
+   > destroyed (newly-added files deleted, modifications reverted).
+   > `--soft` leaves the index and working tree entirely alone; the
+   > surgical scope above touches only the conflicting paths, so
+   > non-conflicting content survives across the drop.
+
+   On every subsequent tick, **DRAIN** runs at the top (inside the PID
+   lock, after fetch so `origin/<branch>` refs are fresh), oldest-first.
+   For each pending entry the tool compares the sidecar's
+   `upstreamBlobShaAtQueue` against origin's blob NOW and picks one of
+   three actions:
+   - **`already-delivered`** — upstream's current blob bytes exactly
+     match the pending content (another writer pushed our version for
+     us). Pending removed cleanly, no workspace write.
+   - **`staged-for-retry`** — upstream blob is unchanged since queue
+     time. Copy the pending bytes back into the workspace at
+     `originalPath`; step 6 will stage them and step 7 will rebase
+     normally. Pending removed ONLY after commit + push are confirmed
+     on HEAD (`finaliseDrainOnPushSuccess`); a crash between drain
+     and commit leaves the pending file intact so the next tick
+     re-evaluates.
+   - **`divergence-held`** — upstream now has a DIFFERENT resolution
+     than the sidecar recorded at queue time (a third writer intervened,
+     a human reconciled with different bytes, etc.). The sidecar is
+     stamped `alertLevel: 'needs-human'` (sticky — never de-escalates
+     back to warn or error), and the workspace is NOT touched. This
+     blocks the silent-clobber hazard the earlier ratified drain
+     sketch had, where re-applying stale bytes would overwrite the
+     winner's resolution.
+
+   Pending queue lives at `.cache/estate-sync/pending/`, gitignored per
+   the tooling standard §16. Content-safety invariant: no reset ever
+   runs when the queue write fails, and no workspace write ever happens
+   when upstream has diverged.
 
 ### Registry-scoped commit set
 
@@ -229,7 +292,13 @@ One JSON object per line, camelCase keys (§11 of the tooling standard):
 | `branch` | string | The current branch name. Present on `ok` and `noop-nothing-to-do`. |
 | `autoResolved` | number | Number of allowlisted regenerated-artifact paths auto-resolved during a rebase conflict. `ok` only, present iff > 0. |
 | `autoResolvedPaths` | string[] | The specific paths that got the `--ours` treatment. `ok` only, paired with `autoResolved`. |
-| `conflictedPaths` | string[] | The disallowed conflicted paths that forced the abort. `fail-rebase` only, when at least one conflict was outside the allowlist. |
+| `conflictedPaths` | string[] | The disallowed conflicted paths. Present on `fail-rebase` (self-heal declined, wedged loud), and on any `fail-rebase-queued` / `fail-rebase-stuck` / `fail-rebase-needs-human` (self-heal ran, workspace healthy again). |
+| `selfHealed` | bool | Set to `true` on any self-heal audit record (`fail-rebase-queued`, `-stuck`, or `-needs-human`). |
+| `droppedCommit` | string | 40-hex sha of estate-sync's own commit that self-heal dropped. Present on all self-heal records. |
+| `queued` | object[] | Summary of each queued pending entry (id, originalPath, attemptCount, alertLevel, upstreamBlobShaAtQueue, conflictingUpstreamCommitSha, pendingPath). Present on all self-heal records. |
+| `drained` | object[] | Summary of drain results for this tick (id, originalPath, action, attemptCount, optional alertLevel + upstream blob shas). Present on any tick that saw pending entries at start-of-tick. |
+| `drainFinalised` | string[] | Ids of pending entries removed after commit + push were confirmed on HEAD. Present on `ok` records that carried `drained` entries with action `staged-for-retry`. |
+| `selfHealDeclined` | object | `{ stage, reason }` when self-heal was invoked but refused (queue-write failure, guard failure, reset failure). Paired with `status: fail-rebase` and `exitCode: 2`. |
 
 Status vocabulary (closed set):
 
@@ -238,13 +307,25 @@ Status vocabulary (closed set):
 | `ok` | 0 | Commit + push (or pull-only) succeeded. |
 | `noop-nothing-to-do` | 0 | Clean tree, no local commits ahead, up-to-date with origin. |
 | `noop-locked` | 0 | Another sync run holds the lock. |
-| `fail-rebase` | 2 | `git pull --rebase` conflicted; rebase aborted. Human reconciliation required. |
+| `fail-rebase` | 2 | `git pull --rebase` conflicted; self-heal either not attempted (regenerated-artifacts branch already resolved) or declined (guard-failure / queue-write-failure / reset-failure). Workspace is wedged, human reconciliation required. |
+| `fail-rebase-queued` | 0 | Self-heal ran on a non-allowlist conflict, dropped estate-sync's own commit under guard, queued the conflicting content for retry. Workspace is fast-forwardable again; librarian-alerts should surface the queued path (`alertLevel: warn`, `attemptCount < 5`). |
+| `fail-rebase-stuck` | 0 | Same as `fail-rebase-queued` but the pending entry's `attemptCount >= 5` — escalated alert (`alertLevel: error`). |
+| `fail-rebase-needs-human` | 0 | Self-heal ran, drain-time upstream divergence detected on a pending entry — someone else pushed a different resolution while ours was queued. Workspace NOT touched; pending held indefinitely (`alertLevel: needs-human`, sticky). |
 | `fail-push` | 2 | Push rejected even after one rebase-and-retry. Commit is local-only. |
 | `fail-git` | 3 | A `git status`/`add`/`commit` command itself errored (transport or IO). |
 | `fail-cli-bootstrap` | varies | parseArgs / import / startup failure before runSync was reached. |
 
-Consumer contract: monitors should treat `status == 'ok'` and any
-`noop-*` as healthy; any `fail-*` as failing.
+Consumer contract:
+- **Process health** — check `exitCode`. `0` = the sync process itself is
+  healthy (nothing to fix at cron / systemd level). This is the correct
+  signal for "is the cron process wedged?"
+- **Alert routing** — check `status.startsWith('fail-')`. Every `fail-*`
+  status is a human-visible alert regardless of exitCode, because
+  self-heal statuses (`fail-rebase-queued`, `fail-rebase-stuck`,
+  `fail-rebase-needs-human`) intentionally exit 0 (workspace is healthy,
+  process is healthy) while surfacing that a pending entry needs
+  attention. Escalation ladder inside self-heal: `queued` → `stuck` at
+  attempt >= 5 → `needs-human` on drain-time divergence (sticky).
 
 ## Exit codes
 

package/dist/engineering-pa-cli/src/sync/git.mjs

@@ -198,3 +198,91 @@ export async function rebaseContinue(runner, { cwd }) {
     { cwd, env: { ...process.env, GIT_EDITOR: 'true' } },
   );
 }
+
+// Resolve a ref (default HEAD) to its full sha. Returns { code, sha, stderr }.
+// The self-heal path uses this both to record the sha of estate-sync's own
+// commit at commit time AND to verify HEAD is still that sha immediately
+// before dropping it — the guard that stops the reset ever touching a
+// commit we did not just make.
+export async function revParseSha(runner, { cwd, ref = 'HEAD' } = {}) {
+  const r = await runner.spawn('git', ['rev-parse', '--verify', `${ref}^{commit}`], { cwd });
+  return { code: r.code, sha: r.stdout.trim(), stderr: r.stderr };
+}
+
+// Count commits in a range (e.g. HEAD^..HEAD). Returns { code, count, stderr }.
+// count === 1 is the drop-guard invariant: exactly one commit between HEAD's
+// parent and HEAD (never a merge-commit stack, never zero, never more).
+export async function revListCount(runner, { cwd, range }) {
+  const r = await runner.spawn('git', ['rev-list', '--count', range], { cwd });
+  const n = Number.parseInt(r.stdout.trim(), 10);
+  return { code: r.code, count: Number.isFinite(n) ? n : null, stderr: r.stderr };
+}
+
+// git reset --soft <ref>. Moves HEAD to <ref>, leaves BOTH the index and
+// the working tree untouched. This is the load-bearing primitive for the
+// R2 self-heal path: after dropping our commit, the non-conflicting
+// portion of that commit's diff MUST remain staged in the index so the
+// next tick recommits it. --mixed would unstage (still fine for our
+// purposes but noisier), --hard would obliterate everything, and --keep
+// (which we originally used, corrected 2026-08-12 per the reviewer's
+// blocker on PR #120) actively UPDATES the working tree to match <ref>
+// on every file that differs between HEAD and <ref> — meaning every
+// non-conflicting path in the dropped commit gets silently destroyed.
+// --soft leaves the surgical work to the caller: keep what we want,
+// remove or restore only the conflicting paths we've already queued.
+export async function resetSoft(runner, { cwd, ref }) {
+  return runner.spawn('git', ['reset', '--soft', ref], { cwd });
+}
+
+// git rm --cached -- <path>. Unstages a single path — removes it from the
+// index without touching the working tree. Paired with `fs.unlink` in
+// self-heal to surgically un-stage a newly-added conflicting path after
+// the --soft reset (the addition is queued to pending, so we want the
+// path GONE from the index AND from disk without touching any other
+// staged content).
+export async function rmCached(runner, { cwd, paths }) {
+  if (paths.length === 0) return { code: 0, stdout: '', stderr: '' };
+  return runner.spawn('git', ['rm', '--cached', '--', ...paths], { cwd });
+}
+
+// git hash-object <path>. Computes git's own blob sha for the byte
+// contents of a file, WITHOUT staging or writing anything to the object
+// store. Used by the drain to compare a pending file's bytes against
+// `origin/<branch>:<path>` via matching sha values — binary-safe, no
+// utf8 round-trip, and apples-to-apples (git blob sha both sides).
+export async function hashObject(runner, { cwd, path }) {
+  const r = await runner.spawn('git', ['hash-object', '--', path], { cwd });
+  return { code: r.code, sha: r.stdout.trim(), stderr: r.stderr };
+}
+
+// Does <ref>:<path> exist? `git cat-file -e` exits 0 if yes, non-zero if no.
+// Used by self-heal to decide the working-tree cleanup shape:
+//   - path existed at HEAD^   → checkout HEAD^ to restore parent's version
+//   - path did NOT exist there → the file was newly added by our commit;
+//                                remove it from the working tree entirely
+// Getting this branch right is what stops the wedge-loop where our own
+// content, still in the tree after reset, re-conflicts on every tick.
+export async function refPathExists(runner, { cwd, ref, path }) {
+  const r = await runner.spawn('git', ['cat-file', '-e', `${ref}:${path}`], { cwd });
+  return r.code === 0;
+}
+
+// git checkout <ref> -- <paths>. Copies the ref's version of each path into
+// BOTH the index and the working tree. Used by self-heal after the
+// reset --keep HEAD^ to overwrite the (now unstaged) conflicting paths with
+// their pre-commit versions, so the next tick's step 6 doesn't re-stage the
+// content we've deliberately queued out of the way.
+export async function checkoutFromRef(runner, { cwd, ref, paths }) {
+  if (paths.length === 0) return { code: 0, stdout: '', stderr: '' };
+  return runner.spawn('git', ['checkout', ref, '--', ...paths], { cwd });
+}
+
+// Does the ref exist locally? Used to check origin/<branch> before we try
+// to inspect it (a fresh clone with no fetches wouldn't have it). We use
+// `git show-ref --verify --quiet` because it's the ref-existence idiom that
+// doesn't fall back to name-rev heuristics and produces no output on either
+// branch.
+export async function refExists(runner, { cwd, ref }) {
+  const r = await runner.spawn('git', ['show-ref', '--verify', '--quiet', ref], { cwd });
+  return r.code === 0;
+}

package/dist/engineering-pa-cli/src/sync/pending-store.mjs

@@ -0,0 +1,318 @@
+// estate-sync — pending-conflict store.
+//
+// On a rebase conflict that lands OUTSIDE the regenerated-artifacts
+// allowlist, estate-sync now (a) captures our own version of every
+// conflicting path, (b) drops the local commit that made the conflict, and
+// (c) queues the captured content for retry on subsequent ticks. This
+// module owns the on-disk representation of that queue.
+//
+// Layout under `<repoRoot>/.cache/estate-sync/pending/`:
+//   <pathSlug>__<firstSeenTsSlug>            — raw bytes of estate-sync's version
+//   <pathSlug>__<firstSeenTsSlug>.json       — sidecar with metadata
+//
+// The pending id is the shared basename; the raw file and the sidecar
+// share it verbatim (sidecar just has `.json` on the end). Path slug is
+// the original path with `/` replaced by `__` and any characters outside
+// [A-Za-z0-9._-] replaced with `-`. First-seen timestamp is stripped of
+// separators (`2026-08-11T16:30:07Z` → `20260811T163007Z`).
+//
+// Two invariants this module enforces:
+//   1. Content-safety on queue — the raw file is opened, written, fsynced,
+//      and closed BEFORE the sidecar is written. Sidecar in turn is
+//      write-tmp-then-rename (with fsync of the tmp handle and of the
+//      containing directory) so a crash never leaves a sidecar pointing at
+//      unwritten content.
+//   2. Upsert by originalPath — a second conflict on the SAME workspace
+//      path replaces the raw file with our new version, keeps `firstSeen`
+//      unchanged (so the file's id stays stable across retries), and
+//      bumps `attemptCount`. This is what stops the drain-then-re-conflict
+//      loop from flooding the pending dir with parallel entries for one
+//      logical conflict.
+//
+// Sidecar fields (see loadAll for canonical field names):
+//   id, originalPath, firstSeen, lastAttemptAt, attemptCount,
+//   conflictingUpstreamCommitSha, upstreamBlobShaAtQueue (nullable —
+//     null when origin had no such path at queue time), ourContentSha,
+//   existedInParent (was HEAD^:originalPath present? drives the tree-
+//     cleanup branch), alertLevel ('warn' | 'error' | 'needs-human').
+
+import { open, mkdir, readFile, readdir, rename, rm, writeFile, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+// Slug rules: replace path separators with `__`, then any character not in
+// [A-Za-z0-9._-] with `-`, then collapse runs of `-` to one, then trim
+// leading/trailing `.-_`. Bounded to 120 chars (rare-long-path safety on
+// filesystems with 255-byte name limits — the timestamp adds ~16 chars and
+// the `.json` suffix adds 5, leaving headroom).
+export function slugifyPath(p) {
+  const out = p
+    .replace(/[\/\\]+/g, '__')
+    .replace(/[^A-Za-z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[.\-_]+|[.\-_]+$/g, '');
+  return out.slice(0, 120) || 'path';
+}
+
+// Turn an ISO timestamp (`2026-08-11T16:30:07Z`) into a filename-safe
+// compact form (`20260811T163007Z`). Non-matching input is passed through
+// unchanged after the same non-alnum sweep as the path slug.
+export function slugifyTs(ts) {
+  return String(ts).replace(/[^A-Za-z0-9]/g, '');
+}
+
+// Build the canonical pending id for an (originalPath, firstSeen) pair.
+// The `__` separator between the path slug and the ts slug is deliberate:
+// path slugs never contain `__` (single `_` may appear, `__` is our
+// literal separator token because paths already collapsed `/` to `__` —
+// see slugifyPath which uses `__` for `/` only after the char scrub, so a
+// raw `_` in a filename becomes `_` alone). Adding a further `__` gives
+// an unambiguous split point when reading id fields back out for logs.
+export function pendingId(originalPath, firstSeen) {
+  return `${slugifyPath(originalPath)}__${slugifyTs(firstSeen)}`;
+}
+
+export function pendingContentPath(pendingDir, id) {
+  return join(pendingDir, id);
+}
+
+export function pendingSidecarPath(pendingDir, id) {
+  return join(pendingDir, `${id}.json`);
+}
+
+function sha256Hex(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+// Atomic-ish sidecar write: write to `<name>.tmp`, fsync the tmp handle,
+// rename over `<name>`, then fsync the containing directory so the
+// rename is durable. If the directory fsync throws (unsupported on some
+// filesystems / Windows), swallow that specific failure — the rename
+// itself has already landed on POSIX, and durability was best-effort by
+// contract on non-POSIX. The write + rename ordering is what actually
+// guarantees no half-written sidecars on the read path.
+async function writeJsonAtomic(filePath, obj) {
+  const tmp = `${filePath}.tmp`;
+  const payload = `${JSON.stringify(obj, null, 2)}\n`;
+  const fh = await open(tmp, 'w');
+  try {
+    await fh.writeFile(payload, 'utf8');
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await rename(tmp, filePath);
+  try {
+    const dh = await open(dirname(filePath), 'r');
+    try { await dh.sync(); } finally { await dh.close(); }
+  } catch {
+    // Directory fsync unsupported on this filesystem — best-effort only.
+  }
+}
+
+// Content-write with the same durability contract as the sidecar. Content
+// is written as bytes (Buffer or string) — callers pass the raw file
+// content captured from the working tree.
+async function writeBytesAtomic(filePath, buf) {
+  const tmp = `${filePath}.tmp`;
+  const fh = await open(tmp, 'w');
+  try {
+    await fh.writeFile(buf);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await rename(tmp, filePath);
+  try {
+    const dh = await open(dirname(filePath), 'r');
+    try { await dh.sync(); } finally { await dh.close(); }
+  } catch {
+    // See writeJsonAtomic — filesystem may not support directory fsync.
+  }
+}
+
+// Ensure the pending dir exists. Idempotent; safe to call on every tick.
+export async function ensurePendingDir(pendingDir) {
+  await mkdir(pendingDir, { recursive: true });
+}
+
+// Compose a canonical sidecar object from a queue-time payload. Kept as a
+// pure function so tests can assert the exact shape without file I/O.
+export function makeSidecar({
+  id,
+  originalPath,
+  firstSeen,
+  attemptCount = 1,
+  conflictingUpstreamCommitSha,
+  upstreamBlobShaAtQueue = null,
+  ourContentSha,
+  existedInParent,
+  alertLevel = 'warn',
+}) {
+  return {
+    id,
+    originalPath,
+    firstSeen,
+    lastAttemptAt: firstSeen,
+    attemptCount,
+    conflictingUpstreamCommitSha: conflictingUpstreamCommitSha ?? null,
+    upstreamBlobShaAtQueue,
+    ourContentSha,
+    existedInParent: Boolean(existedInParent),
+    alertLevel,
+  };
+}
+
+// Look up an existing sidecar for `originalPath`, if any. Used by upsert
+// to preserve `firstSeen` and bump `attemptCount` across a re-queue for
+// the same path.
+export async function findByOriginalPath(pendingDir, originalPath) {
+  let entries;
+  try {
+    entries = await readdir(pendingDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    let text;
+    try {
+      text = await readFile(join(pendingDir, name), 'utf8');
+    } catch {
+      continue;
+    }
+    let obj;
+    try { obj = JSON.parse(text); } catch { continue; }
+    if (obj && obj.originalPath === originalPath) return obj;
+  }
+  return null;
+}
+
+// Queue (or re-queue) a conflict. Contract:
+//   - Raw content is written and fsynced BEFORE the sidecar is written —
+//     if we crash mid-queue, a sidecar-less raw file is orphan (safe:
+//     next tick's cleanup can rm it, or leave it as forensic evidence)
+//     but there is never a sidecar pointing at unwritten content.
+//   - On upsert, `firstSeen` stays anchored to the earliest queue for
+//     this path, `attemptCount` is (prevAttempt + 1) if the caller doesn't
+//     override, and `alertLevel` follows the escalation ladder (warn →
+//     error at attemptCount >= escalateAt; needs-human is caller-set and
+//     sticky — divergence detected at drain time never de-escalates).
+//   - Returns the fully-populated sidecar object plus its content path.
+export async function queueConflict(pendingDir, {
+  originalPath,
+  content,
+  firstSeen,
+  conflictingUpstreamCommitSha,
+  upstreamBlobShaAtQueue = null,
+  existedInParent,
+  escalateAt = 5,
+  forceAlertLevel = null,
+}) {
+  await ensurePendingDir(pendingDir);
+
+  const existing = await findByOriginalPath(pendingDir, originalPath);
+  const anchoredFirstSeen = existing ? existing.firstSeen : firstSeen;
+  const nextAttempt = existing ? (existing.attemptCount || 0) + 1 : 1;
+  const priorAlert = existing?.alertLevel || 'warn';
+  const escalated = nextAttempt >= escalateAt ? 'error' : 'warn';
+  // needs-human is sticky — a caller sets it (divergence detected at drain
+  // time) and later requeues never step it back down to warn/error.
+  const alertLevel = forceAlertLevel
+    || (priorAlert === 'needs-human' ? 'needs-human' : escalated);
+
+  const id = pendingId(originalPath, anchoredFirstSeen);
+  const contentPath = pendingContentPath(pendingDir, id);
+  const sidecarPath = pendingSidecarPath(pendingDir, id);
+
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content);
+  await writeBytesAtomic(contentPath, buf);
+
+  const sidecar = makeSidecar({
+    id,
+    originalPath,
+    firstSeen: anchoredFirstSeen,
+    attemptCount: nextAttempt,
+    conflictingUpstreamCommitSha,
+    upstreamBlobShaAtQueue,
+    ourContentSha: sha256Hex(buf),
+    existedInParent,
+    alertLevel,
+  });
+  sidecar.lastAttemptAt = firstSeen;
+
+  await writeJsonAtomic(sidecarPath, sidecar);
+
+  return { sidecar, contentPath, sidecarPath };
+}
+
+// Read all pending sidecars, oldest-firstSeen-first. Corrupt sidecars are
+// SKIPPED with a warning attached to the return object — a broken sidecar
+// must never block the drain of well-formed ones.
+export async function loadAll(pendingDir) {
+  const out = [];
+  const warnings = [];
+  let names;
+  try {
+    names = await readdir(pendingDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { entries: [], warnings };
+    throw err;
+  }
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const sidecarPath = join(pendingDir, name);
+    let text;
+    try {
+      text = await readFile(sidecarPath, 'utf8');
+    } catch (err) {
+      warnings.push({ sidecar: name, reason: `read failed: ${err.message}` });
+      continue;
+    }
+    let obj;
+    try { obj = JSON.parse(text); } catch (err) {
+      warnings.push({ sidecar: name, reason: `parse failed: ${err.message}` });
+      continue;
+    }
+    if (!obj || typeof obj !== 'object' || !obj.originalPath || !obj.id) {
+      warnings.push({ sidecar: name, reason: 'malformed sidecar (missing id / originalPath)' });
+      continue;
+    }
+    const contentPath = pendingContentPath(pendingDir, obj.id);
+    let contentStat;
+    try { contentStat = await stat(contentPath); } catch {
+      warnings.push({ sidecar: name, reason: 'content file missing — sidecar orphan; skipping' });
+      continue;
+    }
+    out.push({ sidecar: obj, sidecarPath, contentPath, contentSize: contentStat.size });
+  }
+  out.sort((a, b) => (a.sidecar.firstSeen < b.sidecar.firstSeen ? -1 : 1));
+  return { entries: out, warnings };
+}
+
+// Rewrite a sidecar (durably) — used to bump attemptCount / alertLevel
+// without touching the content file. Callers typically compose the next
+// sidecar from the loaded one with `{ ...sidecar, attemptCount: n }`.
+export async function writeSidecar(pendingDir, sidecar) {
+  await ensurePendingDir(pendingDir);
+  const sidecarPath = pendingSidecarPath(pendingDir, sidecar.id);
+  await writeJsonAtomic(sidecarPath, sidecar);
+  return { sidecarPath };
+}
+
+// Remove a pending entry — both the content file and the sidecar. Contract:
+// removal happens ONLY after the sync has committed AND pushed the
+// pending content upstream. Removal is best-effort per file: either half
+// missing is not an error (idempotent cleanup after a crash mid-remove).
+export async function removePending(pendingDir, id) {
+  const contentPath = pendingContentPath(pendingDir, id);
+  const sidecarPath = pendingSidecarPath(pendingDir, id);
+  await rm(contentPath, { force: true });
+  await rm(sidecarPath, { force: true });
+}
+
+// Read the raw content bytes for a pending id.
+export async function readContent(pendingDir, id) {
+  return readFile(pendingContentPath(pendingDir, id));
+}