@cspeach/cli 0.9.0 → 1.1.0

package/dist/projects/plan-schema.js

@@ -28,11 +28,17 @@ export const PLAN_LAYERS = [
  */
 export const PLAN_DELEGATE_SKILLS = [
     'abap-design', 'abap-data-model', 'abap-rap', 'abap-eml',
-    'abap-generate', 'abap-segw', 'abap-test',
+    'abap-generate', 'abap-segw', 'abap-test', 'abap-fiori-build',
+    'abap-extend-model',
 ];
-/** Keep in sync with ItemStatusByType['plan'] in types.ts. */
+/**
+ * Keep in sync with ItemStatusByType['plan'] in types.ts.
+ * 'validated-with-waiver' (C1, 2026-06-11): the exit gate was NOT met but the
+ * user explicitly waived it — DAG eligibility treats it like 'validated'
+ * (see isPhaseSatisfied in plan-run.ts).
+ */
 export const PLAN_PHASE_STATUSES = [
-    'todo', 'designing', 'building', 'verifying', 'validated', 'blocked',
+    'todo', 'designing', 'building', 'verifying', 'validated', 'validated-with-waiver', 'blocked',
 ];
 const SHA256_RE = /^[0-9a-f]{64}$/;
 const planPhaseManifestSchema = z.object({
@@ -48,9 +54,78 @@ const planPhaseWorkSchema = z.object({
     transport: z.string().optional(),
     snapshot: z.string().optional(),
     notes: z.string().optional(),
+    // C2 (D24): exact SRVB name for the plan-complete /abap-fiori-build chain.
+    binding: z.string().optional(),
+    // Track 1 ui-phase fields — tolerant on purpose (written mid-resume by the
+    // model; a malformed value must degrade to undefined, never fail the whole
+    // envelope parse). Keep in sync with PlanPhaseWork in types.ts.
+    app: z.object({ dir: z.string().min(1) }).optional().catch(undefined),
+    service: z.object({
+        url: z.string().min(1).optional(),
+        path: z.string().min(1).optional(),
+        version: z.enum(['2.0', '4.0']).optional(),
+    }).optional().catch(undefined),
+    deployedUrl: z.string().min(1).optional().catch(undefined),
 }).passthrough();
+export const PLAN_UI_FLAVORS = ['fiori-elements', 'freestyle'];
+export const PLAN_UI_FLOORPLANS = ['listReport', 'worklist', 'ovp', 'alp'];
+// Strict on purpose: written once at plan-create under save validation —
+// a bad flavor must fail the save, not silently degrade.
+const planPhaseUiSchema = z.object({
+    flavor: z.enum(PLAN_UI_FLAVORS),
+    floorplan: z.enum(PLAN_UI_FLOORPLANS).optional(),
+    appId: z.string().min(1).optional(),
+    appTitle: z.string().min(1).optional(),
+});
+/** Keep in sync with PlanAuditState in types.ts. 'warn' is the non-blocking
+ * tier (confidence-tiered redesign, 2026-07-08) — persisted literally so a
+ * warned phase records its notes and renders distinctly from a clean pass. */
+export const PLAN_AUDIT_STATES = [
+    'pending', 'passed', 'warn', 'failed', 'infra_failed', 'waived', 'not_audited_hand_edited',
+];
+/**
+ * Reasons a chain stop can record on content.lastStop. Keep in sync with
+ * PlanContent['lastStop']['reason'] in types.ts (same single-source pattern
+ * as PLAN_AUDIT_STATES/PlanAuditState — the zod enum below derives from this).
+ */
+export const PLAN_STOP_REASONS = [
+    'write-phase', 'audit-failed', 'audit-infra', 'deviation',
+];
+/**
+ * §10 Q2 (audit-confidence tiered redesign, 2026-07-08): the light category a
+ * human waive records so the audit's false-positive rate is measurable. Keep in
+ * sync with PlanWaiveCategory in types.ts (the zod enum below derives from it).
+ */
+export const PLAN_WAIVE_CATEGORIES = ['false-positive', 'accepted-risk'];
+const planPhaseAuditSchema = z.object({
+    state: z.enum(PLAN_AUDIT_STATES),
+    findings: z.array(z.string()).optional(),
+    waivedReason: z.string().optional(),
+    // §10 Q2 (2026-07-08): light waive category (see PlanPhaseAudit in types.ts).
+    // Must be listed here or z.object strips it on the next parse — losing the
+    // datum the audit FP-rate query depends on. Optional for back-compat: legacy
+    // waivers carry no category and must still parse.
+    waiveCategory: z.enum(PLAN_WAIVE_CATEGORIES).optional(),
+    at: z.string().optional(),
+    // Task 6 (2026-07-03): evidence-session pointer + consecutive-failure
+    // counter (see PlanPhaseAudit in types.ts). Both MUST be in the schema —
+    // z.object strips unknown keys, so an unlisted field would be silently
+    // dropped on the next parse and the counter/evidence pointer lost.
+    sessionId: z.string().optional(),
+    // D-B review item 1 (2026-07-05): attempt-window cutoff for re-audits (see
+    // PlanPhaseAudit in types.ts). Must be in the schema or z.object strips it.
+    attemptStartedAt: z.string().optional(),
+    consecutiveFailures: z.number().int().nonnegative().optional(),
+});
+/** Fail-safe write-ness: a phase that doesn't declare is treated as writing. */
+export function phaseWrites(phase) {
+    return phase.writes !== false;
+}
 const planPhaseSchema = z.object({
     id: z.string().min(1),
+    // C2 (D29): optional short human name for the tracker board; old envelopes
+    // without it still parse and render via the layer/delegate label fallback.
+    title: z.string().min(1).optional(),
     component: z.string().min(1),
     layer: z.enum(PLAN_LAYERS),
     entryCriteria: z.array(z.string()),
@@ -58,8 +133,46 @@ const planPhaseSchema = z.object({
     manifest: planPhaseManifestSchema,
     exitGate: z.string().min(1),
     approval: z.boolean().optional(),
+    writes: z.boolean().optional(),
+    ui: planPhaseUiSchema.optional(),
+    audit: planPhaseAuditSchema.optional(),
     work: planPhaseWorkSchema.optional(),
 });
+/**
+ * Validates the discovered live stack for a revision plan (RevisionTarget in
+ * types.ts). All layer fields are optional/nullable — a partial stack (e.g.
+ * a table view with no MDE) is valid. Only `anchor`, `uiKind`, and `binding`
+ * are required shape — layers is always an object but all its members are opt.
+ */
+const revisionTargetSchema = z
+    .object({
+    anchor: z.string().min(1),
+    uiKind: z.enum(['fiori-elements', 'freestyle', 'none']),
+    binding: z.string().nullable(),
+    // C2 (2026-06-26): freestyle app on-disk location (see types.ts). Additive
+    // and optional; the superRefine below makes it mandatory ONLY for freestyle.
+    app: z.object({ dir: z.string().min(1) }).optional(),
+    layers: z.object({
+        table: z.string().nullable().optional(),
+        interfaceView: z.string().nullable().optional(),
+        projectionView: z.string().nullable().optional(),
+        bdef: z.string().nullable().optional(),
+        behaviorPool: z.string().nullable().optional(),
+        mde: z.string().nullable().optional(),
+        serviceDef: z.string().nullable().optional(),
+    }),
+})
+    .superRefine((rev, ctx) => {
+    // A freestyle revision must record where the app lives on disk, or the
+    // ui-phase delegation to /abap-fiori-build amend has no appDir to amend.
+    if (rev.uiKind === 'freestyle' && !rev.app) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['app'],
+            message: 'uiKind "freestyle" requires `revision.app.dir` (the freestyle app location for amend)',
+        });
+    }
+});
 // Input type is `unknown` (third param): the `.default({})` on `from` means
 // the schema ACCEPTS input without the key while still OUTPUTTING PlanContent.
 export const planContentSchema = z
@@ -68,6 +181,8 @@ export const planContentSchema = z
         goal: z.string().min(1),
         source: z.string(),
         target: z.string(),
+        // Absent mode parses as undefined (treated as 'create') — back-compat.
+        mode: z.enum(['create', 'revision']).optional(),
     }),
     // Tolerant by lesson (2026-06-06 live smoke): the model omitted the whole
     // `from` key for a goal-only plan and the strict schema killed the save.
@@ -82,6 +197,9 @@ export const planContentSchema = z
             .optional(),
     })
         .default({}),
+    // Present when project.mode='revision'. Optional here; the superRefine
+    // below enforces the cross-field rule: mode='revision' requires revision.
+    revision: revisionTargetSchema.optional(),
     phases: z.array(planPhaseSchema).min(1),
     summary: z.object({
         total: z.number().int().nonnegative(),
@@ -89,8 +207,23 @@ export const planContentSchema = z
         blocked: z.number().int().nonnegative(),
         next: z.string().nullable(),
     }),
+    lastStop: z.object({
+        phaseId: z.string().min(1),
+        reason: z.enum(PLAN_STOP_REASONS),
+        detail: z.string().optional(),
+        at: z.string(),
+    }).optional(),
 })
     .superRefine((content, ctx) => {
+    // mode:'revision' requires a revision target map (the discovered live stack).
+    // Absent mode is treated as 'create' — this check is a no-op in that case.
+    if (content.project.mode === 'revision' && !content.revision) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['revision'],
+            message: 'mode "revision" requires a `revision` target map (discovered live stack)',
+        });
+    }
     // Phase ids must be unique, and entryCriteria may only reference phases
     // EARLIER in the array. Bottom-up ordering by construction — this is what
     // guarantees resume is deterministic and the dependency graph acyclic

package/dist/projects/promote-command.js

@@ -1,5 +1,5 @@
 import { readProjectFile } from './status.js';
-import { buildPromotedFromSnapshot, validatePromotionSource } from './promote.js';
+import { buildPromotedFromSnapshot, buildReviewDecisionsBlock, buildDetailPathHint, validatePromotionSource } from './promote.js';
 import { resolveAtTokenAsync, formatProjectFileList } from './workspace.js';
 /**
  * Per-skill predecessor map. v0.7 admits multi-source via array values —
@@ -92,6 +92,29 @@ export async function runPromoteCommand(args) {
         }
     }
     const promotedFrom = await buildPromotedFromSnapshot(env);
-    const extendedSkillInput = buildExtendedInput(promotedFrom);
+    let extendedSkillInput = buildExtendedInput(promotedFrom);
+    // Always hand the skill the source detail-file path so it reads the baseline
+    // directly (the envelope at .cspeach/ root is unreadable; glob skips .cspeach/).
+    // This is what makes `--from` actually work for upgrade-fix on any scan,
+    // triaged or not — without it the skill globs for the file and fails.
+    const detailHint = buildDetailPathHint(env);
+    if (detailHint) {
+        extendedSkillInput = `${extendedSkillInput}\n\n${detailHint}`;
+    }
+    // When the source is a triaged upgrade-scan envelope, append a dedicated
+    // "Review decisions (honor these)" block joining each finding's status with
+    // its objectName/line/rule. This drives /abap-upgrade-fix off the viewer
+    // triage instead of re-asking object-by-object. Returns null (and we append
+    // nothing) for non-upgrade-scan sources or fully-untriaged scans.
+    const reviewBlock = buildReviewDecisionsBlock(env);
+    if (reviewBlock) {
+        extendedSkillInput = `${extendedSkillInput}\n\n${reviewBlock}`;
+    }
+    // Carry the originating spec document into the handoff so the downstream
+    // skill (e.g. /abap-plan) can cite the running spec the answered gaps trace
+    // back to — the Word/PDF doc → spec-gap → plan thread stays visible.
+    if (env.artefactType === 'spec-gap' && env.content.sourceDocument) {
+        extendedSkillInput = `${extendedSkillInput}\n\nSource spec document: ${env.content.sourceDocument}`;
+    }
     return { promotedFrom, extendedSkillInput };
 }

package/dist/projects/promote.js

@@ -67,6 +67,134 @@ export async function buildPromotedFromSnapshot(source) {
         snapshot: { items },
     };
 }
+/**
+ * Build the compact "Review decisions" block for an upgrade-scan source.
+ *
+ * The viewer lets the user triage each finding to one of
+ * `open | auto-fix | manual | suppress` (stored in `interaction.items[].status`).
+ * Those decisions must DRIVE /abap-upgrade-fix instead of the skill re-asking
+ * object-by-object. The skill cannot file_read the root `.cspeach/<name>.json`
+ * envelope (denylisted), so the statuses must reach it via the `--from`
+ * prompt injection — this block is what the CLI appends to that injection.
+ *
+ * Joins each item's status with the matching `content.findings[]` row
+ * (objectName / line / rule) and renders one aligned line per finding,
+ * e.g.:
+ *   finding-001  ZFI_DUNNING_SELECT  line 52  SELECT_WO_ORDER_BY  → auto-fix
+ *
+ * Returns `null` when the source is not an upgrade-scan, or when every
+ * finding is still `open` (untriaged — nothing to honor; the skill falls
+ * back to its existing interactive ask for all of them).
+ */
+export function buildReviewDecisionsBlock(source) {
+    if (source.artefactType === 'upgrade-scan')
+        return buildUpgradeScanDecisions(source);
+    if (source.artefactType === 'cca-assessment')
+        return buildCcaDecisions(source);
+    return null;
+}
+/**
+ * Always-inject hint for any `--from` source that carries a `content.detailPath`
+ * (upgrade-scan/progress/report, cca-assessment, modernize-result, test-coverage).
+ *
+ * Why this is REQUIRED, not optional: the `.cspeach.json` envelope itself lives at
+ * the denylisted `.cspeach/` root and cannot be read by the skill, and `glob` skips
+ * `.cspeach/` — so without an explicit path the skill hunts for the baseline and
+ * fails (observed live 2026-06-16: `/abap-upgrade-fix --from` globbing endlessly).
+ * The detail file lives under `.cspeach/<domain>/`, which the filesystem carve-out
+ * makes readable — so we hand the skill that exact path to `file_read` directly.
+ */
+export function buildDetailPathHint(source) {
+    const detailPath = source.content?.detailPath;
+    if (!detailPath)
+        return null;
+    return [
+        'Source detail file — READ THIS DIRECTLY with file_read at the exact path below.',
+        'Do NOT glob for it, and do NOT try to read the .cspeach.json envelope (that path',
+        'is protected). The detail file holds the full per-finding data (object, line,',
+        'rule, message, successor) and is readable under .cspeach/:',
+        `  ${detailPath}`,
+    ].join('\n');
+}
+/**
+ * Render a fixed-width "Review decisions (honor these)" table from already-built
+ * rows. `summary` is the one-line counts header; `countKeys` lists the decision
+ * tokens to tally (in display order). Shared by the upgrade-scan and
+ * cca-assessment branches so both render identically.
+ */
+function renderDecisionRows(rows, countKeys, summaryLabel) {
+    const wId = Math.max(...rows.map((r) => r.id.length));
+    const wObj = Math.max(...rows.map((r) => r.objectName.length));
+    const wLine = Math.max(...rows.map((r) => r.line.length));
+    const wRule = Math.max(...rows.map((r) => r.rule.length));
+    const counts = {};
+    for (const k of countKeys)
+        counts[k] = 0;
+    for (const r of rows)
+        counts[r.status] = (counts[r.status] ?? 0) + 1;
+    const summary = countKeys.map((k) => `${counts[k]} ${k}`).join(', ');
+    const lines = [
+        'Review decisions from the source envelope (honor these):',
+        `  ${summaryLabel}: ${summary}.`,
+        '',
+    ];
+    for (const r of rows) {
+        const parts = [
+            r.id.padEnd(wId),
+            r.objectName.padEnd(wObj),
+            r.line.padEnd(wLine),
+            r.rule.padEnd(wRule),
+            `→ ${r.status}`,
+        ];
+        // Collapse the run of spaces from an empty (line-less) column so we never
+        // emit a stray "line undefined"; padEnd of "" already keeps alignment.
+        lines.push(`  ${parts.join('  ').replace(/\s+$/, '')}`);
+    }
+    return lines.join('\n');
+}
+function buildUpgradeScanDecisions(source) {
+    const items = source.interaction.items;
+    if (items.length === 0)
+        return null;
+    // Untriaged source (all open) → omit the block; nothing was decided.
+    if (items.every((it) => it.status === 'open'))
+        return null;
+    const findingById = new Map(source.content.findings.map((f) => [f.id, f]));
+    const rows = items.map((it) => {
+        const f = findingById.get(it.id);
+        return {
+            id: it.id,
+            objectName: f?.objectName ?? '<unknown>',
+            line: f?.line !== undefined ? `line ${f.line}` : '',
+            rule: f?.rule ?? '',
+            status: it.status,
+        };
+    });
+    return renderDecisionRows(rows, ['auto-fix', 'suppress', 'manual', 'open'], 'Applying your review')
+        // The upgrade-scan summary historically reads "... K still open"; keep that
+        // wording for the open bucket while the shared renderer emits "K open".
+        .replace(/(\d+) open\./, '$1 still open.');
+}
+/**
+ * cca-assessment: the per-object review decision is the `classification`
+ * (keep/fix/retire/redesign) the consultant assigned in the worksheet, carried
+ * in content.classifications[]. interaction.items[].status is the triage
+ * lifecycle (open/reviewed/classified/archived), not the fix decision — so we
+ * surface the classification as the decision token the skill must honor.
+ */
+function buildCcaDecisions(source) {
+    const classifications = source.content.classifications;
+    if (!classifications || classifications.length === 0)
+        return null;
+    const rows = classifications.map((c) => ({
+        id: c.id,
+        objectName: c.objectName,
+        line: '',
+        rule: c.objectType ?? '',
+        status: c.classification,
+    }));
+    return renderDecisionRows(rows, ['fix', 'redesign', 'retire', 'keep'], 'Applying your assessment');
+}
 export function validatePromotionSource(source, expectedPredecessor) {
     // v0.7 — accept either a single predecessor or an array (multi-source).
     // /abap-upgrade-fix accepts both upgrade-scan AND cca-assessment, etc.

package/dist/projects/run-lease.js

@@ -0,0 +1,157 @@
+// cspeach-cli/src/projects/run-lease.ts
+//
+// Task 9 (agentic-flow, 2026-07-03) — run lease: concurrent-resume guard for
+// plan envelopes.
+//
+// Problem: two sessions resuming the same plan fork sibling envelope
+// versions silently — saveProject appends collision suffixes and the
+// newest-version redirect tie-breaks on mtime, so neither session notices
+// the other. Guarded mode's long unattended chains make a double-resume
+// likelier. A lightweight lease file makes the second session STOP and say
+// who is already running.
+//
+// Design choices (pinned by __tests__/run-lease.test.ts):
+//
+// - FAMILY-KEYED: the lock path strips the `-vN[-M]` version suffix (same
+//   convention as handoverPathFor in handover-md.ts), so the v3→v4 rotation
+//   every phase save performs does NOT drop the lease —
+//   `hr-plan-ab12-v3.cspeach.json` and `...-v4.cspeach.json` share
+//   `hr-plan-ab12.cspeach.lock`. The FAMILY is the thing being resumed;
+//   individual version files are just its snapshots.
+//
+// - SAME-SESSION IDEMPOTENT: re-acquiring with the sessionId already on the
+//   lease succeeds (and refreshes it). The plan chain re-enters
+//   preparePlanResume on EVERY phase via queueDispatch — without this the
+//   guarded chain would deadlock on its own lease.
+//
+// - STALENESS BY PID LIVENESS: a lease whose holder pid is not alive
+//   (process.kill(pid, 0) throws — works for liveness probing on Windows
+//   Node too) is silently replaced. A crashed or killed session therefore
+//   never needs manual cleanup.
+//
+// - BEST-EFFORT, NOT A SECURITY BOUNDARY: any fs failure while checking or
+//   writing the lease logs one line and reports `acquired: true` —
+//   availability over strictness; a resume must never be blocked by a
+//   broken lock file or a read-only workspace. This is a courtesy guard
+//   against accidental double-resume, nothing more.
+import fs from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+/**
+ * The lease file for an envelope path — keyed on the plan FAMILY base
+ * (version suffix `-vN` and any `-vN-M` collision sub-suffix stripped, same
+ * convention as handoverPathFor), so every version of one plan family maps
+ * to ONE lock file. Non-envelope paths fall back to `<path>.lock`.
+ */
+export function leasePathFor(envelopePath) {
+    const name = basename(envelopePath);
+    if (!name.endsWith('.cspeach.json'))
+        return `${envelopePath}.lock`;
+    const base = name.replace(/(?:-v\d+(?:-\d+)?)?\.cspeach\.json$/, '');
+    return join(dirname(envelopePath), `${base}.cspeach.lock`);
+}
+/**
+ * Liveness probe: signal 0 never delivers, only checks existence. On
+ * Windows Node this maps to an OpenProcess check — valid for liveness.
+ * EPERM means "alive but not ours to signal" — that IS alive.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/**
+ * Try to take the run lease for a plan envelope's family.
+ *
+ * - no lease / stale lease (dead pid) / corrupt lock → acquired, silently
+ * - lease held by the SAME sessionId → acquired (idempotent re-entry;
+ *   the file is refreshed with the current pid + timestamp)
+ * - lease held by a LIVE other session → `{ acquired: false, holder }`
+ * - `force: true` → acquired unconditionally (caller obtained user consent)
+ * - ANY fs error → `{ acquired: true }` after one log line (best-effort)
+ *
+ * The write is atomic (tmp + rename, same style as session/store.ts) so a
+ * concurrent reader never sees a half-written lock.
+ */
+export function acquireRunLease(envelopePath, sessionId, opts) {
+    const lockPath = leasePathFor(envelopePath);
+    try {
+        if (!opts?.force) {
+            let existing = null;
+            try {
+                const raw = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+                if (typeof raw.pid === 'number' && typeof raw.sessionId === 'string') {
+                    existing = { pid: raw.pid, sessionId: raw.sessionId, at: typeof raw.at === 'string' ? raw.at : '' };
+                }
+                // Malformed shape → existing stays null: garbage never holds a lease.
+            }
+            catch {
+                existing = null; // missing or unparseable — treat as absent
+            }
+            if (existing && existing.sessionId !== sessionId && isPidAlive(existing.pid)) {
+                return { acquired: false, holder: existing };
+            }
+        }
+        const holder = { pid: process.pid, sessionId, at: new Date().toISOString() };
+        const tmp = `${lockPath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(holder, null, 2), 'utf8');
+        try {
+            fs.renameSync(tmp, lockPath);
+        }
+        catch (e) {
+            // Don't orphan the tmp file — best-effort cleanup, then let the outer
+            // catch handle the failure as usual (proceed-as-acquired).
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* best-effort */ }
+            throw e;
+        }
+        return { acquired: true, holder };
+    }
+    catch (e) {
+        // Best-effort by design: a broken lock dir must never block a resume.
+        opts?.log?.(`[plan] run-lease check skipped (${e instanceof Error ? e.message : String(e)}) — proceeding without the concurrency guard.`);
+        return { acquired: true };
+    }
+}
+/**
+ * Release the run lease for a plan envelope's family. Ownership-checked:
+ * a lock held by a DIFFERENT live pid (e.g. another session overrode us
+ * mid-run with user consent) is left untouched — we only ever delete our
+ * own, or a dead holder's, lock. Best-effort: all failures are swallowed
+ * (a leaked lease goes stale with the process anyway).
+ */
+export function releaseRunLease(envelopePath) {
+    const lockPath = leasePathFor(envelopePath);
+    try {
+        const raw = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        if (typeof raw.pid === 'number' && raw.pid !== process.pid && isPidAlive(raw.pid)) {
+            return; // live foreign holder — never delete someone else's lease
+        }
+        fs.unlinkSync(lockPath);
+    }
+    catch {
+        // missing / unreadable / undeletable — nothing useful to do
+    }
+}
+/**
+ * Chain-aware release for the REPL's plan-resume legs: when a follow-up
+ * dispatch is QUEUED (`queuedDispatch` non-empty — the pendingDispatch slot
+ * still holds the harness-built next `--resume` command), the lease is HELD
+ * across the gap. Releasing between auto-chained phases would let a second
+ * session grab the family lock mid-chain (headless: the chain silently
+ * stops on re-entry; interactive: the user is prompted mid-auto-chain, and
+ * a takeover forks the plan — the exact failure the lease exists to
+ * prevent). The re-entry's same-session re-acquire is idempotent, so
+ * holding through the gap is free. Only when the chain truly ends (nothing
+ * queued) is the lease released.
+ */
+export function releaseRunLeaseUnlessChained(envelopePath, queuedDispatch) {
+    if (queuedDispatch)
+        return; // chain continues — hold the lease across the dispatch
+    releaseRunLease(envelopePath);
+}