mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/worktree/lifecycle/force-drain.js

@@ -118,10 +118,89 @@ export function findHoldersInPath(wtPath, opts = {}) {
     }));
 }
 
+/**
+ * Pure: compute the set of pids that must never be killed — `selfPid` plus
+ * its full ancestor chain — from a process table of `{ pid, ppid }` rows.
+ * Cycle-guarded (a corrupt/raced table cannot loop forever). `selfPid` is
+ * always included even when the table is empty or missing its row, so the
+ * guard fails safe.
+ *
+ * @param {number} selfPid
+ * @param {Array<{ pid: number, ppid?: number }>} table
+ * @returns {Set<number>}
+ */
+export function computeProtectedPids(selfPid, table) {
+  const protectedPids = new Set([selfPid]);
+  if (!Array.isArray(table) || table.length === 0) return protectedPids;
+  const parentOf = new Map();
+  for (const row of table) {
+    if (row && typeof row.pid === 'number' && typeof row.ppid === 'number') {
+      parentOf.set(row.pid, row.ppid);
+    }
+  }
+  let cursor = selfPid;
+  while (parentOf.has(cursor)) {
+    const ppid = parentOf.get(cursor);
+    if (protectedPids.has(ppid)) break; // cycle guard
+    protectedPids.add(ppid);
+    cursor = ppid;
+  }
+  return protectedPids;
+}
+
+/**
+ * Enumerate the full Windows process table as `{ pid, ppid }` rows so the
+ * kill set can exclude the invoking shell / orchestrator ancestry.
+ * Best-effort: any failure returns `[]` (callers still protect `selfPid`).
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.spawn] Injection point for tests (default `spawnSync`).
+ * @param {string} [opts.platform] Override `process.platform` for tests.
+ * @returns {Array<{ pid: number, ppid: number }>}
+ */
+export function fetchProcessTable(opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const platform = opts.platform ?? process.platform;
+  if (platform !== 'win32') return [];
+
+  const script =
+    'Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId | ConvertTo-Json -Compress';
+  let res;
+  try {
+    res = spawn(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-Command', script],
+      { encoding: 'utf8', timeout: 15_000 },
+    );
+  } catch {
+    return [];
+  }
+  if (!res || res.status !== 0 || !res.stdout) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(String(res.stdout).trim());
+  } catch {
+    return [];
+  }
+  const list = Array.isArray(parsed) ? parsed : [parsed];
+  return list
+    .filter((p) => p && typeof p.ProcessId === 'number')
+    .map((p) => ({
+      pid: p.ProcessId,
+      ppid: typeof p.ParentProcessId === 'number' ? p.ParentProcessId : -1,
+    }));
+}
+
 /**
  * `taskkill /T /F /PID <pid>` for each holder. Returns the pids reported
  * as terminated. Per-pid failures are logged but do not throw — caller
  * decides whether the partial kill is enough to retry.
+ *
+ * Self-preservation (Story #4018): holders are matched by command-line
+ * substring, which can select the invoking shell or the orchestrator's own
+ * ancestor chain (any ancestor whose command line mentions the worktree
+ * path). Before any `taskkill /T /F`, the kill set excludes `selfPid` and
+ * its full ancestor chain — `/T` on an ancestor would kill this process too.
  */
 export function terminateHolders(holders, opts = {}) {
   const spawn = opts.spawn ?? spawnSync;
@@ -130,9 +209,20 @@ export function terminateHolders(holders, opts = {}) {
   if (platform !== 'win32') return [];
   if (!Array.isArray(holders) || holders.length === 0) return [];
 
+  const selfPid = opts.selfPid ?? process.pid;
+  const protectedPids =
+    opts.protectedPids ??
+    computeProtectedPids(selfPid, fetchProcessTable({ spawn, platform }));
+
   const killed = [];
   for (const h of holders) {
     if (!h || typeof h.pid !== 'number') continue;
+    if (protectedPids.has(h.pid)) {
+      logger.warn(
+        `force-drain: skipping pid=${h.pid} name=${h.name ?? '?'} — self/ancestor of this process (never killed)`,
+      );
+      continue;
+    }
     let res;
     try {
       res = spawn('taskkill.exe', ['/T', '/F', '/PID', String(h.pid)], {

package/.agents/scripts/lib/worktree/lifecycle/reap.js

@@ -134,7 +134,7 @@ async function fsRmWithRetry(
       return { success: true, attempts: attempt };
     } catch (err) {
       lastErr = err;
-      if (attempt < maxRetries) {
+      if (attempt < maxRetries && retryDelay > 0) {
         await new Promise((r) => setTimeout(r, retryDelay));
       }
     }
@@ -160,8 +160,8 @@ function handleRemoveFailure(
   classification,
   attempt,
   maxAttempts,
+  { retryDelaysMs = [0, 150, 350, 700, 1200, 2000], sleepFn = sleepSync } = {},
 ) {
-  const retryDelaysMs = [0, 150, 350, 700, 1200, 2000];
   const { isLockLike, isCwdLike } = classification;
   if ((isLockLike || isCwdLike) && attempt < maxAttempts) {
     const delay = retryDelaysMs[attempt] ?? 300;
@@ -169,13 +169,13 @@ function handleRemoveFailure(
     ctx.logger.warn(
       `worktree.reap remove hit ${reasonClass} error; retrying in ${delay}ms (${attempt}/${maxAttempts})`,
     );
-    sleepSync(delay);
+    sleepFn(delay);
     return 'continue';
   }
   return 'break';
 }
 
-async function runGitWorktreeRemoveLoop(ctx, wtPath) {
+async function runGitWorktreeRemoveLoop(ctx, wtPath, retryOpts = {}) {
   const maxAttempts = ctx.platform === 'win32' ? 6 : 2;
   let lastReason = 'worktree-remove-failed';
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -193,6 +193,7 @@ async function runGitWorktreeRemoveLoop(ctx, wtPath) {
       classification,
       attempt,
       maxAttempts,
+      retryOpts,
     );
     if (action === 'break') break;
   }
@@ -205,6 +206,7 @@ function tryForceRemoveFallback(
   lastReason,
   forceRemoveBackoffMs,
   maxAttempts,
+  sleepFn = sleepSync,
 ) {
   if (!(WINDOWS_LOCK_RE.test(lastReason) || WINDOWS_CWD_RE.test(lastReason))) {
     return { handled: false, lastReason };
@@ -212,7 +214,7 @@ function tryForceRemoveFallback(
   ctx.logger.warn(
     `worktree.reap remove exhausted Windows lock retry; retrying with --force in ${forceRemoveBackoffMs}ms path=${wtPath}`,
   );
-  sleepSync(forceRemoveBackoffMs);
+  sleepFn(forceRemoveBackoffMs);
   const forced = ctx.git.gitSpawn(
     ctx.repoRoot,
     'worktree',
@@ -248,8 +250,9 @@ async function tryStage15WindowsFsRm({
   push,
   lastReason,
   priorAttempts,
+  sleepFn = sleepSync,
 }) {
-  sleepSync(forceRemoveBackoffMs);
+  sleepFn(forceRemoveBackoffMs);
   try {
     await fsRm(wtPath, {
       recursive: true,
@@ -304,6 +307,7 @@ async function handleFsRmFailure({
   lastReason,
   forceRemoveBackoffMs,
   fsRm,
+  sleepFn,
 }) {
   // Stage 1.5 — coverage-leak quiesce + extended fs.rm budget (Windows only).
   if (ctx.platform === 'win32') {
@@ -316,6 +320,7 @@ async function handleFsRmFailure({
       push,
       lastReason,
       priorAttempts: rmResult.attempts,
+      sleepFn,
     });
     if (stage15) return stage15;
   }
@@ -347,7 +352,12 @@ async function handleFsRmFailure({
 export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
   const { storyId = null, branch = null, push = false } = opts;
   const forceRemoveBackoffMs = opts.forceRemoveBackoffMs ?? 3000;
-  const removeLoop = await runGitWorktreeRemoveLoop(ctx, wtPath);
+  const retryDelay = opts.retryDelay ?? 200;
+  const { retryDelaysMs, sleepFn } = opts;
+  const removeLoop = await runGitWorktreeRemoveLoop(ctx, wtPath, {
+    ...(retryDelaysMs ? { retryDelaysMs } : {}),
+    ...(sleepFn ? { sleepFn } : {}),
+  });
   if (removeLoop.removed) return { removed: true };
   let { lastReason } = removeLoop;
   if (ctx.platform === 'win32' && opts.forceRemoveFallback !== false) {
@@ -357,6 +367,7 @@ export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
       lastReason,
       forceRemoveBackoffMs,
       removeLoop.maxAttempts,
+      sleepFn,
     );
     if (fallback.handled) return fallback.result;
     lastReason = fallback.lastReason;
@@ -367,7 +378,7 @@ export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
   const fsRm = ctx.fsRm ?? fsPromisesRm;
   const rmResult = await fsRmWithRetry(fsRm, wtPath, {
     maxRetries: 5,
-    retryDelay: 200,
+    retryDelay,
   });
   if (!rmResult.success) {
     return handleFsRmFailure({
@@ -380,6 +391,7 @@ export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
       lastReason,
       forceRemoveBackoffMs,
       fsRm,
+      sleepFn,
     });
   }
   finalizeGitWorktreeRemove(ctx);
@@ -571,6 +583,12 @@ export async function reap(ctx, storyId, opts = {}) {
     storyId: storyIdN,
     branch,
     push: opts.push === true,
+    ...(opts.retryDelaysMs ? { retryDelaysMs: opts.retryDelaysMs } : {}),
+    ...(opts.retryDelay !== undefined ? { retryDelay: opts.retryDelay } : {}),
+    ...(opts.sleepFn ? { sleepFn: opts.sleepFn } : {}),
+    ...(opts.forceRemoveBackoffMs !== undefined
+      ? { forceRemoveBackoffMs: opts.forceRemoveBackoffMs }
+      : {}),
   });
   if (!removeResult.removed) {
     return {

package/.agents/scripts/lib/worktree/node-modules-strategy.js

@@ -119,6 +119,80 @@ export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
   return { cmd: 'npm', args: ['ci'] };
 }
 
+/**
+ * Per-package-manager "install completed" marker files written into
+ * `node_modules/` by the install command itself. Their presence (and
+ * freshness relative to the lockfile) is the cheapest reliable signal that a
+ * prior install ran to completion — a failed/interrupted install leaves
+ * `node_modules` partially populated without (or with a stale) marker.
+ */
+const INSTALL_MARKERS = [
+  '.package-lock.json', // npm ci / npm install
+  '.modules.yaml', // pnpm
+  '.yarn-state.yml', // yarn berry (node-modules linker)
+  '.yarn-integrity', // yarn classic
+];
+
+const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'];
+
+function safeMtimeMs(fsLike, p) {
+  try {
+    return fsLike.statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure: probe whether a **reused** worktree already carries a completed,
+ * up-to-date install. Worktree reuse must not blindly report
+ * `skipped/worktree-reused` — when the prior run's install *failed*, that
+ * status defeats the install retry exactly when it matters
+ * (`deriveInstallAction('skipped')` treats it as "nothing to do").
+ *
+ * Returns the same shape as `installDependencies`:
+ *   - `{ status: 'skipped', reason: 'worktree-reused' }` — a completed
+ *     install was detected (or the strategy never installs per-tree);
+ *     safe to skip.
+ *   - `{ status: 'failed', reason }` — missing/incomplete/stale install
+ *     detected; callers should retry the install.
+ *
+ * @param {string} strategy One of `per-worktree | pnpm-store | symlink`.
+ * @param {string} wtPath Absolute worktree path.
+ * @param {{ existsSync: Function, statSync: Function }} [fsLike] Injectable for tests.
+ * @returns {{ status: 'skipped' | 'failed', reason: string }}
+ */
+export function probeReusedInstall(strategy, wtPath, fsLike = fs) {
+  // `symlink` re-points node_modules at a donor — no per-tree install to probe.
+  if (strategy === 'symlink') {
+    return { status: 'skipped', reason: 'worktree-reused' };
+  }
+  if (!fsLike.existsSync(path.join(wtPath, 'package.json'))) {
+    return { status: 'skipped', reason: 'no-package-json' };
+  }
+  const nmPath = path.join(wtPath, 'node_modules');
+  if (!fsLike.existsSync(nmPath)) {
+    return { status: 'failed', reason: 'reuse-node-modules-missing' };
+  }
+  const marker = INSTALL_MARKERS.map((m) => path.join(nmPath, m)).find((p) =>
+    fsLike.existsSync(p),
+  );
+  if (!marker) {
+    return { status: 'failed', reason: 'reuse-install-incomplete' };
+  }
+  const markerMtime = safeMtimeMs(fsLike, marker);
+  const lockfile = LOCKFILES.map((l) => path.join(wtPath, l)).find((p) =>
+    fsLike.existsSync(p),
+  );
+  if (lockfile && markerMtime !== null) {
+    const lockMtime = safeMtimeMs(fsLike, lockfile);
+    if (lockMtime !== null && lockMtime > markerMtime) {
+      return { status: 'failed', reason: 'reuse-node-modules-stale' };
+    }
+  }
+  return { status: 'skipped', reason: 'worktree-reused' };
+}
+
 /** Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min. */
 export function installRetryPolicy(cmd) {
   const isPnpm = cmd === 'pnpm';

package/.agents/scripts/lifecycle-emit-story-dispatch.js

@@ -5,7 +5,7 @@
  *
  * Thin host-loop CLI that appends a single `story.dispatch.start`
  * NDJSON record to `temp/epic-<id>/lifecycle.ndjson`. Invoked by
- * `/epic-deliver` Phase 2 immediately BEFORE each per-Story Agent
+ * `/deliver` Phase 2 immediately BEFORE each per-Story Agent
  * tool call so the lifecycle ledger durably records every dispatch
  * attempt. The `wave-tick.js` reconciler (Story #2891 Task #2901)
  * then derives `nextAction['in-flight']` from this ledger to surface

package/.agents/scripts/lifecycle-emit.js

@@ -6,7 +6,7 @@
  *
  * Replaces the three single-purpose emit shims
  * (`epic-deliver-finalize.js`, `epic-deliver-automerge.js`,
- * `epic-deliver-cleanup.js`) that the `/epic-deliver` workflow markdown
+ * `epic-deliver-cleanup.js`) that the `/deliver` workflow markdown
  * invoked in Phase 6, 7.5, and 8. Those shims each did exactly one
  * thing: construct a bus and emit one event. Collapsing them into a
  * single argv-driven CLI lets the workflow stay declarative ("fire

package/.agents/scripts/providers/github/board-add.js

@@ -3,7 +3,7 @@
  *
  * Story #3822 — single source of truth for the post-create board-add
  * step. Issues created through any create path (`createTicket`,
- * `createIssue` — which backs `/story-plan` persist and the `/epic-plan`
+ * `createIssue` — which backs `/plan` persist and the `/plan`
  * Phase 4 Epic open) must land on the configured Projects V2 board
  * without relying on GitHub's "Auto-add to project" built-in workflow,
  * which is off by default on fresh boards and cannot be enabled via API.

package/.agents/scripts/providers/github/errors.js

@@ -109,7 +109,7 @@ export function classifyGithubError(err) {
 // callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
 // jittered exponential backoff on transient GitHub errors instead of
 // bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
-// (e.g. the /epic-deliver Phase E retro).
+// (e.g. the /deliver Phase E retro).
 
 export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
   maxAttempts: 6,

package/.agents/scripts/providers/github/mappers.js

@@ -57,7 +57,7 @@ export function issueToEpic(issue) {
 export function subIssueNodeToTicket(node) {
   // Story #3097 (Wave-0 additive, Epic #3078 Strategy B) — return `null`
   // for absent sub-issue nodes instead of dereferencing properties on
-  // `null`/`undefined`. In 3-tier mode a Story can legitimately have zero
+  // `null`/`undefined`. In 2-tier mode a Story can legitimately have zero
   // Task children, which surfaces as an empty / missing sub-issue node
   // when callers iterate the GraphQL response and pass each entry through
   // this mapper. The legacy 4-tier path also benefits — a transient
@@ -83,7 +83,7 @@ export function subIssueNodeToTicket(node) {
  * any null/undefined entries. Story #3097 (Wave-0 additive, Epic #3078
  * Strategy B) — gives callers a single Storyless-tolerant entry point so
  * the existing per-node mappers can stay strict for the 4-tier path while
- * the 3-tier path (Storyless: a Story with zero child Tasks) gets a
+ * the 2-tier path (Storyless: a Story with zero child Tasks) gets a
  * well-defined empty-array result.
  *
  * @param {Array<object|null|undefined>|null|undefined} nodes

package/.agents/scripts/providers/github/tickets.js

@@ -22,6 +22,7 @@
  */
 
 import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
+import { Logger } from '../../lib/Logger.js';
 import { addIssueToBoard } from './board-add.js';
 import { createInlineTicketCache } from './cache.js';
 import { withTransientRetry } from './errors.js';
@@ -33,8 +34,16 @@ import {
 } from './request-helpers.js';
 
 /**
- * Compose the final markdown body for a created ticket. Under the 3-tier
- * hierarchy (Epic → Feature → Story), `body` is always a string supplied
+ * GitHub Search API hard ceiling is 1000 results per query; at
+ * `per_page=100` that is 10 pages. An Epic never has anywhere near 1000
+ * children, so hitting this cap means the query is degenerate — we stop
+ * rather than throw (the regex post-filter keeps results correct).
+ */
+const SEARCH_PAGE_CAP = 10;
+
+/**
+ * Compose the final markdown body for a created ticket. Under the 2-tier
+ * hierarchy (Epic → Story), `body` is always a string supplied
  * by the caller (the decomposer, the spec planner, or the reconciler-apply
  * engine). This helper appends the canonical orchestrator footer
  * (`parent: #<n>` / `Epic: #<m>` / `blocked by #<x>`) byte-stable with the
@@ -100,6 +109,14 @@ export class TicketGateway {
     this.repo = repo;
     this._hooks = hooks;
     this._cache = cache ?? createInlineTicketCache();
+    /**
+     * Per-instance memo of `getTickets(epicId, filters)` results (Story
+     * #3988). The planning-state-manager fetches the same child list twice
+     * per planning pass; without this memo each fetch re-pays the full
+     * search/list round-trip. Invalidated on every write surface.
+     * @type {Map<string, object[]>}
+     */
+    this._listCache = new Map();
   }
 
   /**
@@ -142,29 +159,113 @@ export class TicketGateway {
   }
 
   /**
-   * @field-manifest /repos/{owner}/{repo}/issues?state=...&labels=...:
-   *                 number, body, labels, state, pull_request
+   * Run one Search API query (`/search/issues`) to completion, returning
+   * the raw issue items. Search responses are `{ total_count, items }`
+   * envelopes rather than bare arrays, so this paginates manually instead
+   * of going through `paginateRest`.
+   */
+  async _searchIssues(query) {
+    const items = [];
+    for (let page = 1; page <= SEARCH_PAGE_CAP; page++) {
+      const params = new URLSearchParams({
+        q: query,
+        per_page: '100',
+        page: String(page),
+      });
+      const result = await withTransientRetry(
+        () =>
+          this._gh.api({
+            method: 'GET',
+            endpoint: `/search/issues?${params}`,
+          }),
+        { label: `searchIssues page ${page}`, onRetry: defaultRetryWarn },
+      );
+      const parsed = parseApiJson(result);
+      const batch = Array.isArray(parsed?.items) ? parsed.items : [];
+      items.push(...batch);
+      if (batch.length < 100) break;
+    }
+    return items;
+  }
+
+  /**
+   * Server-side narrowed child lookup (Story #3988): two Search API
+   * queries — `"Epic: #N" in:body` and `"parent: #N" in:body` — deduped
+   * by issue number. Replaces the repo-wide `state=all` pagination that
+   * cost ~1 spawn per 100 repo issues and hard-failed past the
+   * `paginateRest` page cap. Search tokenization can over-match (e.g.
+   * `#10` vs `#100`), so callers MUST keep the word-boundary regex
+   * post-filter.
+   */
+  async _searchEpicChildren(epicId, filters) {
+    const qualifiers = [`repo:${this.owner}/${this.repo}`, 'is:issue'];
+    const state = filters.state ?? 'all';
+    if (state === 'open' || state === 'closed') {
+      qualifiers.push(`state:${state}`);
+    }
+    if (filters.label) qualifiers.push(`label:"${filters.label}"`);
+    const base = qualifiers.join(' ');
+
+    const [epicRefs, parentRefs] = await Promise.all([
+      this._searchIssues(`${base} "Epic: #${epicId}" in:body`),
+      this._searchIssues(`${base} "parent: #${epicId}" in:body`),
+    ]);
+
+    const byNumber = new Map();
+    for (const issue of [...epicRefs, ...parentRefs]) {
+      if (!byNumber.has(issue.number)) byNumber.set(issue.number, issue);
+    }
+    return Array.from(byNumber.values());
+  }
+
+  /**
+   * Repo-wide listing fallback — the pre-#3988 shape. Only used when the
+   * Search API path fails (search outage, search-specific rate limit).
    */
   /* node:coverage ignore next */
-  async getTickets(epicId, filters = {}) {
+  async _listAllIssues(filters) {
     const params = new URLSearchParams({ state: filters.state ?? 'all' });
     if (filters.label) params.set('labels', filters.label);
-
     const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
-    const issues = await paginateRest(this._gh, endpoint);
+    return paginateRest(this._gh, endpoint);
+  }
+
+  /**
+   * @field-manifest /search/issues?q=...: number, id, node_id, title,
+   *                 body, labels, state, pull_request
+   * @field-manifest /repos/{owner}/{repo}/issues?state=...&labels=...:
+   *                 number, body, labels, state, pull_request
+   */
+  async getTickets(epicId, filters = {}) {
+    const memoKey = `${epicId}|${filters.state ?? 'all'}|${filters.label ?? ''}`;
+    if (this._listCache.has(memoKey)) return this._listCache.get(memoKey);
+
+    let issues;
+    try {
+      issues = await this._searchEpicChildren(epicId, filters);
+    } catch (err) {
+      const msg = typeof err?.message === 'string' ? err.message : String(err);
+      Logger.warn(
+        `[TicketGateway] search-based getTickets(#${epicId}) failed (${msg}); ` +
+          'falling back to repo-wide issue listing',
+      );
+      issues = await this._listAllIssues(filters);
+    }
 
     // Word-boundary regex prevents #1 matching #10, #100, etc.
     const epicRefRe = new RegExp(
       `(?:Epic:\\s*#${epicId}|parent:\\s*#${epicId})(?:\\s|$|[,.)\\]])`,
     );
 
-    return issues
+    const tickets = issues
       .filter((issue) => {
         if (issue.pull_request) return false;
         const body = issue.body ?? '';
         return epicRefRe.test(body);
       })
       .map(issueToListItem);
+    this._listCache.set(memoKey, tickets);
+    return tickets;
   }
 
   /* node:coverage ignore next */
@@ -187,6 +288,7 @@ export class TicketGateway {
 
   invalidateTicket(ticketId) {
     this._cache.invalidate(ticketId);
+    this._listCache.clear();
   }
 
   // ---------------------------------------------------------------------------
@@ -226,6 +328,7 @@ export class TicketGateway {
       },
     });
     const issue = parseApiJson(result);
+    this._listCache.clear();
 
     let subIssueLinked = false;
     let subIssueError = null;
@@ -258,8 +361,8 @@ export class TicketGateway {
   /**
    * Create a **bare** issue — no `parent: #N` footer composition and no
    * sub-issue link. Serves the standalone create paths that bypass
-   * `createTicket`'s Story-shaped body rendering: the `/story-plan`
-   * persist step and the `/epic-plan` Phase 4 Epic open
+   * `createTicket`'s Story-shaped body rendering: the `/plan`
+   * persist step and the `/plan` Phase 4 Epic open
    * (`openEpicFromOnePager`'s `createIssue` port).
    *
    * After the POST, the new issue is added to the configured Project V2
@@ -288,6 +391,7 @@ export class TicketGateway {
       body: { title, body, labels },
     });
     const issue = parseApiJson(result);
+    this._listCache.clear();
 
     const boardAdd = await addIssueToBoard({
       nodeId: issue.node_id,

package/.agents/scripts/resync-status-column.js

@@ -5,7 +5,7 @@
  * resync-status-column.js — re-assert the GitHub Projects v2 Status
  * column for a ticket after auto-merge has fired (Story #2845).
  *
- * The `/single-story-deliver` and `/story-deliver` workflow docs call
+ * The `/single-story-deliver` and `/deliver` workflow docs call
  * this CLI after Step 5 confirms `state: "MERGED"` so the orchestrator
  * wins the race against the GitHub built-in `Pull request merged`
  * workflow, which would otherwise overwrite Status to whatever value

package/.agents/scripts/retro-run.js

@@ -2,9 +2,9 @@
 /* node:coverage ignore file */
 
 /**
- * retro-run.js — execute the `/epic-deliver` Phase 6 retro from a CLI.
+ * retro-run.js — execute the `/deliver` Phase 6 retro from a CLI.
  *
- * Phase 6 of `/epic-deliver` posts the Epic retro by invoking the
+ * Phase 6 of `/deliver` posts the Epic retro by invoking the
  * in-process retro module (`lib/orchestration/retro-runner.js`'s
  * `runRetro`). That module is a library entry point — it has no CLI
  * wrapper and hard-requires both a GitHub `provider` and a lifecycle

package/.agents/scripts/run-lint.js

@@ -64,11 +64,20 @@ const tasks = [
     // only the canonical `<axis>::<value>` separator from
     // `lib/label-constants.js` appears. Closes the drift gap that
     // let the original `type/epic` typo land at
-    // `.agents/workflows/epic-plan.md:49`.
+    // `.agents/workflows/helpers/plan-epic.md:49`.
     name: 'label-vocabulary',
     cmd: 'node',
     args: ['.agents/scripts/lint-label-vocabulary.js'],
   },
+  {
+    // Architecture cycle ratchet (Story #3991). Detects directed import
+    // cycles under `.agents/scripts/` and fails on any cycle not in the
+    // committed allowlist (`baselines/arch-cycles.json`). Mirrors the
+    // ratchet-down semantics of `check-dead-exports.js`.
+    name: 'arch-cycles',
+    cmd: 'node',
+    args: ['.agents/scripts/check-arch-cycles.js'],
+  },
 ];
 
 function runTask({ name, cmd, args }) {

package/.agents/scripts/run-tests.js

@@ -84,11 +84,31 @@ export const TEST_RUNNER_FLAGS = Object.freeze([
  * quoting). Budgeting the targets to 8 000 chars keeps every spawn's full
  * command line at roughly a quarter of the ceiling — ample headroom for the
  * exe path and any pass-through `--test-name-pattern` args — while keeping
- * the chunk count (and thus the extra `node` start-ups) low. POSIX limits are
- * far higher, so this only ever splits work that would otherwise fail on
- * Windows.
+ * the chunk count (and thus the extra `node` start-ups) low.
+ *
+ * `MAX_TARGET_CHARS` is the **Windows** budget. On POSIX hosts `ARG_MAX` is
+ * far higher (~256 KB on macOS, ~1 MB on Linux), so applying the Windows
+ * budget there needlessly serializes the quick tier into several sequential
+ * `node --test` spawns — each chunk pays a fresh runner start-up, and cores
+ * idle at every chunk's tail. `POSIX_MAX_TARGET_CHARS` (100 000) lets the
+ * whole quick-tier target list (~33 000 chars today) collapse into a single
+ * spawn on POSIX while staying far below `ARG_MAX`.
+ * `resolveMaxTargetChars` picks the budget per platform; the Windows
+ * semantics of `MAX_TARGET_CHARS` are unchanged.
  */
 export const MAX_TARGET_CHARS = 8000;
+export const POSIX_MAX_TARGET_CHARS = 100_000;
+
+/**
+ * Resolve the per-spawn target-character budget for the host platform.
+ * The `platform` parameter is injected in tests.
+ *
+ * @param {NodeJS.Platform} [platform]
+ * @returns {number}
+ */
+export function resolveMaxTargetChars(platform = process.platform) {
+  return platform === 'win32' ? MAX_TARGET_CHARS : POSIX_MAX_TARGET_CHARS;
+}
 
 /**
  * Partition an ordered list of test-file targets into chunks whose joined
@@ -144,7 +164,7 @@ export function runTestSuite({
   spawn = spawnSync,
   cleanup = cleanupRepoTestTempArtifacts,
   listTargets = listTestFilesForTier,
-  maxTargetChars = MAX_TARGET_CHARS,
+  maxTargetChars = resolveMaxTargetChars(),
 } = {}) {
   const { tier, rest } = parseTierArgv(argv);
   const targets = listTargets(tier, cwd);