mandrel 2.8.0 → 2.9.0

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -0,0 +1,207 @@
+/**
+ * lib/orchestration/complexity-gate.js — plan-time ceremony-lite routing gate.
+ *
+ * A **deterministic, conservative** complexity gate that routes a planning seed
+ * onto either the full two-session plan/deliver ceremony (`full`) or a collapsed
+ * ceremony-lite path (`lite`). It exists because the full ceremony imposes a
+ * large fixed cost premium on genuinely trivial single-artifact scopes with no
+ * measured quality gain (Story #4683): the bench cohort spent ~52 turns on a
+ * hello-world scope a bare control delivered in ~6, and no path existed to opt
+ * trivial scopes out.
+ *
+ * ## What "lite" changes and — critically — what it never changes
+ *
+ * The lite route collapses the **advisory ceremony** only: the plan/deliver
+ * session split, the fresh-context critic ceremony, and the Tech-Spec authoring
+ * that a one-artifact scope does not earn. It **never** relaxes a non-negotiable.
+ * {@link LITE_PATH_INVARIANTS} is the machine-readable contract that the lite
+ * path still produces a Story ticket, still lands via a PR to `main`, still runs
+ * every repo quality gate, and still honours `rules/security-baseline.md`. Those
+ * gates run in `single-story-close.js` regardless of route; the gate cannot and
+ * does not switch them off. Every `lite` decision carries this frozen object on
+ * its `preserves` field so a downstream reader can assert the invariants held.
+ *
+ * ## Conservative by construction — full on any doubt
+ *
+ * The gate is total and pure: seed text + resolved config in, decision out. It
+ * routes `lite` **only** when every trivial-scope signal agrees; every other
+ * case — an empty/unreadable seed, a seed above the word ceiling, a seed
+ * enumerating more than one candidate artifact, or the gate disabled by config —
+ * falls to `full`. Being wrong toward `full` costs a session; being wrong toward
+ * `lite` would skip ceremony a real capability slice needs, so the tie always
+ * breaks to `full`.
+ *
+ * ## Threshold + operator override
+ *
+ * {@link DEFAULT_COMPLEXITY_GATE} is the single source of truth for the
+ * threshold. Operators tune it (or disable the gate entirely) via
+ * `planning.complexityGate` in `.agentrc.json`:
+ *
+ *   - `enabled`      (default `true`)  — `false` forces every seed to `full`.
+ *   - `maxSeedWords` (default `60`)    — seed prose word ceiling for `lite`.
+ *   - `maxArtifacts` (default `1`)     — enumerated-artifact ceiling for `lite`.
+ *
+ * Resolution clamps every field toward the conservative default: a malformed or
+ * negative ceiling falls back to the framework default rather than widening the
+ * lite path.
+ *
+ * @typedef {'lite'|'full'} ComplexityRoute
+ */
+
+/**
+ * Framework defaults for the plan-time complexity gate. The threshold SSOT —
+ * the config schema mirror and the configuration reference both cite these
+ * numbers rather than restating divergent ones.
+ */
+const DEFAULT_COMPLEXITY_GATE = Object.freeze({
+  enabled: true,
+  maxSeedWords: 60,
+  maxArtifacts: 1,
+});
+
+/**
+ * The non-negotiables the ceremony-lite path preserves. This is the
+ * contract behind Story #4683 AC-2: collapsing ceremony never means dropping
+ * the Story ticket, the PR-to-`main` landing, the repo quality gates, or the
+ * security baseline. Attached verbatim to every `lite` decision's `preserves`
+ * field; a downstream consumer (or contract test) asserts against it.
+ */
+const LITE_PATH_INVARIANTS = Object.freeze({
+  storyTicket: true,
+  prToMain: true,
+  repoGates: true,
+  securityBaseline: true,
+});
+
+/**
+ * Coerce a candidate ceiling into a non-negative integer, falling back to the
+ * framework default for anything malformed. Non-numbers, non-finite values, and
+ * negatives all fall back — a stray `-1` or `NaN` must never widen the lite path
+ * (the gate fails conservative, toward `full`).
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function normalizeCeiling(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+/**
+ * Resolve the effective complexity-gate config, shallow-overlaying an operator
+ * `planning.complexityGate` block onto {@link DEFAULT_COMPLEXITY_GATE}. Accepts
+ * the full resolved config, the bare `planning` bag, or the bare
+ * `complexityGate` bag, mirroring the tolerant unwrap the other routing
+ * accessors use. Module-private: exposed only through the resolved `threshold`
+ * on {@link buildComplexityRouteSignal}'s output, so there is no test-only
+ * export to leave production-dead.
+ *
+ * @param {object | null | undefined} config
+ * @returns {{ enabled: boolean, maxSeedWords: number, maxArtifacts: number }}
+ */
+function resolveComplexityGate(config) {
+  const raw =
+    config?.planning?.complexityGate ?? config?.complexityGate ?? config ?? {};
+  const bag = raw && typeof raw === 'object' ? raw : {};
+  return {
+    enabled:
+      typeof bag.enabled === 'boolean'
+        ? bag.enabled
+        : DEFAULT_COMPLEXITY_GATE.enabled,
+    maxSeedWords: normalizeCeiling(
+      bag.maxSeedWords,
+      DEFAULT_COMPLEXITY_GATE.maxSeedWords,
+    ),
+    maxArtifacts: normalizeCeiling(
+      bag.maxArtifacts,
+      DEFAULT_COMPLEXITY_GATE.maxArtifacts,
+    ),
+  };
+}
+
+/**
+ * Count top-level enumerated items (`- `, `* `, `1. `) in a free-form seed —
+ * the same shape the scope-triage and delivery-shape signals read as candidate
+ * capabilities. Each enumerated line is one predicted artifact; a seed with two
+ * or more is a multi-capability scope that must take the full path.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countSeedArtifacts(text) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  return text
+    .split(/\r?\n/)
+    .filter((line) => /^\s*(?:[-*]|\d+\.)\s+\S/.test(line)).length;
+}
+
+/**
+ * Build the advisory complexity-route signal for a planning seed. Deterministic,
+ * total, and conservative (see the module header): every trivial-scope signal
+ * must agree for a `lite` decision; everything else routes `full`.
+ *
+ * The result is folded into the `/plan` context envelope as `complexityRoute`,
+ * so the workflow reads one field instead of re-deriving the decision. Every
+ * `lite` decision carries {@link LITE_PATH_INVARIANTS} on `preserves`.
+ *
+ * @param {{ seedText?: string, config?: object }} [args]
+ * @returns {{
+ *   route: ComplexityRoute,
+ *   reasons: string[],
+ *   threshold: { enabled: boolean, maxSeedWords: number, maxArtifacts: number },
+ *   preserves: typeof LITE_PATH_INVARIANTS,
+ *   advisory: true,
+ * }}
+ */
+export function buildComplexityRouteSignal({ seedText = '', config } = {}) {
+  const threshold = resolveComplexityGate(config);
+  const advisory = /** @type {const} */ (true);
+  const preserves = LITE_PATH_INVARIANTS;
+  const decide = (route, reason) => ({
+    route,
+    reasons: [reason],
+    threshold,
+    preserves,
+    advisory,
+  });
+
+  if (!threshold.enabled) {
+    return decide(
+      'full',
+      'complexity gate disabled (planning.complexityGate.enabled=false) — full plan/deliver ceremony',
+    );
+  }
+
+  const text = typeof seedText === 'string' ? seedText : '';
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return decide(
+      'full',
+      'empty seed — triviality cannot be judged; conservative full path',
+    );
+  }
+
+  const artifactCount = countSeedArtifacts(text);
+  if (artifactCount > threshold.maxArtifacts) {
+    return decide(
+      'full',
+      `seed enumerates ${artifactCount} candidate artifacts (> maxArtifacts ${threshold.maxArtifacts}) — multi-capability scope takes the full path`,
+    );
+  }
+
+  const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+  if (wordCount > threshold.maxSeedWords) {
+    return decide(
+      'full',
+      `seed is ${wordCount} words (> maxSeedWords ${threshold.maxSeedWords}) — not a trivial scope; full path`,
+    );
+  }
+
+  return decide(
+    'lite',
+    `trivial single-artifact scope (${wordCount} words ≤ ${threshold.maxSeedWords}, ${artifactCount} enumerated artifact(s) ≤ ${threshold.maxArtifacts}) — collapsed ceremony-lite path; non-negotiables preserved`,
+  );
+}

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -26,6 +26,7 @@ import {
   renderTechSpecSystemPrompt,
 } from '../templates/spec-author-prompts.js';
 import { concurrentMap } from '../util/concurrent-map.js';
+import { buildComplexityRouteSignal } from './complexity-gate.js';
 import { parseDeliverySlicingTable } from './consolidation-precondition.js';
 import { buildDocsDigest } from './docs-digest.js';
 import { buildAuthoringContext } from './planning/authoring-context.js';
@@ -482,6 +483,7 @@ async function buildSeedFileModeEnvelope({
   return {
     mode: modeLabel,
     seed: { path: seedFilePath ?? null, content },
+    complexityRoute: buildComplexityRouteSignal({ seedText: content, config }),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -635,6 +637,7 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
+    complexityRoute: buildComplexityRouteSignal({ seedText: seed, config }),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,

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

@@ -23,6 +23,42 @@
  * no-op. `--delete-branch` is preserved verbatim, so the PR head branch is
  * still deleted on merge without depending on the repo's auto-delete
  * setting. Resolution is non-fatal — it degrades to the original cwd.
+ *
+ * Story #4681 made the arm survive a LOCAL-ONLY cleanup failure. Against an
+ * already-mergeable PR, `gh pr merge --auto --squash --delete-branch` merges
+ * immediately and then shells out to local `git` to drop the head branch.
+ * When the per-Story worktree still holds `story-<id>`, that local delete
+ * fails (`Cannot delete branch 'story-<id>' used by worktree at …`) and `gh`
+ * exits non-zero — even though the REMOTE merge already landed. Reporting
+ * that as an arm failure sent close's confirm phase straight to
+ * `blockOnUnlanded`, flipping a merged Story to a stale `agent::blocked` that
+ * only a hand-run `single-story-confirm-merge.js` could undo. The failure is
+ * now classified: a local-cleanup-only signature reports the arm as ENABLED
+ * with `localCleanupDeferred: true`, so the confirm phase polls the PR
+ * (observes MERGED) and the post-land tail reaps the local ref. Every other
+ * non-zero exit — a genuinely refused REMOTE merge — keeps the pre-existing
+ * `enabled: false` → blocked behaviour verbatim.
+ *
+ * Story #4682 restored the direct-merge fallback the v2.0.0 Story-only cutover
+ * dropped (originally PR #4480 / Story #4472, in the retired `AutomergeArmer`).
+ * GitHub native auto-merge (`gh pr merge --auto`) can only be QUEUED on a repo
+ * that has the "Allow auto-merge" setting enabled — which in practice requires
+ * branch protection. A repo with NO required checks and NO branch protection
+ * (every mandrel-bench sandbox, many real consumer repos) refuses the `--auto`
+ * arm: either "auto-merge is not allowed for this repository", or — once the
+ * PR has settled to an immediately-mergeable state, which the SECOND delivery
+ * into a warm repo reaches faster than the first into a cold one — the
+ * `enablePullRequestAutoMerge` "Pull request is in clean status" refusal. The
+ * close gates and Story-scope review have already cleared the merge by the
+ * time the arm runs, so the safe, must-land-satisfying response is a direct
+ * immediate squash-merge (no `--auto`). When the `--auto` failure matches the
+ * narrow {@link isAutoMergeUnavailable} signature, `enableAutoMergeWith`
+ * retries `gh pr merge --squash --delete-branch` and reports
+ * `{ enabled: true, directMerged: true }` on success — so the confirm phase
+ * polls the PR, observes MERGED, and lands it instead of blocking a PR that
+ * would never merge on its own. Every OTHER `--auto` failure — a genuine
+ * conflict, a red required check, an auth fault — matches neither the
+ * local-cleanup nor the unavailable signature and keeps blocking verbatim.
  */
 
 import { gh as defaultGh } from '../../../gh-exec.js';
@@ -52,6 +88,123 @@ export function isOperatorMergeReason(reason) {
   return OPERATOR_MERGE_ARM_REASONS.includes(reason);
 }
 
+/**
+ * Signatures of a `gh pr merge --delete-branch` failure whose ONLY casualty
+ * is the LOCAL head-branch cleanup that runs *after* the remote merge has
+ * already been performed (or auto-merge already armed).
+ *
+ * Each pattern is emitted by local `git` (or `gh`'s wrapper around it) and
+ * names branch DELETION specifically:
+ *   - `Cannot delete branch '<name>' used by worktree at …` — `git branch -D`
+ *     refusing a ref another worktree has checked out (the Story #4681 report).
+ *   - `failed to delete local branch …` — `gh`'s own wrapper wording.
+ *
+ * Deliberately narrow on two fronts. A genuinely refused REMOTE merge ("Pull
+ * request is not mergeable", a required status check, branch protection)
+ * matches neither pattern and keeps the existing blocked path. Nor does the
+ * bare `fatal: '<base>' is already used by worktree` checkout collision Story
+ * #4282 defends against: that one aborts `gh` *before* the branch delete and
+ * carries no evidence the merge stands, so it must keep failing the arm.
+ */
+const LOCAL_CLEANUP_FAILURE =
+  /cannot delete branch[^\n]*used by worktree|failed to delete (?:the )?local branch/i;
+
+/**
+ * Whether a non-zero `gh pr merge` exit is attributable solely to local
+ * branch cleanup, leaving the remote merge/arm itself intact.
+ *
+ * Module-private on purpose: `enableAutoMergeWith` is the only caller and the
+ * only surface worth pinning, so the classification is asserted through it
+ * rather than through a test-only export.
+ *
+ * @param {string|undefined|null} stderr
+ * @returns {boolean}
+ */
+function isLocalCleanupOnlyFailure(stderr) {
+  return LOCAL_CLEANUP_FAILURE.test(String(stderr ?? ''));
+}
+
+/**
+ * Pure: does a `gh pr merge --auto` stderr indicate that GitHub native
+ * auto-merge is UNAVAILABLE on this repository / PR — as opposed to a genuine
+ * arm failure (a merge conflict, a red required check, an auth fault)?
+ *
+ * Two distinct refusals both mean "there is no queued auto-merge for this repo,
+ * merge it directly instead", and both are safe to retry as an immediate
+ * squash-merge:
+ *
+ *   - **"auto-merge is not allowed for this repository"** — the repo has no
+ *     "Allow auto-merge" setting (no branch protection). Constant per repo.
+ *   - **"Pull request is in clean status"** — the `enablePullRequestAutoMerge`
+ *     GraphQL mutation refuses to queue a merge on a PR that is ALREADY
+ *     immediately mergeable with nothing to wait for (no required checks
+ *     pending). This is the second-delivery wedge (Story #4682): the first
+ *     delivery into a cold sandbox arms while GitHub is still computing the
+ *     fresh PR's mergeability (the arm queues, then merges); the second
+ *     delivery into the now-warm repo hits an instantly-clean PR, so the arm
+ *     is refused here.
+ *
+ * Only these classes fall through to the direct-merge fallback; everything
+ * else (an unmatched non-zero exit) keeps the `enabled: false` → blocked path.
+ * Matched case-insensitively.
+ *
+ * Module-private on purpose (mirroring {@link isLocalCleanupOnlyFailure}):
+ * `enableAutoMergeWith` is the only caller, so the marker set is asserted
+ * through it rather than through a test-only export the production dead-export
+ * ratchet would then flag.
+ *
+ * @param {string|undefined|null} stderr
+ * @returns {boolean}
+ */
+function isAutoMergeUnavailable(stderr) {
+  const text = String(stderr ?? '').toLowerCase();
+  return (
+    text.includes('auto merge is not allowed') ||
+    text.includes('auto-merge is not allowed') ||
+    text.includes('enablepullrequestautomerge') ||
+    text.includes('clean status') ||
+    (text.includes('auto') && text.includes('not enabled'))
+  );
+}
+
+/**
+ * Direct (non-`--auto`) squash-merge fallback (Story #4682, restoring PR
+ * #4480 / Story #4472). Reached only when the `--auto` arm was refused with
+ * the {@link isAutoMergeUnavailable} signature — a repo with no native
+ * auto-merge, or an already-clean PR with nothing to queue behind. Omitting
+ * `--auto` makes `gh` merge synchronously; the same `--squash --delete-branch`
+ * shape and the same `armCwd` re-point are preserved so the trailing local
+ * `--delete-branch` housekeeping runs from the primary worktree (Story #4282).
+ *
+ * A local-cleanup-only grumble on the direct merge (Story #4681) still means
+ * the REMOTE merge landed, so it reports `directMerged` with
+ * `localCleanupDeferred`. Any other non-zero exit is a genuine failure the
+ * caller escalates.
+ *
+ * @returns {Promise<{ enabled: boolean, directMerged?: boolean, localCleanupDeferred?: boolean, reason?: string }>}
+ */
+async function directMergeFallback({ exec, prNumber, armCwd, autoReason }) {
+  const direct = await exec(
+    ['pr', 'merge', String(prNumber), '--squash', '--delete-branch'],
+    { cwd: armCwd },
+  );
+  if (direct.status === 0) {
+    return { enabled: true, directMerged: true, reason: autoReason };
+  }
+  if (isLocalCleanupOnlyFailure(direct.stderr)) {
+    return {
+      enabled: true,
+      directMerged: true,
+      localCleanupDeferred: true,
+      reason: autoReason,
+    };
+  }
+  return {
+    enabled: false,
+    reason: `direct-merge fallback failed after auto-merge unavailable (${autoReason}); gh-exit-${direct.status}: ${(direct.stderr ?? '').trim().slice(0, 160)}`,
+  };
+}
+
 /**
  * Enable GitHub native auto-merge on the PR. Non-fatal.
  *
@@ -62,7 +215,7 @@ export function isOperatorMergeReason(reason) {
  *   runner?: (args: string[], opts: object) => ({ status: number, stdout?: string, stderr?: string } | Promise<{ status: number, stdout?: string, stderr?: string }>),
  *   resolveArmCwd?: (cwd: string) => string,
  * }} opts
- * @returns {Promise<{ enabled: boolean, reason?: string }>}
+ * @returns {Promise<{ enabled: boolean, reason?: string, localCleanupDeferred?: boolean, directMerged?: boolean }>}
  */
 export async function enableAutoMergeWith({
   cwd,
@@ -89,10 +242,25 @@ export async function enableAutoMergeWith({
       { cwd: armCwd },
     );
     if (result.status === 0) return { enabled: true };
-    return {
-      enabled: false,
-      reason: `gh-exit-${result.status}: ${(result.stderr ?? '').trim().slice(0, 200)}`,
-    };
+    const detail = `gh-exit-${result.status}: ${(result.stderr ?? '').trim().slice(0, 200)}`;
+    if (isLocalCleanupOnlyFailure(result.stderr)) {
+      // The remote side stands; only the local head-branch cleanup failed.
+      // Report ENABLED so the confirm phase polls the real PR state instead
+      // of blocking a merge that already landed, and flag the deferred
+      // cleanup for the land tail's `git branch -D` to finish.
+      return { enabled: true, localCleanupDeferred: true, reason: detail };
+    }
+    if (isAutoMergeUnavailable(result.stderr)) {
+      // No native auto-merge on this repo (or nothing to queue behind an
+      // already-clean PR): merge directly so the PR still lands (Story #4682).
+      return directMergeFallback({
+        exec,
+        prNumber,
+        armCwd,
+        autoReason: detail,
+      });
+    }
+    return { enabled: false, reason: detail };
   } catch (err) {
     return { enabled: false, reason: `gh-spawn-error: ${err?.message ?? err}` };
   }
@@ -167,7 +335,11 @@ function makeDefaultGhAutoMergeRunner(gh) {
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
  *   progress: (tag: string, msg: string) => void,
  * }} args
- * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null }>}
+ * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null, localCleanupDeferred?: boolean, directMerged?: boolean }>}
+ *   `localCleanupDeferred` is true when the arm stands but `gh`'s local
+ *   head-branch delete failed (Story #4681) — the land tail owns the reap.
+ *   `directMerged` is true when native auto-merge was unavailable and the PR
+ *   was landed by a direct squash-merge instead (Story #4682).
  */
 export async function runAutoMergePhase({
   cwd,
@@ -211,15 +383,56 @@ export async function runAutoMergePhase({
   }
   const result = await enableAutoMergeWith({ cwd, prNumber, gh });
   if (result.enabled) {
+    if (result.directMerged) {
+      // No native auto-merge on this repo — the PR was merged directly
+      // instead of queued (Story #4682). The confirm phase polls the PR,
+      // observes MERGED, and runs the land tail; `localCleanupDeferred`
+      // still defers a local-ref reap when gh's `--delete-branch` grumbled.
+      progress(
+        'PR',
+        `✅ Native auto-merge unavailable on PR #${prNumber} — direct squash-merge landed it` +
+          (result.localCleanupDeferred
+            ? " (gh's LOCAL branch cleanup deferred to the land tail; the merge stands)."
+            : '.'),
+      );
+      return {
+        autoMergeEnabled: true,
+        autoMergeReason: null,
+        directMerged: true,
+        localCleanupDeferred: Boolean(result.localCleanupDeferred),
+      };
+    }
+    if (result.localCleanupDeferred) {
+      // Warning, never a block (Story #4681): the merge/arm stands and the
+      // land tail reaps the local ref once the worktree releases it.
+      progress(
+        'PR',
+        `⚠️ Auto-merge armed on PR #${prNumber}, but gh's LOCAL branch cleanup failed ` +
+          `(${result.reason}) — deferring the local ref reap to the land tail; the merge stands.`,
+      );
+      return {
+        autoMergeEnabled: true,
+        autoMergeReason: null,
+        localCleanupDeferred: true,
+      };
+    }
     progress(
       'PR',
       `✅ Auto-merge enabled on PR #${prNumber} (squash, delete-branch).`,
     );
-    return { autoMergeEnabled: true, autoMergeReason: null };
+    return {
+      autoMergeEnabled: true,
+      autoMergeReason: null,
+      localCleanupDeferred: false,
+    };
   }
   progress(
     'PR',
     `⚠️ Auto-merge enablement failed (${result.reason}) — operator can merge manually.`,
   );
-  return { autoMergeEnabled: false, autoMergeReason: result.reason };
+  return {
+    autoMergeEnabled: false,
+    autoMergeReason: result.reason,
+    localCleanupDeferred: false,
+  };
 }

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

@@ -7,6 +7,7 @@ import { resolveConfig } from '../../config-resolver.js';
 import { getStoryBranch, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
 import { emitTerminalFriction } from '../../observability/runtime-friction.js';
+import { emitTerseResult } from '../../observability/terse-result.js';
 import { createProvider } from '../../provider-factory.js';
 import { flipLabelAndNotify } from '../../single-story/story-merged-notify.js';
 import { WorktreeManager } from '../../worktree-manager.js';
@@ -53,12 +54,22 @@ const progress = Logger.createProgress('single-story-close', { stderr: true });
  * The emit is best-effort internally and cannot throw.
  */
 async function emitTerminal({ terminal, result, config }) {
-  // The human-facing result dump stays level-gated; the terminal envelope is
-  // the machine contract and must survive AGENT_LOG_LEVEL=silent.
+  // Story #4685 — the human-facing result dump goes to a temp log; the agent
+  // acts on the (separate, unsuppressible) terminal envelope emitted below.
+  // The single summary line keeps the fields worth an at-a-glance read.
   if (result) {
-    Logger.info(
-      `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
-    );
+    emitTerseResult({
+      label: 'STORY CLOSE RESULT',
+      result,
+      scope: result.storyId,
+      summary: {
+        storyId: result.storyId,
+        action: result.action,
+        reason: result.reason,
+        prNumber: result.prNumber,
+        status: terminal?.status,
+      },
+    });
   }
   emitTerminalEnvelope(terminal);
   await emitTerminalFriction({ envelope: terminal, config });
@@ -311,6 +322,8 @@ function closeResult({
   autoMergeReason,
   worktreeReaped,
   leaseReleased,
+  localCleanupDeferred = false,
+  directMerged = false,
   waitedForMerge = false,
   merged = false,
 }) {
@@ -326,6 +339,15 @@ function closeResult({
     autoMergeReason,
     worktreeReaped,
     leaseReleased,
+    // Story #4681 — `gh`'s local head-branch delete failed while the remote
+    // merge/arm stood. Surfaced so the land is auditable as
+    // merged-with-deferred-cleanup rather than silently degraded.
+    localCleanupDeferred,
+    // Story #4682 — native auto-merge was unavailable (no branch protection /
+    // an already-clean PR), so the PR was landed by a direct squash-merge.
+    // Surfaced so a checks-less land is auditable rather than looking like a
+    // queued auto-merge that never fired.
+    directMerged,
     waitedForMerge,
     merged,
     note: waitedForMerge
@@ -486,8 +508,31 @@ async function runClosePipeline({
       }),
     leaseArgs,
   );
+  // Reap the per-Story worktree BEFORE the arm (Story #4681). Arming runs
+  // `gh pr merge --auto --squash --delete-branch`, which — against an
+  // already-mergeable PR — merges immediately and then shells out to local
+  // `git` to drop `story-<id>`. A live worktree still holding that ref makes
+  // the local delete fail, `gh` exit non-zero, and the arm read as failed,
+  // which used to strand a genuinely merged PR at `agent::blocked`.
+  // Pre-empting the hold is the ordering half of the fix (the tolerate half
+  // lives in `phases/auto-merge.js`); it is safe here because push and PR
+  // creation already made the work durable off-machine, and `isSafeToRemove`
+  // still refuses a dirty tree.
+  const worktreeReaped = await reapWorktreePhase({
+    cwd: options.cwd,
+    storyId: options.storyId,
+    worktreePath,
+    wtIsolation: config.delivery?.worktreeIsolation,
+    progress,
+    WorktreeManager,
+  });
   setPhase('auto-merge');
-  const { autoMergeEnabled, autoMergeReason } = await runAutoMergePhase({
+  const {
+    autoMergeEnabled,
+    autoMergeReason,
+    localCleanupDeferred,
+    directMerged,
+  } = await runAutoMergePhase({
     cwd: options.cwd,
     prNumber,
     prUrl,
@@ -507,14 +552,6 @@ async function runClosePipeline({
     config,
     progress,
   });
-  const worktreeReaped = await reapWorktreePhase({
-    cwd: options.cwd,
-    storyId: options.storyId,
-    worktreePath,
-    wtIsolation: config.delivery?.worktreeIsolation,
-    progress,
-    WorktreeManager,
-  });
   const leaseReleased = await releaseLease(leaseArgs);
 
   // Close-and-land (Story #4428; default since `delivery.routing.closeAndLand`
@@ -589,6 +626,8 @@ async function runClosePipeline({
       autoMergeReason,
       worktreeReaped,
       leaseReleased,
+      localCleanupDeferred,
+      directMerged,
       waitedForMerge: true,
       merged: waitOutcome.confirmed === true,
     });
@@ -625,6 +664,8 @@ async function runClosePipeline({
     autoMergeReason,
     worktreeReaped,
     leaseReleased,
+    localCleanupDeferred,
+    directMerged,
   });
   // `--no-wait-merge` / operator-merge: the PR is open and the human owns
   // the land. That is a `pending` terminal by definition — the work is not

package/.agents/scripts/lib/orchestration/story-close/emit-blocked.js

@@ -5,6 +5,7 @@
  */
 
 import { Logger } from '../../Logger.js';
+import { emitTerseResult } from '../../observability/terse-result.js';
 
 /**
  * Best-effort `story.blocked` lifecycle emit. The bus is optional and emit
@@ -41,9 +42,14 @@ export async function emitBlockedCloseResult({
 }) {
   const result = { success: false, status: 'blocked', phase, reason, ...extra };
   await emitStoryBlockedSafe({ bus, storyId, reason, logger });
-  logger.info?.(
-    `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
-  );
+  // Story #4685 — full detail to a temp log; single summary line in its place.
+  emitTerseResult({
+    label: 'STORY CLOSE RESULT',
+    result,
+    scope: storyId,
+    summary: { storyId, status: 'blocked', phase, reason },
+    log: logger,
+  });
   progress('BLOCKED', blockedMessage);
   return result;
 }

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -263,8 +263,11 @@ export function emitTerminalEnvelope(
   envelope,
   { write = (s) => process.stdout.write(s) } = {},
 ) {
+  // Story #4685 — compact (not 2-space pretty) JSON. The envelope is a
+  // machine contract callers recover with `JSON.parse`, so pretty-printing
+  // only adds turn-resident bytes without helping any consumer.
   write(
-    `\n${TERMINAL_BEGIN_MARKER}\n${JSON.stringify(envelope, null, 2)}\n${TERMINAL_END_MARKER}\n`,
+    `\n${TERMINAL_BEGIN_MARKER}\n${JSON.stringify(envelope)}\n${TERMINAL_END_MARKER}\n`,
   );
 }