mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/project-meta-cache.js

@@ -1,67 +1,23 @@
 /**
- * project-meta-cache — on-disk cache for repo-invariant GitHub Projects v2
- * board metadata (Story #4252).
- *
- * Every `agent::*` label flip routes through `transitionTicketState` →
- * `ColumnSync.sync`, which must resolve the board's `{ projectId, fieldId,
- * options }` before issuing the Status mutation. Single-story delivery
- * performs each flip in a *separate cold CLI process* (init → executing,
- * close → closing, confirm-merge → done, plus `resync-status-column`), so
- * the in-process `_meta` cache is always empty and every flip re-pays
- * `resolveProjectMeta` + an item-id lookup + the mutation (~3 GraphQL
- * round-trips).
- *
- * The board metadata is **repo-invariant** — it changes only when the
- * Status single-select field is reconfigured — so it is a prime candidate
- * for an on-disk cache that survives across the cold processes. This module
- * persists the resolved metadata to a small JSON file under the resolved
- * `tempRoot`, keyed by `owner/projectNumber`, carrying a TTL. Correctness
- * is bounded by "the mutation still validates against the live board": a
- * stale entry at worst causes one failed mutation, which the caller treats
- * as a signal to invalidate the entry and re-resolve — never a wrong write.
- *
- * Layout: `<tempRoot>/cache/project-meta.json`, a single JSON object keyed
- * by `<owner>/<projectNumber>`:
- *
- *   {
- *     "dsj1984/1": {
- *       "cachedAt": 1718000000000,
- *       "projectId": "PVT_…",
- *       "fieldId": "PVTSSF_…",
- *       "options": { "Todo": "abc", "In Progress": "def", "Done": "ghi" }
- *     }
- *   }
- *
- * The `options` map is serialised as a plain object and re-hydrated into a
- * `Map<name, id>` on read so the ColumnSync call site is identical whether
- * the metadata came from the disk cache or a live resolve.
- *
- * The cache file lives under `tempRoot`, which is gitignored
- * (`temp/` in `.gitignore`), so it introduces no new tracked artifact.
+ * project-meta-cache — on-disk cache of repo-invariant Projects v2 board
+ * metadata (`{ projectId, fieldId, options }`), so each cold CLI process that
+ * flips a label skips re-resolving it. Stored at
+ * `<tempRoot>/cache/project-meta.json`, keyed `<owner>/<projectNumber>`, with
+ * a TTL. A stale entry at worst fails one mutation, which the caller answers
+ * by invalidating and re-resolving — never a wrong write.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { anchorTempRoot, tempRootFrom } from '../config/temp-paths.js';
 
-/**
- * Default time-to-live for a cached board-metadata entry, in milliseconds.
- * Board metadata is repo-invariant (it only changes on a manual Status
- * field reconfiguration), so a generous TTL is safe — and a stale entry is
- * self-healing via invalidate-on-error regardless. One hour comfortably
- * spans a single `/single-story-deliver` run's four cold flips while still
- * forcing a periodic re-resolve.
- */
+/** One hour spans a delivery run's cold flips yet forces periodic refresh. */
 const DEFAULT_META_TTL_MS = 60 * 60 * 1000;
 
 /**
- * Resolve the path to the on-disk project-meta cache file under the
- * (anchored) resolved `tempRoot`. A relative `tempRoot` is anchored to the
- * main checkout root so a worktree child and the main-checkout host
- * converge on the same file (Story #3900 semantics, reused here).
+ * Anchored to the main checkout so worktree children and the host share it.
  *
- * @param {object} [config] Optional resolved config bag. Omitted → framework
- *   default (`temp`).
+ * @param {object} [config] Optional resolved config bag.
  * @returns {string}
  */
 function projectMetaCachePath(config) {
@@ -73,12 +29,9 @@ function projectMetaCachePath(config) {
 }
 
 /**
- * Build the per-board cache key from `(owner, projectNumber)`.
- *
  * @param {string|null|undefined} owner
  * @param {number|string|null|undefined} projectNumber
- * @returns {string|null} `<owner>/<projectNumber>`, or null when either part
- *   is missing (an un-keyable board — caller skips the cache).
+ * @returns {string|null} null when un-keyable (caller skips the cache).
  */
 function projectMetaCacheKey(owner, projectNumber) {
   if (!owner || projectNumber === null || projectNumber === undefined) {
@@ -88,9 +41,7 @@ function projectMetaCacheKey(owner, projectNumber) {
 }
 
 /**
- * Read the entire cache file as a plain object. Returns an empty object on
- * any read/parse failure (missing file, malformed JSON) so the caller treats
- * a corrupt cache as a cold miss rather than throwing.
+ * A missing or corrupt file reads as `{}` — a cold miss.
  *
  * @param {string} filePath
  * @returns {Record<string, object>}
@@ -106,11 +57,7 @@ function readCacheFile(filePath) {
 }
 
 /**
- * Read a cached metadata entry for `(owner, projectNumber)`.
- *
- * Returns the re-hydrated `{ projectId, fieldId, options: Map }` descriptor
- * when a fresh (within TTL) entry exists, or `null` on a miss / expired /
- * malformed entry. Never throws — a read failure is a cache miss.
+ * A fresh entry with `options` re-hydrated to a Map, else `null`. Never throws.
  *
  * @param {{
  *   owner?: string|null,
@@ -142,7 +89,6 @@ export function readProjectMetaCache(opts = {}) {
   ) {
     return null;
   }
-  // TTL check — an expired entry is a miss so the caller re-resolves.
   if (now - cachedAt > ttlMs) return null;
 
   return {
@@ -153,13 +99,7 @@ export function readProjectMetaCache(opts = {}) {
 }
 
 /**
- * Persist a resolved metadata descriptor for `(owner, projectNumber)`.
- *
- * The `options` value may be a `Map<name,id>` or a plain object; it is
- * normalised to a plain object on disk. Best-effort: any write failure is
- * swallowed (the cache is a pure optimisation — a failed write just means
- * the next process re-resolves). Writes the rest of the store back intact so
- * sibling board entries are preserved.
+ * Best-effort write preserving sibling board entries.
  *
  * @param {{
  *   owner?: string|null,
@@ -206,13 +146,8 @@ export function writeProjectMetaCache(opts = {}) {
 }
 
 /**
- * Invalidate (delete) the cached entry for `(owner, projectNumber)`.
- *
- * Called when a GraphQL error fires against a board whose metadata came from
- * the cache, so a mid-run board reconfiguration self-heals on the next flip
- * (which re-resolves and re-writes). Best-effort and idempotent: a missing
- * entry or unreadable file is a no-op. Returns true when an entry was
- * actually removed.
+ * Drop an entry after a GraphQL error against cached metadata, so a board
+ * reconfiguration self-heals. Best-effort, idempotent.
  *
  * @param {{
  *   owner?: string|null,

package/.agents/scripts/lib/orchestration/project-meta-resolver.js

@@ -1,40 +1,13 @@
 /**
- * project-meta-resolver — shared GitHub Projects v2 owner-resolution
- * primitive (Story #4237).
- *
- * Background:
- *   Both `ColumnSync._loadMeta` (`lib/orchestration/column-sync.js`) and
- *   `resolveProjectIdByNumber` (`lib/bootstrap/workflow-audit.js`)
- *   needed to turn a `(owner, projectNumber)` pair into a Projects v2
- *   board node id. Each historically resolved only **user-owned** /
- *   `viewer`-owned boards: `viewer.projectV2(number:)` first, then
- *   `user(login:$owner).projectV2(number:)` (Story #3560). Neither had an
- *   `organization(login:$owner)` branch, so for an **org-owned** board
- *   every lookup failed with `NOT_FOUND` and the `agent::*` → board
- *   Status mirror silently no-oped (reproduced on `Beestera/swarm-os`).
- *
- * Fix:
- *   A single shared resolver that walks the owner-type ladder in order —
- *   `organization(login:$owner)` → `user(login:$owner)` → `viewer` —
- *   returning the first board it can resolve. Centralising the ladder in
- *   one place means the org path can never again drift between the two
- *   call sites.
- *
- * The resolver issues a sub-query for the project itself (`field(name:
- * "Status") { … }` for the column-sync caller, or a bare `id` for the
- * workflow-audit caller). Pass the desired projection in via
- * `projectFields`; the resolver wraps it in the right owner scope and
- * extracts the resolved `projectV2` node.
+ * project-meta-resolver — the one Projects v2 owner-resolution ladder
+ * (`organization` → `user` → `viewer`), shared so an org-owned board can
+ * never again silently fail to resolve at one call site. Callers pass the
+ * `projectV2 { … }` selection body as `projectFields`.
  */
 
 /**
- * The owner-resolution ladder, in priority order. Each entry names the
- * GraphQL root field and whether it requires the `$owner` variable.
- *
- * `organization` and `user` are keyed by `login: $owner`; `viewer` is the
- * authenticated identity and takes no owner argument. The viewer rung is
- * the historical default and stays last so a configured owner is always
- * preferred over the ambient identity.
+ * Priority order. `viewer` (the ambient identity) is last so a configured
+ * owner always wins.
  */
 const OWNER_SCOPES = Object.freeze([
   { root: 'organization', needsOwner: true },
@@ -43,11 +16,8 @@ const OWNER_SCOPES = Object.freeze([
 ]);
 
 /**
- * Build the GraphQL document for a single owner scope.
- *
  * @param {{ root: string, needsOwner: boolean }} scope
- * @param {string} projectFields — the inner `projectV2(number: $number) { … }`
- *   selection body (everything between the braces).
+ * @param {string} projectFields — the selection body inside `projectV2 { … }`.
  * @returns {string}
  */
 function buildScopedQuery(scope, projectFields) {
@@ -72,17 +42,8 @@ function buildScopedQuery(scope, projectFields) {
 }
 
 /**
- * Resolve a Projects v2 board node by walking the owner-type ladder.
- *
- * Tries `organization(login:$owner)` → `user(login:$owner)` → `viewer` in
- * order, returning the first non-null `projectV2` node. A scope that
- * throws (e.g. GitHub returns `NOT_FOUND` for the wrong owner type) or
- * resolves to `null` is treated as a miss and the ladder advances to the
- * next rung. Returns `null` when every rung misses.
- *
- * When `owner` is falsy, only the `viewer` rung is attempted (there is no
- * login to scope `organization`/`user` by) — this preserves the original
- * viewer-only behaviour for callers that never configured a project owner.
+ * The first non-null `projectV2` node down the ladder; a throwing or null
+ * rung is a miss. With no `owner`, only `viewer` is tried.
  *
  * @param {{
  *   provider: { graphql: Function },
@@ -104,7 +65,6 @@ export async function resolveProjectMeta(args) {
   }
 
   for (const scope of OWNER_SCOPES) {
-    // Skip the owner-scoped rungs when no owner login is available.
     if (scope.needsOwner && !owner) continue;
 
     const query = buildScopedQuery(scope, projectFields);
@@ -116,8 +76,7 @@ export async function resolveProjectMeta(args) {
     try {
       data = await provider.graphql(query, vars);
     } catch {
-      // Wrong owner type (NOT_FOUND), missing scope, etc. — advance the
-      // ladder rather than aborting the whole resolution.
+      // Wrong owner type (NOT_FOUND) etc. — advance the ladder.
       continue;
     }
 

package/.agents/scripts/lib/orchestration/reassert-status-column.js

@@ -1,56 +1,18 @@
 /**
- * reassert-status-column — re-fire `ColumnSync` against a ticket's
- * current label set so the GitHub Projects v2 Status column matches the
- * orchestrator's view (Story #2845, hardened in Story #2876).
- *
- * Why a dedicated helper:
- *   `transitionTicketState` already calls `syncProjectStatusColumn` at
- *   label-flip time, but the GitHub built-in `Pull request merged` /
- *   `Pull request linked to issue` workflows fire ~minutes after the
- *   PR auto-merges and overwrite Status. The orchestrator's close path
- *   has long-since exited by then, so "the last write" is the bot's.
- *   This helper is invoked AFTER the merge confirmation step (via the
- *   `resync-status-column.js` CLI the `/single-story-deliver` workflow
- *   doc calls) to reassert authority and win the race deterministically.
- *
- *   Operators who disable the conflicting bot workflows (via the
- *   `--reap-conflicting-workflows` bootstrap flag) get the same outcome
- *   without needing the re-sync. The helper is defense-in-depth and is
- *   cheap to fire — Story #2876 added a bounded poll-and-retry loop so
- *   the defense actually works against an asynchronous bot overwrite
- *   that lands after the initial mutation. Without the loop, a one-shot
- *   mutation routinely lost the race (reproduced on Story #2871 /
- *   PR #2872).
- *
- * Surface:
- *   - {@link reassertStatusColumn} — read the ticket's current labels,
- *     pick the canonical column via {@link columnForLabels}, push it
- *     via `ColumnSync.sync`, then poll the live Status for a bounded
- *     window and re-fire on drift. Returns the sync envelope augmented
- *     with `attempts`.
+ * reassert-status-column — re-fire `ColumnSync` from a ticket's current
+ * labels after merge confirmation. GitHub's built-in PR workflows overwrite
+ * Status minutes after auto-merge, so a bounded poll-and-refire is needed to
+ * win that race; a one-shot mutation routinely lost it.
  */
 
 import { ColumnSync, columnForLabels } from './column-sync.js';
 
-/**
- * Default total mutation attempts (including the initial sync). At
- * `pollDelayMs = 5000`, four attempts cover a ~15 s defense window —
- * long enough to outlast the typical GitHub built-in workflow fire
- * timing without ballooning the close-path wall clock.
- */
+/** Four attempts at 5 s cover a ~15 s window past typical bot timing. */
 const DEFAULT_POLL_ATTEMPTS = 4;
 
-/**
- * Default delay between drift checks (ms). Five seconds is a sweet
- * spot: short enough that the operator doesn't perceive the close
- * path as hung, long enough that one re-fire usually wins the race.
- */
 const DEFAULT_POLL_DELAY_MS = 5000;
 
 /**
- * Production sleep function. Tests inject `sleepFn: () => Promise.resolve()`
- * so the poll loop runs instantly.
- *
  * @param {number} ms
  * @returns {Promise<void>}
  */
@@ -59,28 +21,11 @@ function defaultSleep(ms) {
 }
 
 /**
- * Re-assert the Status column for a single ticket. Reads the ticket's
- * current labels so the caller doesn't have to pass them (the typical
- * use site is a post-merge CLI that knows the ticket id only).
- *
- * Returns the same envelope shape as `ColumnSync.sync`, augmented with
- * `attempts` (the number of mutations actually fired):
- *   - `{ status: 'synced', column, attempts }` — the mutation landed
- *     and the drift-check confirmed Status matches the target. If
- *     drift was detected and re-fired, `attempts` reflects the total
- *     mutation count.
- *   - `{ status: 'drifted', column, attempts }` — the helper exhausted
- *     `pollAttempts` and the live Status still didn't match the
- *     target. Returned, not thrown — the caller decides whether to
- *     escalate. `column` carries the target column the helper was
- *     trying to set.
- *   - `{ status: 'skipped', reason }` — no-op for an enumerated reason
- *     (`no-matching-label`, `no-project`, `no-meta`, `no-option-<col>`,
- *     `not-on-project`). Skip paths short-circuit before the poll loop.
- *
- * Throws when the provider is unusable. Other failures (GraphQL,
- * network) propagate from `ColumnSync.sync` and `provider.getTicket` —
- * callers wrap in try/catch if they want best-effort semantics.
+ * Re-assert one ticket's Status column. Returns `ColumnSync.sync`'s envelope
+ * plus `attempts`: `synced` (confirmed), `drifted` (budget exhausted, still
+ * wrong — returned, not thrown), or `skipped` with a reason (before any
+ * polling). Throws on an unusable provider; GraphQL/network errors from the
+ * first sync propagate.
  *
  * @param {{
  *   provider: { getTicket: Function, graphql: Function, owner: string, repo: string, projectNumber?: number|null },
@@ -132,9 +77,6 @@ export async function reassertStatusColumn(args) {
   }
   const sync = new ColumnSync({ provider, logger: logger ?? console, config });
 
-  // First attempt — always fires through ColumnSync.sync so the skip
-  // paths (no-project / no-meta / no-option-<col> / not-on-project)
-  // short-circuit before we enter the poll loop.
   const initial = await sync.sync(ticketId, labels);
   if (initial.status !== 'synced') {
     return initial;
@@ -142,9 +84,7 @@ export async function reassertStatusColumn(args) {
   let attempts = 1;
   let lastEnvelope = { ...initial, attempts };
 
-  // Drift loop — read live Status, re-fire if it doesn't match the
-  // target column. Bounded by pollAttempts so a hostile bot can't
-  // stall the close path indefinitely.
+  // Bounded so a hostile bot cannot stall the close path.
   for (let i = 1; i < pollAttempts; i += 1) {
     await sleepFn(pollDelayMs);
     let current;
@@ -159,7 +99,6 @@ export async function reassertStatusColumn(args) {
       continue;
     }
     if (current === targetColumn) {
-      // Sticky confirmation — return the existing envelope.
       return lastEnvelope;
     }
     logger?.info?.(
@@ -170,8 +109,7 @@ export async function reassertStatusColumn(args) {
     try {
       const next = await sync.sync(ticketId, labels);
       attempts += 1;
-      // Skip envelopes during the retry loop are unexpected once we've
-      // already synced once; preserve their shape but stop retrying.
+      // A skip after a successful sync is unexpected: stop retrying.
       if (next.status !== 'synced') {
         return { ...next, attempts };
       }
@@ -185,8 +123,6 @@ export async function reassertStatusColumn(args) {
     }
   }
 
-  // Exhausted the poll budget — final drift read to report the
-  // honest outcome to the caller.
   let final;
   try {
     final = await sync.readCurrentColumn(ticketId);

package/.agents/scripts/lib/orchestration/remote-verifier.js

@@ -1,36 +1,20 @@
 // .agents/scripts/lib/orchestration/remote-verifier.js
 /**
- * remote-verifier.js — deterministic "is there a live, pushable remote?"
- * evidence for the delivery entry seams. Issue #4483.
+ * remote-verifier.js — verified "is there a live, pushable remote?" evidence
+ * for the delivery entry seams, so the workflow branches on
+ * `remoteVerified` (use the remote, or block quoting the probe) instead of an
+ * agent's perception — never a silent local build.
  *
- * `/mandrel-deliver` could silently shortcut the entire orchestration — building
- * the delivery inline and committing to local `main` without pushing —
- * when the driving agent *perceived* the environment had no live GitHub
- * remote. The judgment was vibes, not fact. This module gives the entry
- * seams (`single-story-init.js` for v2 `/mandrel-deliver`) a verified
- * probe result to record in their envelopes so the workflow can branch on
- * `remoteVerified: true|false` deterministically: use the remote, or
- * transition to `agent::blocked` quoting the probe output — never a
- * silent local build.
- *
- * Two probes, both bounded (a hung git spawn must not park the entry
- * seam — mirrors the `ghPrListHead` timeout contract in `finalizer.js`):
- *
- *   1. `git remote get-url origin`  — is an `origin` remote configured?
- *   2. `git ls-remote origin HEAD`  — is it reachable with current auth?
- *
- * `remoteVerified` is true only when BOTH succeed. The CLI callers do
- * NOT flip labels on a false result — the workflow owns the
- * `agent::blocked` transition (same division of labour as the preflight
- * breach handling).
+ * `remoteVerified` requires both `git remote get-url origin` and
+ * `git ls-remote origin HEAD` to succeed. Callers flip no labels; the
+ * workflow owns the `agent::blocked` transition.
  */
 
 import { spawnSync } from 'node:child_process';
 
 /**
- * Bounded timeout for each git probe. `ls-remote` is a network call;
- * SIGKILL at the bound so an unreachable or hanging remote degrades to a
- * deterministic `remoteVerified: false` instead of a stuck entry seam.
+ * Per-probe bound, SIGKILLed, so a hanging remote degrades to
+ * `remoteVerified: false` instead of parking the entry seam.
  */
 export const REMOTE_PROBE_TIMEOUT_MS = 30_000;
 
@@ -51,8 +35,6 @@ function runProbe({ args, cwd, spawnFn, timeoutMs }) {
 }
 
 /**
- * Probe the `origin` remote for existence + reachability.
- *
  * @param {{
  *   cwd?: string,
  *   spawnFn?: typeof spawnSync,
@@ -113,15 +95,9 @@ export function verifyRemote({
 }
 
 /**
- * Probe whether a specific branch exists on `origin` — the deterministic
- * finalize backstop (issue #4483 fix direction 3): a delivery branch that
- * was never pushed MUST fail finalize with an explicit blocker rather
- * than let the run declare success.
- *
- * Distinct from `git-branch-lifecycle.js#branchExistsRemotely` in two
- * load-bearing ways: the spawn is bounded (timeout + SIGKILL, so a hung
- * remote cannot park the finalize seam) and the result carries the probe
- * detail for the blocker envelope instead of a bare boolean.
+ * Finalize backstop: a never-pushed delivery branch must fail with a blocker,
+ * not declare success. Unlike `branchExistsRemotely`, the spawn is bounded
+ * and the result carries probe detail for the blocker envelope.
  *
  * @param {{
  *   branch: string,