mandrel 1.90.0 → 1.91.0

package/.agents/scripts/epic-deliver-preflight.js

@@ -11,7 +11,12 @@
  *      `storyCount`, `installCostSeconds`, `dependencyDepth`,
  *      `githubApiRequests`, `claudeQuotaTokens`, plus `breaches`
  *      (the non-empty subset of `delivery.preflight.max*` thresholds the
- *      estimate exceeds).
+ *      estimate exceeds), plus `remoteVerified` / `remoteProbe` — the
+ *      issue #4483 deterministic remote evidence (`git remote get-url
+ *      origin` + bounded `git ls-remote origin HEAD`). On
+ *      `remoteVerified: false` the workflow MUST flip the Epic to
+ *      `agent::blocked` quoting `remoteProbe.detail` — inline delivery to
+ *      local `main` is never a sanctioned fallback.
  *   2. When `--post` is set (and `--dry-run` is not), an upserted
  *      `delivery-preflight` structured comment on the Epic ticket so
  *      reviewers reading the Epic discover the same numbers without
@@ -66,6 +71,7 @@ import {
   computeBaseSha,
   writePreflightCache,
 } from './lib/orchestration/preflight-cache.js';
+import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -218,10 +224,23 @@ export function renderPreflightBody({
   estimate,
   breaches,
   thresholds,
+  remote,
 }) {
   const lines = [];
   lines.push(`### 🛫 Delivery preflight — Epic #${epicId}`);
   lines.push('');
+  // Issue #4483 — verified remote evidence at entry. Rendered before the
+  // metric table so a reviewer (and the orchestrating agent) sees the
+  // land-or-block fact first. Omitted when the caller has no probe result
+  // (legacy callers / tests that only exercise the estimate math).
+  if (remote) {
+    lines.push(
+      remote.remoteVerified
+        ? `✅ **remoteVerified: true** — ${remote.detail}`
+        : `⛔ **remoteVerified: false** — ${remote.detail} — \`/deliver\` MUST transition the Epic to \`agent::blocked\` quoting this probe; inline delivery to local \`main\` is forbidden.`,
+    );
+    lines.push('');
+  }
   lines.push('| Metric | Estimate | Threshold |');
   lines.push('| --- | ---: | ---: |');
   const rows = [
@@ -276,6 +295,7 @@ export function renderPreflightBody({
  *   perStoryClaudeTokens?: number,
  *   injectedProvider?: object,
  *   injectedConfig?: object,
+ *   verifyRemoteFn?: typeof verifyRemote,
  * }} args
  */
 export async function runPreflight({
@@ -288,6 +308,7 @@ export async function runPreflight({
   perStoryClaudeTokens,
   injectedProvider,
   injectedConfig,
+  verifyRemoteFn = verifyRemote,
 }) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     throw new TypeError('runPreflight: --epic must be a positive integer');
@@ -297,6 +318,13 @@ export async function runPreflight({
   const provider = injectedProvider ?? createProvider(config);
   const thresholds = getPreflight(config);
 
+  // Issue #4483 — deterministic remote evidence at entry. Probe BEFORE any
+  // provider work so the envelope always carries verified fact (not the
+  // agent's perception) about whether a live, pushable `origin` exists.
+  // The CLI records; the `/deliver` workflow owns the `agent::blocked`
+  // transition on `remoteVerified: false` (same split as breach handling).
+  const remote = verifyRemoteFn({ cwd });
+
   // Compose the same two phases /deliver Phase 1 runs so the
   // preflight numbers match the actual dispatch plan.
   const ctx = { epicId, provider };
@@ -348,6 +376,13 @@ export async function runPreflight({
     thresholds,
     baseSha,
     cacheWritten,
+    // Issue #4483 — verified remote evidence. `remoteVerified: false`
+    // REQUIRES the workflow to block explicitly (never build inline).
+    remoteVerified: remote.remoteVerified,
+    remoteProbe: {
+      remoteUrl: remote.remoteUrl,
+      detail: remote.detail,
+    },
   };
 
   if (post && !dryRun) {
@@ -356,6 +391,7 @@ export async function runPreflight({
       estimate,
       breaches,
       thresholds,
+      remote,
     });
     await upsertStructuredComment(provider, epicId, 'delivery-preflight', body);
     envelope.commentUpserted = true;

package/.agents/scripts/lib/orchestration/lifecycle/listeners/finalizer.js

@@ -82,6 +82,7 @@ import {
   openOrLocatePr as defaultOpenOrLocatePr,
 } from '../../finalize/open-or-locate-pr.js';
 import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/post-handoff-comment.js';
+import { probeRemoteBranch as defaultProbeRemoteBranch } from '../../remote-verifier.js';
 
 /**
  * Build the production default `runFinalizeFn` that composes the
@@ -103,12 +104,22 @@ import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/
  * contract is identical and `markPrReady` is a no-op on an already-ready
  * PR, so replay stays idempotent.
  *
+ * Issue #4483 — deterministic land-or-block backstop. Before opening (or
+ * readying) the PR, finalize asserts the delivery branch `epic/<id>`
+ * actually exists on origin. A delivery that was never pushed — e.g. an
+ * agent that built the Epic inline on local `main` and skipped the
+ * orchestration — MUST surface as an explicit
+ * `delivery-branch-missing-on-origin` blocker (which keeps the Epic at
+ * `agent::blocked`), never a declared success. The probe is bounded
+ * (timeout + SIGKILL) so a hung remote degrades to a blocker too.
+ *
  * @param {{
  *   provider?: object|null,
  *   earlyPr?: boolean,
  *   openOrLocatePrFn?: typeof defaultOpenOrLocatePr,
  *   markPrReadyFn?: typeof defaultMarkPrReady,
  *   postHandoffCommentFn?: typeof defaultPostHandoffComment,
+ *   probeRemoteBranchFn?: typeof defaultProbeRemoteBranch,
  * }} deps
  */
 export function composeBusOwnedFinalize(deps = {}) {
@@ -116,6 +127,8 @@ export function composeBusOwnedFinalize(deps = {}) {
   const markPrReadyFn = deps.markPrReadyFn ?? defaultMarkPrReady;
   const postHandoffCommentFn =
     deps.postHandoffCommentFn ?? defaultPostHandoffComment;
+  const probeRemoteBranchFn =
+    deps.probeRemoteBranchFn ?? defaultProbeRemoteBranch;
   const provider = deps.provider ?? null;
   const earlyPr = deps.earlyPr !== false;
 
@@ -128,6 +141,25 @@ export function composeBusOwnedFinalize(deps = {}) {
         },
       };
     }
+
+    // Issue #4483 backstop — the delivery branch MUST be on origin before
+    // finalize declares any success. A never-pushed branch is the silent
+    // local-main failure shape; block explicitly with the probe detail.
+    let branchProbe;
+    try {
+      branchProbe = probeRemoteBranchFn({ branch: `epic/${epicId}`, cwd });
+    } catch (err) {
+      branchProbe = { exists: false, detail: err?.message ?? String(err) };
+    }
+    if (!branchProbe.exists) {
+      return {
+        blocker: {
+          reason: 'delivery-branch-missing-on-origin',
+          detail: `epic/${epicId} is not on origin — the delivery was never pushed; refusing to finalize (issue #4483). Probe: ${branchProbe.detail}`,
+        },
+      };
+    }
+
     let openResult;
     try {
       openResult = await openOrLocatePrFn({

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

@@ -0,0 +1,165 @@
+// .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.
+ *
+ * `/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 (`epic-deliver-preflight.js`, `single-story-init.js`) 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).
+ */
+
+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.
+ */
+export const REMOTE_PROBE_TIMEOUT_MS = 30_000;
+
+function runProbe({ args, cwd, spawnFn, timeoutMs }) {
+  const result = spawnFn('git', args, {
+    cwd,
+    encoding: 'utf-8',
+    shell: false,
+    timeout: timeoutMs,
+    killSignal: 'SIGKILL',
+  });
+  return {
+    args: ['git', ...args].join(' '),
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? '').trim(),
+    stderr: (result.stderr ?? '').trim(),
+  };
+}
+
+/**
+ * Probe the `origin` remote for existence + reachability.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   spawnFn?: typeof spawnSync,
+ *   timeoutMs?: number,
+ * }} [opts]
+ * @returns {{
+ *   remoteVerified: boolean,
+ *   remoteUrl: string|null,
+ *   detail: string,
+ *   probes: {
+ *     getUrl: { args: string, status: number, stdout: string, stderr: string },
+ *     lsRemote: { args: string, status: number, stdout: string, stderr: string }|null,
+ *   },
+ * }}
+ */
+export function verifyRemote({
+  cwd = process.cwd(),
+  spawnFn = spawnSync,
+  timeoutMs = REMOTE_PROBE_TIMEOUT_MS,
+} = {}) {
+  const getUrl = runProbe({
+    args: ['remote', 'get-url', 'origin'],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (getUrl.status !== 0) {
+    return {
+      remoteVerified: false,
+      remoteUrl: null,
+      detail: `no 'origin' remote configured — \`${getUrl.args}\` exited ${getUrl.status}: ${getUrl.stderr || '(no stderr)'}`,
+      probes: { getUrl, lsRemote: null },
+    };
+  }
+  const remoteUrl = getUrl.stdout;
+
+  const lsRemote = runProbe({
+    args: ['ls-remote', 'origin', 'HEAD'],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (lsRemote.status !== 0 || lsRemote.stdout.length === 0) {
+    return {
+      remoteVerified: false,
+      remoteUrl,
+      detail: `'origin' (${remoteUrl}) is unreachable — \`${lsRemote.args}\` exited ${lsRemote.status}: ${lsRemote.stderr || '(empty ls-remote output)'}`,
+      probes: { getUrl, lsRemote },
+    };
+  }
+
+  return {
+    remoteVerified: true,
+    remoteUrl,
+    detail: `origin verified (${remoteUrl}); ls-remote HEAD → ${lsRemote.stdout.split(/\s+/)[0]}`,
+    probes: { getUrl, lsRemote },
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {{
+ *   branch: string,
+ *   cwd?: string,
+ *   spawnFn?: typeof spawnSync,
+ *   timeoutMs?: number,
+ * }} opts
+ * @returns {{ exists: boolean, detail: string }}
+ */
+export function probeRemoteBranch({
+  branch,
+  cwd = process.cwd(),
+  spawnFn = spawnSync,
+  timeoutMs = REMOTE_PROBE_TIMEOUT_MS,
+}) {
+  if (typeof branch !== 'string' || branch.length === 0) {
+    throw new TypeError('probeRemoteBranch: branch must be a non-empty string');
+  }
+  const probe = runProbe({
+    args: ['ls-remote', '--heads', 'origin', branch],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (probe.status !== 0) {
+    return {
+      exists: false,
+      detail: `\`${probe.args}\` exited ${probe.status}: ${probe.stderr || '(no stderr)'}`,
+    };
+  }
+  if (probe.stdout.length === 0) {
+    return {
+      exists: false,
+      detail: `\`${probe.args}\` found no ref — ${branch} was never pushed to origin`,
+    };
+  }
+  return {
+    exists: true,
+    detail: `${branch} on origin at ${probe.stdout.split(/\s+/)[0]}`,
+  };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js

@@ -5,6 +5,16 @@
  * subsequent fetches are cheap. A push failure raises so the caller
  * fails non-zero — the operator must resolve before retrying.
  *
+ * Issue #4483 — this phase IS the standalone path's deterministic
+ * land-or-block backstop (the counterpart to the Epic finalize seam's
+ * `delivery-branch-missing-on-origin` blocker). `git push` exits 0 only
+ * after origin has accepted the ref, so the throw below is the origin
+ * assertion: every later close phase (PR open, auto-merge, the
+ * `closeResult` success envelope) is unreachable unless the Story branch
+ * verifiably landed on origin. No post-push `ls-remote` re-probe is
+ * added because it would re-ask a question the push exit code already
+ * answered authoritatively.
+ *
  * `gitSync` is accepted as an injected dependency rather than statically
  * imported so the caller's (cache-busted) binding wins. The
  * `single-story-close.js` orchestrator owns the static import; test

package/.agents/scripts/single-story-init.js

@@ -59,6 +59,7 @@ import {
   executeFastForward,
   planFastForward,
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
+import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { acquireStoryLease } from './lib/orchestration/single-story-lease-guard.js';
 import {
   STATE_LABELS,
@@ -446,6 +447,7 @@ export async function runSingleStoryInit({
   injectedAcquireLease,
   steal = false,
   leaseNow,
+  injectedVerifyRemote,
 } = {}) {
   const parsed =
     storyIdParam !== undefined
@@ -487,6 +489,20 @@ export async function runSingleStoryInit({
   );
   progress('INIT', `Initializing standalone Story #${storyId}...`);
 
+  // Issue #4483 — deterministic remote evidence at the standalone entry
+  // seam (the counterpart to `epic-deliver-preflight.js`'s probe). The
+  // probe is read-only, so it runs under --dry-run too. The CLI records
+  // the fact; the workflow owns the `agent::blocked` transition on
+  // `remoteVerified: false` — inline delivery to local `main` is never a
+  // sanctioned fallback.
+  const remote = (injectedVerifyRemote ?? verifyRemote)({ cwd });
+  progress(
+    'REMOTE',
+    remote.remoteVerified
+      ? `✅ remoteVerified=true — ${remote.detail}`
+      : `⛔ remoteVerified=false — ${remote.detail}`,
+  );
+
   const story = await provider.getTicket(storyId);
   assertDeliverableStory(story, storyId);
 
@@ -563,6 +579,9 @@ export async function runSingleStoryInit({
     dependenciesInstalled,
     installFailed: installStatus.status === 'failed',
     dryRun,
+    // Issue #4483 — verified remote evidence for the orchestrating agent.
+    remoteVerified: remote.remoteVerified,
+    remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
   // Upsert the `story-init` structured comment + flip Story to executing.
@@ -632,6 +651,8 @@ export function renderSingleStoryInitComment(result) {
     worktreeCreated: result.worktreeCreated,
     dependenciesInstalled: result.dependenciesInstalled,
     installStatus: result.installStatus,
+    remoteVerified: result.remoteVerified,
+    remoteProbe: result.remoteProbe,
   };
   return [
     '## Story init (standalone)',
@@ -641,6 +662,7 @@ export function renderSingleStoryInitComment(result) {
     `- **baseBranch:** \`${result.baseBranch}\``,
     `- **workCwd:** \`${result.workCwd}\``,
     `- **worktreeEnabled:** \`${result.worktreeEnabled}\``,
+    `- **remoteVerified:** \`${result.remoteVerified}\``,
     `- **dependenciesInstalled:** \`${result.dependenciesInstalled}\``,
     '',
     '```json',

package/.agents/workflows/deliver.md

@@ -131,6 +131,14 @@ the standalone segment; segments themselves remain strictly sequential.
 
 ## Constraints
 
+- **Land or block — never a silent local build (issue #4483).** The
+  helpers' orchestration path (worktrees, `story-<id>`/`epic/<id>` branches,
+  close-validation, PR) is the ONLY sanctioned delivery mechanism.
+  Executing story slices inline in this session and/or committing the
+  delivery to local `main` is expressly forbidden, regardless of how the
+  environment looks. Each path surfaces verified remote evidence
+  (`remoteVerified`) at entry; on `false`, transition the ticket to
+  `agent::blocked` quoting `remoteProbe.detail` and halt.
 - `/deliver` requires planned tickets: Epics at `agent::ready` (the
   Epic helper's preflight enforces this, per segment) or well-formed
   standalone Stories. Planning happens in [`/plan`](plan.md); the

package/.agents/workflows/helpers/deliver-epic.md

@@ -181,6 +181,17 @@ Threshold defaults live in `delivery.preflight.*` in `.agentrc.json`
 (all keys default to "no cap" — the gate is opt-in until an operator
 configures `maxStories` etc.).
 
+**Remote evidence — land or block (issue #4483).** The envelope also
+carries `remoteVerified` + `remoteProbe` (deterministic probes:
+`git remote get-url origin`, bounded `git ls-remote origin HEAD`). When
+`remoteVerified` is `false`, flip the Epic to `agent::blocked`, post a
+friction comment quoting `remoteProbe.detail`, and halt — the same
+explicit-block shape as #4425/#4480. NEVER fall back to executing Stories
+inline in this session or committing the delivery to local `main`; the
+worktree/branch/PR path below is the only sanctioned mechanism. Phase 7's
+finalize additionally refuses with a `delivery-branch-missing-on-origin`
+blocker when `epic/<epicId>` never reached origin.
+
 ### Phase 1 main — Seed the wave plan
 
 ```bash

package/.agents/workflows/helpers/single-story-deliver.md

@@ -97,6 +97,14 @@ Capture `workCwd` from the result envelope. Add `--dry-run` to inspect
 the planned actions without git or ticket mutations (dry-run also skips
 the lease and the sweep).
 
+**Remote evidence — land or block (issue #4483).** The envelope also
+carries `remoteVerified` + `remoteProbe` (`git remote get-url origin` +
+bounded `git ls-remote origin HEAD`). When `remoteVerified` is `false`,
+transition the Story to `agent::blocked` quoting `remoteProbe.detail` and
+stop. Implementing the Story inline outside the worktree/branch/PR path
+and/or committing it to local `main` is expressly forbidden — the close
+pipeline's push is the only sanctioned landing.
+
 ### Step 0.5 — `cd` into the workCwd
 
 ```bash

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.91.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.90.0...mandrel-v1.91.0) (2026-07-12)
+
+
+### Fixed
+
+* **deliver:** verify the remote at entry and assert the delivery branch on origin (refs [#4483](https://github.com/dsj1984/mandrel/issues/4483)) ([#4484](https://github.com/dsj1984/mandrel/issues/4484)) ([a99ca2f](https://github.com/dsj1984/mandrel/commit/a99ca2fc4c74f7c397041dc4c703d845fae640c2))
+
 ## [1.90.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.89.0...mandrel-v1.90.0) (2026-07-12)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.90.0",
+  "version": "1.91.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",