@lumenflow/cli 5.2.3 → 5.2.5

package/dist/approval-request.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 // Copyright (c) 2026 Hellmai Ltd
 // SPDX-License-Identifier: AGPL-3.0-only
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
+import { CONTEXT_VALIDATION, resolveLocation } from '@lumenflow/core';
 import { createHttpControlPlaneSyncPort, parseWorkspaceControlPlaneConfig, } from '@lumenflow/control-plane-sdk';
 import { CONFIG_FILES } from '@lumenflow/core/wu-constants';
 import { parseYAML } from '@lumenflow/core/wu-yaml';
@@ -12,6 +13,20 @@ const LOG_PREFIX = '[approval:request]';
 const WORKSPACE_PATH = CONFIG_FILES.WORKSPACE_CONFIG;
 const DEFAULT_REQUESTER_TYPE = 'agent';
 const REQUESTER_TYPE_VALUES = new Set(['agent', 'user']);
+const HUMAN_ESCALATION_RESERVED_CONTEXT_KEYS = new Set([
+    'triggers',
+    'summary',
+    'resolver_command',
+    'skip_gates_reason',
+    'fix_wu',
+]);
+/**
+ * WU-2874: Approval type constant for worker-agent human-escalation handoff.
+ * Workers emit this instead of prose-dumping wu:escalate/wu:done commands.
+ */
+export const HUMAN_ESCALATION_APPROVAL_TYPE = 'human-escalation';
+/** WU-2874: Local sidecar directory for structured escalation context. */
+export const ESCALATION_SIDECAR_DIR = join('.lumenflow', 'state', 'approvals');
 function asRecord(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new Error('Expected a JSON object payload');
@@ -27,18 +42,28 @@ function parseJsonRecord(value, label) {
         throw new Error(`Invalid ${label}: ${reason}`, { cause: error });
     }
 }
+function parseHumanEscalationExtraContext(value) {
+    const parsed = parseJsonRecord(value, '--context');
+    return Object.fromEntries(Object.entries(parsed).filter(([key]) => !HUMAN_ESCALATION_RESERVED_CONTEXT_KEYS.has(key)));
+}
 function parseOptions(argv = process.argv) {
     const program = new Command()
         .name('approval-request')
         .description('Request an approval from the configured control-plane')
         .requiredOption('--type <type>', 'Approval type (for example: wu_assignment)')
-        .requiredOption('--subject <json>', 'JSON object describing the approval subject')
+        .option('--subject <json>', 'JSON object describing the approval subject')
         .option('--context <json>', 'Optional JSON object with additional context')
         .option('--requester-id <id>', 'Requester identifier')
         .option('--requester-type <type>', 'Requester type: agent or user', DEFAULT_REQUESTER_TYPE)
         .option('--expires-at <iso>', 'Optional expiry timestamp (ISO-8601)')
         .option('--workspace-id <id>', 'Override workspace_id from workspace.yaml')
         .option('--json', 'Output JSON response', false)
+        // WU-2874: Structured flags for --type human-escalation
+        .option('--wu <id>', 'WU id (human-escalation: required)')
+        .option('--triggers <csv>', 'Comma-separated escalation_triggers that fired (human-escalation)')
+        .option('--summary <text>', 'Summary of worker changes (human-escalation: required)')
+        .option('--skip-gates-reason <text>', 'If approval should chain --skip-gates, the reason')
+        .option('--fix-wu <id>', 'Paired fix-WU id when skip-gates-reason is set')
         .exitOverride();
     try {
         program.parse(argv);
@@ -65,7 +90,85 @@ function parseOptions(argv = process.argv) {
         expiresAt: parsed.expiresAt?.trim(),
         workspaceId: parsed.workspaceId?.trim(),
         json: parsed.json ?? false,
+        wu: parsed.wu?.trim(),
+        triggers: parsed.triggers,
+        summary: parsed.summary,
+        skipGatesReason: parsed.skipGatesReason,
+        fixWu: parsed.fixWu?.trim(),
+    };
+}
+/**
+ * WU-2874: Validate + assemble structured subject/context from human-escalation flags.
+ * Keeps the original free-form --subject/--context path untouched for other types.
+ */
+export function buildHumanEscalationPayload(options) {
+    if (!options.wu) {
+        throw new Error('--wu is required when --type human-escalation');
+    }
+    if (!options.summary) {
+        throw new Error('--summary is required when --type human-escalation');
+    }
+    const triggers = (options.triggers ?? '')
+        .split(',')
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    const payload = {
+        wu: options.wu,
+        triggers,
+        summary: options.summary,
     };
+    if (options.skipGatesReason)
+        payload.skipGatesReason = options.skipGatesReason;
+    if (options.fixWu)
+        payload.fixWu = options.fixWu;
+    return payload;
+}
+/**
+ * Resolve where a human-escalation sidecar should live. Worker agents request
+ * approvals from their claimed worktree, but reviewers run approval:review from
+ * the main checkout so the sidecar must be written where the reviewer can read
+ * it. Unknown/non-git roots fall back to the caller's root for unit tests and
+ * non-worktree control-plane use.
+ */
+export async function resolveEscalationSidecarRoot(rootDir = process.cwd(), location) {
+    const resolvedLocation = location ?? (await resolveLocation(rootDir));
+    const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+    if (resolvedLocation.type === LOCATION_TYPES.WORKTREE) {
+        return resolvedLocation.mainCheckout;
+    }
+    if (resolvedLocation.type === LOCATION_TYPES.MAIN ||
+        resolvedLocation.type === LOCATION_TYPES.DETACHED) {
+        return resolvedLocation.gitRoot;
+    }
+    return rootDir;
+}
+/**
+ * WU-2874: Write sidecar file so approval:review --approve can chain the
+ * resolver without a list/fetch roundtrip. Idempotent — overwrites on re-run.
+ */
+export function writeEscalationSidecar(approvalId, payload, rootDir = process.cwd()) {
+    const dir = join(rootDir, ESCALATION_SIDECAR_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const path = join(dir, `${approvalId}.json`);
+    writeFileSync(path, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    return path;
+}
+/**
+ * WU-2874: Read sidecar written by writeEscalationSidecar. Returns undefined
+ * when missing (e.g. approval was not a human-escalation type).
+ */
+export function readEscalationSidecar(approvalId, rootDir = process.cwd()) {
+    const path = join(rootDir, ESCALATION_SIDECAR_DIR, `${approvalId}.json`);
+    if (!existsSync(path))
+        return undefined;
+    const raw = readFileSync(path, 'utf8');
+    return JSON.parse(raw);
+}
+/** WU-2874: Return the absolute sidecar path for a given approval id. */
+export function getEscalationSidecarPath(approvalId, rootDir = process.cwd()) {
+    return join(rootDir, ESCALATION_SIDECAR_DIR, `${approvalId}.json`);
 }
 function resolveApprovalContext(workspaceRoot, environment, workspaceIdOverride) {
     const workspaceFilePath = join(workspaceRoot, WORKSPACE_PATH);
@@ -89,9 +192,39 @@ function formatResultLine(result) {
     return `${LOG_PREFIX} Created ${result.approval_id} (${result.status}) for type ${result.type}`;
 }
 export async function runApprovalRequest(options, input = {}) {
-    const subject = parseJsonRecord(options.subject, '--subject');
-    const context = options.context ? parseJsonRecord(options.context, '--context') : undefined;
-    const { workspaceId, syncPort } = resolveApprovalContext(input.workspaceRoot ?? process.cwd(), input.environment ?? process.env, options.workspaceId);
+    const rootDir = input.workspaceRoot ?? process.cwd();
+    // WU-2874: human-escalation synthesises subject+context from structured flags
+    // so the worker does not have to hand-craft JSON. The existing free-form
+    // API (--subject/--context) remains untouched for every other type.
+    let subject;
+    let context;
+    let escalationPayload;
+    if (options.type === HUMAN_ESCALATION_APPROVAL_TYPE) {
+        escalationPayload = buildHumanEscalationPayload(options);
+        subject = { wu: escalationPayload.wu };
+        const structuredContext = {
+            triggers: escalationPayload.triggers,
+            summary: escalationPayload.summary,
+            ...(escalationPayload.skipGatesReason
+                ? { skip_gates_reason: escalationPayload.skipGatesReason }
+                : {}),
+            ...(escalationPayload.fixWu ? { fix_wu: escalationPayload.fixWu } : {}),
+        };
+        context = structuredContext;
+        // Free-form --context lets operators add trace metadata, but structured
+        // escalation fields remain authoritative.
+        if (options.context) {
+            context = { ...parseHumanEscalationExtraContext(options.context), ...structuredContext };
+        }
+    }
+    else {
+        if (!options.subject) {
+            throw new Error('--subject is required (unless --type human-escalation)');
+        }
+        subject = parseJsonRecord(options.subject, '--subject');
+        context = options.context ? parseJsonRecord(options.context, '--context') : undefined;
+    }
+    const { workspaceId, syncPort } = resolveApprovalContext(rootDir, input.environment ?? process.env, options.workspaceId);
     if (!syncPort.requestApproval) {
         throw new Error('Control-plane adapter does not support requestApproval');
     }
@@ -104,16 +237,29 @@ export async function runApprovalRequest(options, input = {}) {
         ...(options.expiresAt ? { expires_at: options.expiresAt } : {}),
         ...(context ? { context } : {}),
     };
-    return syncPort.requestApproval(payload);
+    const record = await syncPort.requestApproval(payload);
+    // WU-2874: write sidecar after the control-plane acknowledges so the
+    // reviewer's approval:review --approve path can chain the resolver locally
+    // without a lookup. Sidecar-write is side-effect only; we never auto-run
+    // wu:escalate/wu:done on the worker's behalf (Acceptance criterion: no
+    // auto-run on creation).
+    if (escalationPayload) {
+        const sidecarRoot = await resolveEscalationSidecarRoot(rootDir);
+        writeEscalationSidecar(record.approval_id, escalationPayload, sidecarRoot);
+    }
+    return record;
 }
 export async function main(argv = process.argv) {
     const options = parseOptions(argv);
-    const result = (await runApprovalRequest(options));
+    const result = await runApprovalRequest(options);
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
     console.log(formatResultLine(result));
+    if (options.type === HUMAN_ESCALATION_APPROVAL_TYPE) {
+        console.log(`${LOG_PREFIX} Reviewer resolves via: pnpm approval:review --approve ${result.approval_id}`);
+    }
 }
 if (import.meta.main) {
     void runCLI(main);

package/dist/approval-request.js.map

@@ -1 +1 @@
-{"version":3,"file":"approval-request.js","sourceRoot":"","sources":["../src/approval-request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approval-request.js","sourceRoot":"","sources":["../src/approval-request.ts"],"names":[],"mappings":"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"}

package/dist/approval-review.js

@@ -1,29 +1,39 @@
 #!/usr/bin/env node
 // Copyright (c) 2026 Hellmai Ltd
 // SPDX-License-Identifier: AGPL-3.0-only
-import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
+import { CONTEXT_VALIDATION, resolveLocation } from '@lumenflow/core';
 import { createHttpControlPlaneSyncPort, parseWorkspaceControlPlaneConfig, } from '@lumenflow/control-plane-sdk';
 import { CONFIG_FILES } from '@lumenflow/core/wu-constants';
+import { getGitForCwd } from '@lumenflow/core/git-adapter';
 import { parseYAML } from '@lumenflow/core/wu-yaml';
 import { runCLI } from './cli-entry-point.js';
+import { HUMAN_ESCALATION_APPROVAL_TYPE, getEscalationSidecarPath, readEscalationSidecar, } from './approval-request.js';
 const LOG_PREFIX = '[approval:review]';
 const WORKSPACE_PATH = CONFIG_FILES.WORKSPACE_CONFIG;
 const DEFAULT_REVIEWER_TYPE = 'user';
 const REVIEWER_TYPE_VALUES = new Set(['agent', 'user']);
 const DECISION_VALUES = new Set(['approved', 'rejected', 'expired']);
+const HUMAN_ESCALATION_LOOKUP_LIMIT = 100;
 function parseOptions(argv = process.argv) {
     const program = new Command()
         .name('approval-review')
         .description('Resolve a pending approval in the configured control-plane')
-        .requiredOption('--id <approvalId>', 'Approval identifier')
-        .requiredOption('--decision <decision>', 'Decision: approved, rejected, or expired')
+        // WU-2874: `--id` accepted as option, positional, or via --approve/--deny <id>
+        .option('--id <approvalId>', 'Approval identifier')
+        .option('--decision <decision>', 'Decision: approved, rejected, or expired')
+        .option('--approve [approvalId]', 'Convenience for --decision approved')
+        .option('--deny [approvalId]', 'Convenience for --decision rejected')
         .option('--reason <reason>', 'Optional decision reason')
         .option('--reviewer-id <id>', 'Reviewer identifier')
         .option('--reviewer-type <type>', 'Reviewer type: agent or user', DEFAULT_REVIEWER_TYPE)
+        .option('--reviewer <email>', 'Reviewer email (used as --resolver for human-escalation chains); defaults to git user.email')
         .option('--workspace-id <id>', 'Override workspace_id from workspace.yaml')
         .option('--json', 'Output JSON response', false)
+        .argument('[approvalId]', 'Approval identifier (positional alternative to --id)')
         .exitOverride();
     try {
         program.parse(argv);
@@ -37,20 +47,42 @@ function parseOptions(argv = process.argv) {
         throw error;
     }
     const parsed = program.opts();
-    const decision = parsed.decision.trim();
+    const positional = program.args[0];
+    // WU-2874: derive approval id from --id | --approve <id> | --deny <id> | positional
+    const approvalIdRaw = parsed.id ??
+        (typeof parsed.approve === 'string' ? parsed.approve : undefined) ??
+        (typeof parsed.deny === 'string' ? parsed.deny : undefined) ??
+        positional;
+    if (!approvalIdRaw) {
+        throw new Error('Missing approval id. Pass --id <approvalId> or --approve <approvalId>.');
+    }
+    // WU-2874: derive decision from --decision or the convenience flags.
+    let decisionRaw = parsed.decision;
+    if (!decisionRaw && parsed.approve !== undefined)
+        decisionRaw = 'approved';
+    if (!decisionRaw && parsed.deny !== undefined)
+        decisionRaw = 'rejected';
+    if (parsed.approve !== undefined && parsed.deny !== undefined) {
+        throw new Error('--approve and --deny are mutually exclusive');
+    }
+    if (!decisionRaw) {
+        throw new Error('Missing decision. Use --approve, --deny, or --decision <value>.');
+    }
+    const decision = decisionRaw.trim();
     if (!DECISION_VALUES.has(decision)) {
-        throw new Error(`Invalid --decision: ${parsed.decision}`);
+        throw new Error(`Invalid --decision: ${decisionRaw}`);
     }
     const reviewerTypeRaw = (parsed.reviewerType ?? DEFAULT_REVIEWER_TYPE).trim();
     if (!REVIEWER_TYPE_VALUES.has(reviewerTypeRaw)) {
         throw new Error(`Invalid --reviewer-type: ${reviewerTypeRaw}`);
     }
     return {
-        approvalId: parsed.id.trim(),
+        approvalId: approvalIdRaw.trim(),
         decision,
         reason: parsed.reason?.trim(),
         reviewerId: parsed.reviewerId?.trim(),
         reviewerType: reviewerTypeRaw,
+        reviewer: parsed.reviewer?.trim(),
         workspaceId: parsed.workspaceId?.trim(),
         json: parsed.json ?? false,
     };
@@ -77,11 +109,192 @@ function formatResultLine(result) {
     const reasonSuffix = result.decision_reason ? ` (${result.decision_reason})` : '';
     return `${LOG_PREFIX} Updated ${result.approval_id} -> ${result.status}${reasonSuffix}`;
 }
+const defaultRunner = (command, args, options) => {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'inherit', 'inherit'],
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout : undefined,
+        stderr: typeof result.stderr === 'string' ? result.stderr : undefined,
+    };
+};
+export async function resolveEscalationReviewRoot(rootDir = process.cwd(), location) {
+    const resolvedLocation = location ?? (await resolveLocation(rootDir));
+    const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+    if (resolvedLocation.type === LOCATION_TYPES.WORKTREE) {
+        return resolvedLocation.mainCheckout;
+    }
+    if (resolvedLocation.type === LOCATION_TYPES.MAIN ||
+        resolvedLocation.type === LOCATION_TYPES.DETACHED) {
+        return resolvedLocation.gitRoot;
+    }
+    return rootDir;
+}
+/**
+ * WU-2874: Chain wu:escalate --resolve + wu:done for an approved human-escalation.
+ *
+ * Pure-ish: accepts a runner so tests can assert call ordering without spawning
+ * real processes. Stops at the first non-zero exit and surfaces the failing step.
+ * The approval record is only marked resolved when every step returns status 0.
+ */
+export function runEscalationChain(input) {
+    const runner = input.runner ?? defaultRunner;
+    const cwd = input.cwd;
+    const steps = [];
+    const escalateArgs = [
+        'wu:escalate',
+        '--resolve',
+        '--id',
+        input.payload.wu,
+        '--resolver',
+        input.reviewerEmail,
+    ];
+    const escalate = runner('pnpm', escalateArgs, { cwd });
+    const escalateStep = {
+        command: 'pnpm',
+        args: escalateArgs,
+        status: escalate.status,
+    };
+    steps.push(escalateStep);
+    if (escalate.status !== 0) {
+        return { steps, success: false, failedStep: escalateStep };
+    }
+    const doneArgs = ['wu:done', '--id', input.payload.wu];
+    if (input.payload.skipGatesReason) {
+        doneArgs.push('--skip-gates', '--reason', input.payload.skipGatesReason);
+        if (input.payload.fixWu) {
+            doneArgs.push('--fix-wu', input.payload.fixWu);
+        }
+    }
+    const done = runner('pnpm', doneArgs, { cwd });
+    const doneStep = {
+        command: 'pnpm',
+        args: doneArgs,
+        status: done.status,
+    };
+    steps.push(doneStep);
+    if (done.status !== 0) {
+        return { steps, success: false, failedStep: doneStep };
+    }
+    return { steps, success: true };
+}
+/**
+ * WU-2874: Resolve the reviewer's email. Explicit --reviewer wins; otherwise
+ * fall back to git user.email so the approver identity is never the approval
+ * creator (per acceptance criteria).
+ */
+async function resolveReviewerEmail(override) {
+    if (override)
+        return override;
+    const email = await getGitForCwd().getConfigValue('user.email');
+    if (!email) {
+        throw new Error('Cannot determine reviewer email. Pass --reviewer <email> or configure git user.email.');
+    }
+    return email;
+}
+function missingHumanEscalationContextMessage(approvalId, detail) {
+    return (`${LOG_PREFIX} Missing human-escalation context for approval ${approvalId}: ${detail}. ` +
+        'Re-run pnpm approval:request --type human-escalation from the claimed worktree, ' +
+        'then retry approval:review.');
+}
+function readRequiredString(value, fieldName, approvalId) {
+    if (typeof value === 'string' && value.trim().length > 0) {
+        return value;
+    }
+    throw new Error(missingHumanEscalationContextMessage(approvalId, `expected ${fieldName}`));
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function readTriggers(value, approvalId) {
+    if (Array.isArray(value) && value.every((trigger) => typeof trigger === 'string')) {
+        return value;
+    }
+    throw new Error(missingHumanEscalationContextMessage(approvalId, 'expected context.triggers to be an array of strings'));
+}
+export function humanEscalationPayloadFromApprovalRecord(record) {
+    if (record.type !== HUMAN_ESCALATION_APPROVAL_TYPE) {
+        return undefined;
+    }
+    if (!record.context) {
+        throw new Error(missingHumanEscalationContextMessage(record.approval_id, 'control-plane record has no context'));
+    }
+    const payload = {
+        wu: readRequiredString(record.subject.wu, 'subject.wu', record.approval_id),
+        triggers: readTriggers(record.context.triggers, record.approval_id),
+        summary: readRequiredString(record.context.summary, 'context.summary', record.approval_id),
+    };
+    const skipGatesReason = readOptionalString(record.context.skip_gates_reason);
+    if (skipGatesReason)
+        payload.skipGatesReason = skipGatesReason;
+    const fixWu = readOptionalString(record.context.fix_wu);
+    if (fixWu)
+        payload.fixWu = fixWu;
+    return payload;
+}
+async function findPendingHumanEscalationPayload(input) {
+    if (!input.syncPort.listApprovals) {
+        return undefined;
+    }
+    const result = await input.syncPort.listApprovals({
+        workspace_id: input.workspaceId,
+        status: 'pending',
+        type: HUMAN_ESCALATION_APPROVAL_TYPE,
+        limit: HUMAN_ESCALATION_LOOKUP_LIMIT,
+    });
+    const matchingRecord = result.approvals.find((approval) => approval.approval_id === input.approvalId);
+    return matchingRecord ? humanEscalationPayloadFromApprovalRecord(matchingRecord) : undefined;
+}
 export async function runApprovalReview(options, input = {}) {
-    const { workspaceId, syncPort } = resolveApprovalContext(input.workspaceRoot ?? process.cwd(), input.environment ?? process.env, options.workspaceId);
+    const rootDir = input.workspaceRoot ?? process.cwd();
+    const reviewRoot = await resolveEscalationReviewRoot(rootDir);
+    const { workspaceId, syncPort } = resolveApprovalContext(rootDir, input.environment ?? process.env, options.workspaceId);
     if (!syncPort.resolveApproval) {
         throw new Error('Control-plane adapter does not support resolveApproval');
     }
+    // WU-2874: Human-escalation approve-chain runs BEFORE marking the approval
+    // resolved. If either wu:escalate or wu:done fails, the approval stays
+    // pending so the reviewer can re-approve after fixes (replayable).
+    const sidecar = options.decision === 'approved'
+        ? readEscalationSidecar(options.approvalId, reviewRoot)
+        : undefined;
+    const escalationPayload = sidecar ??
+        (options.decision === 'approved'
+            ? await findPendingHumanEscalationPayload({
+                approvalId: options.approvalId,
+                workspaceId,
+                syncPort,
+            })
+            : undefined);
+    if (escalationPayload) {
+        const reviewerEmail = await resolveReviewerEmail(options.reviewer);
+        const chainResult = runEscalationChain({
+            approvalId: options.approvalId,
+            payload: escalationPayload,
+            reviewerEmail,
+            runner: input.runner,
+            cwd: reviewRoot,
+        });
+        if (!chainResult.success) {
+            const step = chainResult.failedStep;
+            const joined = step ? `${step.command} ${step.args.join(' ')}` : 'unknown step';
+            throw new Error(`${LOG_PREFIX} Resolver chain failed at: ${joined} (exit ${step?.status ?? 'null'}). ` +
+                `Approval ${options.approvalId} left pending — fix the underlying issue and re-run ` +
+                `pnpm approval:review --approve ${options.approvalId}.`);
+        }
+        // Successful chain → remove the sidecar so re-approval is a no-op.
+        try {
+            const sidecarPath = getEscalationSidecarPath(options.approvalId, reviewRoot);
+            if (existsSync(sidecarPath))
+                unlinkSync(sidecarPath);
+        }
+        catch {
+            // Non-fatal — resolver already succeeded.
+        }
+    }
     const payload = {
         workspace_id: workspaceId,
         approval_id: options.approvalId,
@@ -92,9 +305,11 @@ export async function runApprovalReview(options, input = {}) {
     };
     return syncPort.resolveApproval(payload);
 }
+/** WU-2874: Exported for integration tests that assert on approval type guards. */
+export { HUMAN_ESCALATION_APPROVAL_TYPE };
 export async function main(argv = process.argv) {
     const options = parseOptions(argv);
-    const result = (await runApprovalReview(options));
+    const result = await runApprovalReview(options);
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
         return;

package/dist/approval-review.js.map

@@ -1 +1 @@
-{"version":3,"file":"approval-review.js","sourceRoot":"","sources":["../src/approval-review.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approval-review.js","sourceRoot":"","sources":["../src/approval-review.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAwB,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EACL,8BAA8B,EAC9B,gCAAgC,GAKjC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EACL,8BAA8B,EAC9B,wBAAwB,EACxB,qBAAqB,GAEtB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,UAAU,GAAG,mBAAmB,CAAC;AACvC,MAAM,cAAc,GAAG,YAAY,CAAC,gBAAgB,CAAC;AACrD,MAAM,qBAAqB,GAAsB,MAAM,CAAC;AACxD,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAmB,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AACvF,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAmB1C,SAAS,YAAY,CAAC,OAAiB,OAAO,CAAC,IAAI;IACjD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;SAC1B,IAAI,CAAC,iBAAiB,CAAC;SACvB,WAAW,CAAC,4DAA4D,CAAC;QAC1E,+EAA+E;SAC9E,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CAAC;SAClD,MAAM,CAAC,uBAAuB,EAAE,0CAA0C,CAAC;SAC3E,MAAM,CAAC,wBAAwB,EAAE,qCAAqC,CAAC;SACvE,MAAM,CAAC,qBAAqB,EAAE,qCAAqC,CAAC;SACpE,MAAM,CAAC,mBAAmB,EAAE,0BAA0B,CAAC;SACvD,MAAM,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;SACnD,MAAM,CAAC,wBAAwB,EAAE,8BAA8B,EAAE,qBAAqB,CAAC;SACvF,MAAM,CACL,oBAAoB,EACpB,6FAA6F,CAC9F;SACA,MAAM,CAAC,qBAAqB,EAAE,2CAA2C,CAAC;SAC1E,MAAM,CAAC,QAAQ,EAAE,sBAAsB,EAAE,KAAK,CAAC;SAC/C,QAAQ,CAAC,cAAc,EAAE,sDAAsD,CAAC;SAChF,YAAY,EAAE,CAAC;IAElB,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,cAAc,GAAG,KAA0B,CAAC;QAClD,IACE,cAAc,CAAC,IAAI,KAAK,yBAAyB;YACjD,cAAc,CAAC,IAAI,KAAK,mBAAmB,EAC3C,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAWvB,CAAC;IACL,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAEnC,oFAAoF;IACpF,MAAM,aAAa,GACjB,MAAM,CAAC,EAAE;QACT,CAAC,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QACjE,CAAC,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3D,UAAU,CAAC;IACb,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IAED,qEAAqE;IACrE,IAAI,WAAW,GAAuB,MAAM,CAAC,QAAQ,CAAC;IACtD,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,WAAW,GAAG,UAAU,CAAC;IAC3E,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,WAAW,GAAG,UAAU,CAAC;IACxE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAsB,CAAC;IACxD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,uBAAuB,WAAW,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,eAAe,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,qBAAqB,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9E,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,eAAoC,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,4BAA4B,eAAe,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,OAAO;QACL,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE;QAChC,QAAQ;QACR,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE;QAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE;QACrC,YAAY,EAAE,eAAoC;QAClD,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE;QACjC,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE;QACvC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,KAAK;KAC3B,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAC7B,aAAqB,EACrB,WAA8B,EAC9B,mBAA4B;IAE5B,MAAM,iBAAiB,GAAG,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,6BAA6B,iBAAiB,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,iBAAiB,GAAG,SAAS,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,gCAAgC,CAAC,iBAAiB,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,mBAAmB,IAAI,MAAM,CAAC,EAAE,CAAC;IACrD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO;QACL,WAAW;QACX,QAAQ,EAAE,8BAA8B,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE;YACxE,WAAW;SACZ,CAAC;KACH,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,MAIzB;IACC,MAAM,YAAY,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,OAAO,GAAG,UAAU,YAAY,MAAM,CAAC,WAAW,OAAO,MAAM,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;AAC1F,CAAC;AAkBD,MAAM,aAAa,GAA0B,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;IACtE,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE;QACtC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;KACxC,CAAC,CAAC;IACH,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACrE,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;KACtE,CAAC;AACJ,CAAC,CAAC;AAsBF,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,UAAkB,OAAO,CAAC,GAAG,EAAE,EAC/B,QAA0B;IAE1B,MAAM,gBAAgB,GAAG,QAAQ,IAAI,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,EAAE,cAAc,EAAE,GAAG,kBAAkB,CAAC;IAE9C,IAAI,gBAAgB,CAAC,IAAI,KAAK,cAAc,CAAC,QAAQ,EAAE,CAAC;QACtD,OAAO,gBAAgB,CAAC,YAAY,CAAC;IACvC,CAAC;IACD,IACE,gBAAgB,CAAC,IAAI,KAAK,cAAc,CAAC,IAAI;QAC7C,gBAAgB,CAAC,IAAI,KAAK,cAAc,CAAC,QAAQ,EACjD,CAAC;QACD,OAAO,gBAAgB,CAAC,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA2B;IAC5D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,aAAa,CAAC;IAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACtB,MAAM,KAAK,GAA0B,EAAE,CAAC;IAExC,MAAM,YAAY,GAAG;QACnB,aAAa;QACb,WAAW;QACX,MAAM;QACN,KAAK,CAAC,OAAO,CAAC,EAAE;QAChB,YAAY;QACZ,KAAK,CAAC,aAAa;KACpB,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,MAAM,YAAY,GAAwB;QACxC,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,QAAQ,CAAC,MAAM;KACxB,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;IAC7D,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAClC,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACzE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAwB;QACpC,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;IACzD,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,oBAAoB,CAAC,QAAiB;IACnD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,uFAAuF,CACxF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,oCAAoC,CAAC,UAAkB,EAAE,MAAc;IAC9E,OAAO,CACL,GAAG,UAAU,kDAAkD,UAAU,KAAK,MAAM,IAAI;QACxF,kFAAkF;QAClF,6BAA6B,CAC9B,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc,EAAE,SAAiB,EAAE,UAAkB;IAC/E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,UAAU,EAAE,YAAY,SAAS,EAAE,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAClF,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,UAAkB;IACtD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,EAAE,CAAC;QAClF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,KAAK,CACb,oCAAoC,CAClC,UAAU,EACV,qDAAqD,CACtD,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wCAAwC,CACtD,MAAsB;IAEtB,IAAI,MAAM,CAAC,IAAI,KAAK,8BAA8B,EAAE,CAAC;QACnD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,oCAAoC,CAClC,MAAM,CAAC,WAAW,EAClB,qCAAqC,CACtC,CACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,EAAE,EAAE,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC;QAC3E,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC;QACnE,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,WAAW,CAAC;KAC3F,CAAC;IAEF,MAAM,eAAe,GAAG,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7E,IAAI,eAAe;QAAE,OAAO,CAAC,eAAe,GAAG,eAAe,CAAC;IAE/D,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,IAAI,KAAK;QAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IAEjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,iCAAiC,CAAC,KAIhD;IACC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC;QAChD,YAAY,EAAE,KAAK,CAAC,WAAW;QAC/B,MAAM,EAAE,SAAS;QACjB,IAAI,EAAE,8BAA8B;QACpC,KAAK,EAAE,6BAA6B;KACrC,CAAC,CAAC;IACH,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAC1C,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,KAAK,KAAK,CAAC,UAAU,CACxD,CAAC;IACF,OAAO,cAAc,CAAC,CAAC,CAAC,wCAAwC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAmB,EACnB,QAII,EAAE;IAEN,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACrD,MAAM,UAAU,GAAG,MAAM,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAC9D,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,sBAAsB,CACtD,OAAO,EACP,KAAK,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAChC,OAAO,CAAC,WAAW,CACpB,CAAC;IAEF,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,2EAA2E;IAC3E,uEAAuE;IACvE,mEAAmE;IACnE,MAAM,OAAO,GACX,OAAO,CAAC,QAAQ,KAAK,UAAU;QAC7B,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,CAAC;QACvD,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,iBAAiB,GACrB,OAAO;QACP,CAAC,OAAO,CAAC,QAAQ,KAAK,UAAU;YAC9B,CAAC,CAAC,MAAM,iCAAiC,CAAC;gBACtC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,WAAW;gBACX,QAAQ;aACT,CAAC;YACJ,CAAC,CAAC,SAAS,CAAC,CAAC;IAEjB,IAAI,iBAAiB,EAAE,CAAC;QACtB,MAAM,aAAa,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnE,MAAM,WAAW,GAAG,kBAAkB,CAAC;YACrC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,OAAO,EAAE,iBAAiB;YAC1B,aAAa;YACb,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,EAAE,UAAU;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC;YACpC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC;YAChF,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,8BAA8B,MAAM,UAAU,IAAI,EAAE,MAAM,IAAI,MAAM,KAAK;gBACpF,YAAY,OAAO,CAAC,UAAU,sDAAsD;gBACpF,kCAAkC,OAAO,CAAC,UAAU,GAAG,CAC1D,CAAC;QACJ,CAAC;QACD,mEAAmE;QACnE,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,wBAAwB,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YAC7E,IAAI,UAAU,CAAC,WAAW,CAAC;gBAAE,UAAU,CAAC,WAAW,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,0CAA0C;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAyB;QACpC,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,OAAO,CAAC,UAAU;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO,CAAC,YAAY;QACnC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,CAAC;IAEF,OAAO,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,mFAAmF;AACnF,OAAO,EAAE,8BAA8B,EAAE,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAiB,OAAO,CAAC,IAAI;IACtD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;AACpB,CAAC"}

package/dist/lumenflow-upgrade.js

@@ -39,7 +39,7 @@ import { generateScriptsFromManifest } from './public-manifest.js';
 import { loadTemplate, processTemplate, CORE_DOC_TEMPLATE_PATHS, buildCoreDocTokens, executeDocsSyncInDir, } from './docs-sync.js';
 // WU-2864: propagate the .gitattributes merge=union rule to consumer repos
 // on upgrade so rebase conflicts on append-only JSONL state files auto-resolve.
-import { scaffoldGitattributes } from './init-safety-scripts.js';
+import { scaffoldGitattributes, scaffoldGitignore } from './init-safety-scripts.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[lumenflow:upgrade]';
 /** Operation name for micro-worktree */
@@ -813,6 +813,33 @@ async function _runUpgradeTransaction(addCommand, versionSpec, upgradeId) {
             if (docsSyncResult.created.length > 0) {
                 console.log(`${LOG_PREFIX} Synced ${docsSyncResult.created.length} doc file(s)`);
             }
+            // WU-2876: Reconcile .gitignore against LUMENFLOW_RUNTIME_WRITE_PATHS +
+            // REQUIRED_GITIGNORE_EXCLUSIONS for existing consumers. Consumers that
+            // initialised before v5.2 never received the `.lumenflow/state/*.jsonl`
+            // glob and see runtime-write files (e.g. display-name-reservations.jsonl)
+            // show up as dirty in source control. scaffoldGitignore's merge path
+            // preserves user-owned lines outside the LumenFlow block byte-for-byte,
+            // and when no .gitignore exists it writes the full GITIGNORE_TEMPLATE.
+            // Called before scaffoldGitattributes to mirror init.ts ordering.
+            const giResult = {
+                created: [],
+                skipped: [],
+                merged: [],
+                warnings: [],
+                overwritten: [],
+            };
+            await scaffoldGitignore(worktreePath, { force: false, full: false }, giResult);
+            const giTouched = giResult.created.length > 0 ||
+                (giResult.merged?.length ?? 0) > 0 ||
+                (giResult.overwritten?.length ?? 0) > 0;
+            if (giTouched) {
+                const action = giResult.created.length > 0
+                    ? 'Created'
+                    : (giResult.overwritten?.length ?? 0) > 0
+                        ? 'Rewrote'
+                        : 'Updated managed block in';
+                console.log(`${LOG_PREFIX} ${action} .gitignore (WU-2876 runtime-write-path reconciliation)`);
+            }
             // WU-2864: Propagate the .gitattributes merge=union rule for append-only
             // JSONL state files. This is the sibling of syncCoreDocs — a managed
             // block that consumer repos need to receive on every upgrade so future
@@ -846,6 +873,7 @@ async function _runUpgradeTransaction(addCommand, versionSpec, upgradeId) {
                     UPGRADE_MARKER_RELATIVE_PATH,
                     ...docsSyncResult.allFiles,
                     ...(gaTouched ? ['.gitattributes'] : []),
+                    ...(giTouched ? ['.gitignore'] : []),
                 ],
             };
         },