@empire-builder-kit/nx 1.0.0-rc.44 → 1.0.0-rc.46

package/src/git-policy/github-bootstrap.js

@@ -203,11 +203,7 @@ function requiresImmutableOidcSubjectCutover(state) {
 function immutableOidcTrustAcknowledgement(identity) {
     return `${GITHUB_IMMUTABLE_OIDC_TRUST_ACKNOWLEDGEMENT_PREFIX}${identity.subjectPrefix}`;
 }
-const PRIVATE_ENVIRONMENT_REVIEWER_PLANS = new Set([
-    'business_plus',
-    'enterprise',
-    'enterprise_cloud',
-]);
+const PRIVATE_ENVIRONMENT_REVIEWER_PLANS = new Set(['enterprise']);
 class GitHubApiError extends Error {
     status;
     constructor(status, message) {
@@ -575,6 +571,14 @@ async function inspectEnvironment(api, repositoryPath, name) {
         branchPolicies: branchPolicyValues,
         customBranchPolicies,
         exists: true,
+        canAdminsBypass: environment.can_admins_bypass === false ? false : true,
+        protectedBranches: typeof environment.deployment_branch_policy === 'object' &&
+            environment.deployment_branch_policy !== null &&
+            'protected_branches' in environment.deployment_branch_policy &&
+            typeof environment.deployment_branch_policy.protected_branches ===
+                'boolean'
+            ? environment.deployment_branch_policy.protected_branches
+            : undefined,
         preventSelfReview: reviewers.preventSelfReview,
         reviewers: reviewers.reviewers,
         secretNames: namedValues(secrets),
@@ -786,7 +790,7 @@ function evaluate(repository, state, inspectionBlockers, productionApprovalMode,
         privateRepository &&
         state.ownerPlanName !== undefined &&
         !PRIVATE_ENVIRONMENT_REVIEWER_PLANS.has(state.ownerPlanName)) {
-        blockers.push(`Committed environment-reviewer mode requires GitHub Enterprise support for a private repository; the inspected owner plan is ${state.ownerPlanName}.`);
+        blockers.push(`Committed environment-reviewer mode does not support inspected owner plan ${state.ownerPlanName} under EBK's verified private environment-reviewer contract; supported REST plan.name: enterprise.`);
     }
     if (state.repo.allow_merge_commit !== true) {
         changes.push('Enable repository merge commits.');
@@ -1099,7 +1103,96 @@ async function applyChanges(api, repositoryPath, state, productionApprovalMode,
         }
     }
 }
+async function runFrameworkNpmStableBootstrap(options) {
+    if (options.repository !== 'empire-builder-kit/empire-builder-kit')
+        throw new Error('npm-stable is restricted to the exact framework repository.');
+    if (!options.token.trim())
+        throw new Error('GH_TOKEN or GITHUB_TOKEN is required for GitHub bootstrap.');
+    if (!Array.isArray(options.npmStableReviewerIds) ||
+        options.npmStableReviewerIds.length < 1 ||
+        options.npmStableReviewerIds.length > 6 ||
+        options.npmStableReviewerIds.some((id) => !Number.isSafeInteger(id) || id <= 0) ||
+        new Set(options.npmStableReviewerIds).size !==
+            options.npmStableReviewerIds.length ||
+        typeof options.npmStablePreventSelfReview !== 'boolean') {
+        throw new Error('npm-stable requires exact reviewer IDs and explicit prevent-self-review choice.');
+    }
+    const reviewers = existingReviewerPayload([...options.npmStableReviewerIds].sort((left, right) => left - right));
+    const api = new GitHubApi(options.apiBaseUrl?.trim() || 'https://api.github.com', options.token);
+    const repositoryPath = '/repos/empire-builder-kit/empire-builder-kit';
+    const repo = await api.request('GET', repositoryPath);
+    if (repo.full_name !== options.repository)
+        throw new Error('npm-stable repository readback differs from its exact target.');
+    const environmentPath = `${repositoryPath}/environments/npm-stable`;
+    const inspectStable = () => inspectEnvironment(api, repositoryPath, 'npm-stable');
+    const evaluateStable = (state) => {
+        const changes = [];
+        const blockers = [];
+        if (!state.exists ||
+            !state.customBranchPolicies ||
+            state.protectedBranches !== false ||
+            state.canAdminsBypass !== false ||
+            state.preventSelfReview !== options.npmStablePreventSelfReview ||
+            state.waitTimer !== 0 ||
+            JSON.stringify(state.reviewers) !== JSON.stringify(reviewers)) {
+            changes.push('Set exact npm-stable reviewers, explicit self-review choice, administrator bypass false, and custom main-only policy.');
+        }
+        if (state.branchPolicies.length !== 1 ||
+            state.branchPolicies[0]?.name !== 'main' ||
+            state.branchPolicies[0]?.type !== 'branch')
+            changes.push('Restrict npm-stable to the main branch only.');
+        if ([...state.secretNames, ...state.variableNames].some((name) => FORBIDDEN_NPM_TOKEN_NAMES.some((tokenName) => name.toUpperCase() === tokenName)))
+            blockers.push('npm-stable may not contain npm token credentials.');
+        return {
+            kind: 'framework-npm-stable',
+            repository: options.repository,
+            ready: changes.length === 0 && blockers.length === 0,
+            blockers,
+            changes,
+            warnings: [],
+        };
+    };
+    const initial = await inspectStable();
+    const report = evaluateStable(initial);
+    if (!options.apply)
+        return report;
+    if (report.blockers.length)
+        throw new Error(`npm-stable apply is blocked: ${report.blockers.join(' ')}`);
+    if (report.ready)
+        return report;
+    await api.request('PUT', environmentPath, {
+        can_admins_bypass: false,
+        deployment_branch_policy: {
+            protected_branches: false,
+            custom_branch_policies: true,
+        },
+        prevent_self_review: options.npmStablePreventSelfReview,
+        reviewers,
+        wait_timer: 0,
+    });
+    const policies = await readPagedObjects(api, `${environmentPath}/deployment-branch-policies`, 'branch_policies');
+    let mainRetained = false;
+    for (const policy of policies) {
+        if (policy.name === 'main' && policy.type === 'branch' && !mainRetained) {
+            mainRetained = true;
+            continue;
+        }
+        if (!Number.isSafeInteger(policy.id) ||
+            typeof policy.id !== 'number' ||
+            policy.id <= 0)
+            throw new Error('npm-stable branch policy has no exact deletion identity.');
+        await api.request('DELETE', `${environmentPath}/deployment-branch-policies/${policy.id}`);
+    }
+    if (!mainRetained)
+        await api.request('POST', `${environmentPath}/deployment-branch-policies`, {
+            name: 'main',
+            type: 'branch',
+        });
+    return evaluateStable(await inspectStable());
+}
 async function runGitHubBootstrap(options) {
+    if ('npmStable' in options)
+        return runFrameworkNpmStableBootstrap(options);
     const repository = options.repository.trim();
     const deploymentProfile = options.deploymentProfile ?? 'fully-isolated';
     const { owner, repo } = parseRepository(repository);

package/src/local-dev/dev-command-core.d.ts

@@ -1,4 +1,5 @@
 import { inspectDevelopmentEnvironment } from './environment-inspector.js';
+import type { FleetOperationProgress, FleetOperationWaitOptions } from './fleet-client.js';
 import type { FleetOperationStateRecord, FleetStateRecord } from './fleet-state.js';
 import { type FleetLaunchInput } from './fleet-launcher.js';
 import type { LocalDevContext } from './local-context.js';
@@ -22,9 +23,8 @@ export interface FleetUpCoreClient {
         operationId: string;
         state: 'accepted';
     }>;
-    waitForOperation(operationId: string, options?: {
-        timeoutMs?: number;
-    }): Promise<FleetOperationStateRecord>;
+    /** Resolves on the terminal record, `succeeded` or `failed`. */
+    waitForOperationOutcome(operationId: string, options?: FleetOperationWaitOptions): Promise<FleetOperationStateRecord>;
 }
 export interface FleetUpCoreLaunchResult {
     attached: boolean;
@@ -48,7 +48,28 @@ export interface FleetUpCoreEffects {
     inspectEnvironment?: typeof inspectDevelopmentEnvironment;
     launchFleet?: (input: FleetLaunchInput) => Promise<FleetUpCoreLaunchResult>;
     reportCleanupFailure?: (message: string) => void;
+    /** One human progress line while an operation is observed (stderr). */
+    reportProgress?: (line: string) => void;
 }
+/** Aspirational duration targets per Fleet command, taken from the measured
+ * two-Slice figures in docs/local-development.md (fresh up 334-442 s, down
+ * 242-345 s, restart about 70-85 s). Exceeding one prints a "slower than
+ * target" line; it never fails or stops observing an operation. */
+export declare const FLEET_OPERATION_TARGET_MS: Readonly<{
+    down: 350000;
+    restart: 90000;
+    up: 450000;
+}>;
+/** Progress lines for a watched Fleet operation; the first report past the
+ * command's target says so once, and observation continues. */
+export declare function fleetOperationProgressReporter(command: keyof typeof FLEET_OPERATION_TARGET_MS, report: (line: string) => void): (progress: FleetOperationProgress) => void;
+/** Human cause for a terminal failed operation record. */
+export declare function fleetOperationFailureDetail(operation: FleetOperationStateRecord): string;
+/** Owned-cleanup settlement attached to an error from a foreground `up` whose
+ * in-process supervisor can outlive the failure. Callers report the error
+ * first, then keep interrupt handling installed until this settles, exactly as
+ * they do with `afterWrite` after a successful foreground `up`. */
+export declare function foregroundUpSettlement(error: unknown): Promise<void> | undefined;
 export declare function executeFleetUpCore(command: FleetUpCoreCommand, input: {
     appData: string;
     context: LocalDevContext;

package/src/local-dev/dev-command-core.js

@@ -1,12 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLEET_OPERATION_TARGET_MS = void 0;
+exports.fleetOperationProgressReporter = fleetOperationProgressReporter;
+exports.fleetOperationFailureDetail = fleetOperationFailureDetail;
+exports.foregroundUpSettlement = foregroundUpSettlement;
 exports.executeFleetUpCore = executeFleetUpCore;
 const node_crypto_1 = require("node:crypto");
 const environment_inspector_js_1 = require("./environment-inspector.js");
 const errors_js_1 = require("./errors.js");
 const fleet_launcher_js_1 = require("./fleet-launcher.js");
 const nx_workspace_js_1 = require("./nx-workspace.js");
-function foregroundWait(launch, command, signal, idempotencyKey, reportCleanupFailure) {
+/** Aspirational duration targets per Fleet command, taken from the measured
+ * two-Slice figures in docs/local-development.md (fresh up 334-442 s, down
+ * 242-345 s, restart about 70-85 s). Exceeding one prints a "slower than
+ * target" line; it never fails or stops observing an operation. */
+exports.FLEET_OPERATION_TARGET_MS = Object.freeze({
+    down: 350_000,
+    restart: 90_000,
+    up: 450_000,
+});
+function progressClock(milliseconds) {
+    const seconds = Math.max(0, Math.floor(milliseconds / 1_000));
+    return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+}
+function describeSliceProgress(slice) {
+    const details = [
+        ...(slice.cleanup === 'failed' ? ['cleanup failed'] : []),
+        ...(slice.restartAttempts > 0
+            ? [`restart attempt ${slice.restartAttempts}`]
+            : []),
+    ];
+    return `${slice.name} ${slice.routeState}${details.length > 0 ? ` (${details.join(', ')})` : ''}`;
+}
+/** Progress lines for a watched Fleet operation; the first report past the
+ * command's target says so once, and observation continues. */
+function fleetOperationProgressReporter(command, report) {
+    const targetMs = exports.FLEET_OPERATION_TARGET_MS[command];
+    let exceeded = false;
+    return ({ elapsedMs, operation, slices }) => {
+        const summary = slices.length > 0
+            ? slices.map(describeSliceProgress).join(', ')
+            : `operation ${operation.state}`;
+        if (!exceeded && elapsedMs > targetMs) {
+            exceeded = true;
+            report(`[ebk dev ${command}] ${progressClock(elapsedMs)} slower than the ${progressClock(targetMs)} target for ${command}; still running: ${summary}`);
+            return;
+        }
+        report(`[ebk dev ${command}] ${progressClock(elapsedMs)} ${summary}`);
+    };
+}
+/** Human cause for a terminal failed operation record. */
+function fleetOperationFailureDetail(operation) {
+    return operation.failureMessage ? ` Cause: ${operation.failureMessage}` : '';
+}
+function foregroundWait(launch, command, signal, idempotencyKey, reportCleanupFailure, reportProgress) {
     if (!command.foreground || !launch.runtime)
         return undefined;
     const stop = async () => {
@@ -24,11 +71,15 @@ function foregroundWait(launch, command, signal, idempotencyKey, reportCleanupFa
                 }
             }
             if (down) {
-                const operation = await launch.client.waitForOperation(down.operationId, {
-                    timeoutMs: command.timeoutMs ?? 120_000,
-                });
+                // The supervisor lives in this process: a capped wait could only
+                // abandon its shutdown, so observe the down until it settles.
+                const operation = await launch.client.waitForOperationOutcome(down.operationId, reportProgress
+                    ? {
+                        onProgress: fleetOperationProgressReporter('down', reportProgress),
+                    }
+                    : {});
                 if (operation.state !== 'succeeded') {
-                    throw new errors_js_1.LocalDevContractError(operation.failureClassification ?? 'operation-conflict', 'Foreground Fleet down did not complete successfully; ownership was retained.');
+                    throw new errors_js_1.LocalDevContractError(operation.failureClassification ?? 'operation-conflict', `Foreground Fleet down did not complete successfully; ownership was retained.${fleetOperationFailureDetail(operation)}`);
                 }
             }
             await launch.client.shutdown(idempotencyKey());
@@ -46,6 +97,14 @@ function foregroundWait(launch, command, signal, idempotencyKey, reportCleanupFa
         signal.removeEventListener('abort', onAbort);
     });
 }
+const foregroundSettlements = new WeakMap();
+/** Owned-cleanup settlement attached to an error from a foreground `up` whose
+ * in-process supervisor can outlive the failure. Callers report the error
+ * first, then keep interrupt handling installed until this settles, exactly as
+ * they do with `afterWrite` after a successful foreground `up`. */
+function foregroundUpSettlement(error) {
+    return error instanceof Error ? foregroundSettlements.get(error) : undefined;
+}
 async function executeFleetUpCore(command, input, effects = {}) {
     const slices = (0, nx_workspace_js_1.selectWorkspaceSlices)(input.plan, command.selector);
     const inspect = effects.inspectEnvironment ?? environment_inspector_js_1.inspectDevelopmentEnvironment;
@@ -78,7 +137,8 @@ async function executeFleetUpCore(command, input, effects = {}) {
         }
         throw error;
     }
-    const afterWrite = foregroundWait(launch, command, input.signal, idempotencyKey, effects.reportCleanupFailure ?? (() => undefined));
+    const reportCleanupFailure = effects.reportCleanupFailure ?? (() => undefined);
+    const afterWrite = foregroundWait(launch, command, input.signal, idempotencyKey, reportCleanupFailure, effects.reportProgress);
     if (command.noWait) {
         return {
             ...(afterWrite ? { afterWrite } : {}),
@@ -88,21 +148,73 @@ async function executeFleetUpCore(command, input, effects = {}) {
             operationId: submission.operationId,
         };
     }
-    const operation = await launch.client.waitForOperation(submission.operationId, command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs });
+    if (command.foreground && command.timeoutMs !== undefined) {
+        effects.reportProgress?.('[ebk dev up] --timeout does not apply to a foreground up: its supervisor runs in this process, so the command watches until the outcome.');
+    }
+    let observed;
+    try {
+        // No default deadline: watch the supervised up until it settles. Only an
+        // explicit --timeout caps a detached wait, and in detached mode an
+        // interrupt ends observation; neither cancels the operation. A foreground
+        // up takes neither: its supervisor lives in this process, so a cap could
+        // only abandon it, and an interrupt instead drives the owned down above,
+        // which this wait then observes fail.
+        const operation = await launch.client.waitForOperationOutcome(submission.operationId, {
+            ...(command.foreground || command.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: command.timeoutMs }),
+            ...(command.foreground ? {} : { signal: input.signal }),
+            ...(effects.reportProgress
+                ? {
+                    onProgress: fleetOperationProgressReporter('up', effects.reportProgress),
+                }
+                : {}),
+        });
+        observed =
+            operation.state === 'failed'
+                ? { operation }
+                : { operation, slices: (await launch.client.status()).slices };
+    }
+    catch (error) {
+        if (afterWrite && !input.signal.aborted) {
+            effects.reportProgress?.('[ebk dev up] The foreground Fleet supervisor keeps running in this process. Interrupt to run owned cleanup, or run ebk dev down --all from another terminal.');
+        }
+        throw holdForegroundSettlement(error, afterWrite);
+    }
+    const { operation } = observed;
     if (operation.state === 'failed') {
-        if (!launch.attached) {
-            await launch.client.shutdown(idempotencyKey()).catch(() => undefined);
+        // After a foreground interrupt the owned down and shutdown already run; a
+        // second shutdown here would only be refused while that down runs.
+        if (!launch.attached && !(afterWrite && input.signal.aborted)) {
+            await launch.client.shutdown(idempotencyKey()).catch((error) => {
+                reportCleanupFailure(`Fleet up failed and the supervisor it launched refused to shut down, so it keeps running and keeps its claims: ${error instanceof Error ? error.message : String(error)} ${afterWrite
+                    ? 'It runs in this process: interrupt to retry owned cleanup, or run ebk dev down --all from another terminal.'
+                    : 'Check ebk dev status, then run ebk dev down --all to retry cleanup.'}`);
+            });
         }
-        throw new errors_js_1.LocalDevContractError(operation.failureClassification ?? 'internal-error', `Fleet up failed after transactional rollback (${operation.failureClassification ?? 'internal-error'}).`);
+        throw holdForegroundSettlement(new errors_js_1.LocalDevContractError(operation.failureClassification ?? 'internal-error', `Fleet up failed after transactional rollback (${operation.failureClassification ?? 'internal-error'}).${fleetOperationFailureDetail(operation)}`), afterWrite);
     }
-    const state = await launch.client.status();
     return {
         ...(afterWrite ? { afterWrite } : {}),
         attached: launch.attached,
         fleetId: launch.fleetId,
         operation,
         operationId: submission.operationId,
-        slices: state.slices,
+        slices: observed.slices,
     };
 }
+/** A foreground supervisor lives in this process and can outlive a failed
+ * wait: a refused shutdown keeps it, and an interrupt's owned down may still
+ * run. Attach its settlement so the caller reports the failure, then holds
+ * interrupt handling until owned cleanup settles instead of leaving Node's
+ * default handler to kill the process. */
+function holdForegroundSettlement(error, afterWrite) {
+    if (!afterWrite)
+        return error;
+    const failure = error instanceof Error
+        ? error
+        : new errors_js_1.LocalDevContractError('internal-error', String(error));
+    foregroundSettlements.set(failure, afterWrite);
+    return failure;
+}
 //# sourceMappingURL=dev-command-core.js.map

package/src/local-dev/errors.d.ts

@@ -1,6 +1,24 @@
-export declare const LOCAL_DEV_FAILURE_CLASSIFICATIONS: readonly ["invalid-input", "personal-identity-unavailable", "fleet-in-use", "fleet-ownership-ambiguous", "local-context-missing", "local-context-invalid", "local-context-conflict", "unknown-slice", "invalid-adapter", "slice-active-elsewhere", "slice-claim-ambiguous", "not-running", "invalid-state", "configuration-mismatch", "protocol-mismatch", "environment-deficient", "prerequisite-unavailable", "foundation-unavailable", "operation-conflict", "readiness-timeout", "provisioning-timeout", "startup-interrupted", "cleanup-incomplete", "supervisor-unreachable", "stale-state", "stale-state-ambiguous", "log-query-invalid", "internal-error"];
+export declare const LOCAL_DEV_FAILURE_CLASSIFICATIONS: readonly ["invalid-input", "personal-identity-unavailable", "fleet-in-use", "fleet-ownership-ambiguous", "local-context-missing", "local-context-invalid", "local-context-conflict", "unknown-slice", "invalid-adapter", "slice-active-elsewhere", "slice-claim-ambiguous", "not-running", "invalid-state", "configuration-mismatch", "protocol-mismatch", "environment-deficient", "prerequisite-unavailable", "foundation-unavailable", "operation-conflict", "readiness-timeout", "readiness-stalled", "health-check-failing", "provisioning-timeout", "process-exited", "startup-interrupted", "observation-timeout", "observation-interrupted", "cleanup-incomplete", "supervisor-unreachable", "stale-state", "stale-state-ambiguous", "log-query-invalid", "internal-error"];
 export type LocalDevFailureClassification = (typeof LOCAL_DEV_FAILURE_CLASSIFICATIONS)[number];
 export declare class LocalDevContractError extends Error {
     readonly classification: LocalDevFailureClassification;
     constructor(classification: LocalDevFailureClassification, message: string);
 }
+/** What the client knew when it stopped watching an accepted operation that
+ * had not settled. The operation itself may still be running. */
+export interface FleetObservationDetail {
+    elapsedMs: number;
+    /** The last non-terminal state read; absent when no read succeeded. */
+    lastObservedState?: 'accepted' | 'running';
+    operationId: string;
+    /** The explicit cap, present only for `observation-timeout`. */
+    timeoutMs?: number;
+}
+/** Observation of an accepted operation ended without a terminal record: at an
+ * explicit cap, on interruption, or because the supervisor stopped answering.
+ * The CLI renders `detail` in the failure envelope, with the operation ID at
+ * the envelope level, so a script can keep following the same operation. */
+export declare class FleetObservationError extends LocalDevContractError {
+    readonly detail: FleetObservationDetail;
+    constructor(classification: 'observation-interrupted' | 'observation-timeout' | 'supervisor-unreachable', message: string, detail: FleetObservationDetail);
+}

package/src/local-dev/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalDevContractError = exports.LOCAL_DEV_FAILURE_CLASSIFICATIONS = void 0;
+exports.FleetObservationError = exports.LocalDevContractError = exports.LOCAL_DEV_FAILURE_CLASSIFICATIONS = void 0;
 exports.LOCAL_DEV_FAILURE_CLASSIFICATIONS = [
     'invalid-input',
     'personal-identity-unavailable',
@@ -22,8 +22,13 @@ exports.LOCAL_DEV_FAILURE_CLASSIFICATIONS = [
     'foundation-unavailable',
     'operation-conflict',
     'readiness-timeout',
+    'readiness-stalled',
+    'health-check-failing',
     'provisioning-timeout',
+    'process-exited',
     'startup-interrupted',
+    'observation-timeout',
+    'observation-interrupted',
     'cleanup-incomplete',
     'supervisor-unreachable',
     'stale-state',
@@ -40,4 +45,16 @@ class LocalDevContractError extends Error {
     }
 }
 exports.LocalDevContractError = LocalDevContractError;
+/** Observation of an accepted operation ended without a terminal record: at an
+ * explicit cap, on interruption, or because the supervisor stopped answering.
+ * The CLI renders `detail` in the failure envelope, with the operation ID at
+ * the envelope level, so a script can keep following the same operation. */
+class FleetObservationError extends LocalDevContractError {
+    detail;
+    constructor(classification, message, detail) {
+        super(classification, message);
+        this.detail = detail;
+    }
+}
+exports.FleetObservationError = FleetObservationError;
 //# sourceMappingURL=errors.js.map

package/src/local-dev/fleet-client.d.ts

@@ -1,19 +1,67 @@
 import { type FleetMutationCommand } from './control-contract.js';
+import { LocalDevContractError } from './errors.js';
 import { sendFleetControlRequest } from './fleet-ipc.js';
-import { type FleetOperationStateRecord, type FleetStateRecord } from './fleet-state.js';
+import { type FleetOperationStateRecord, type FleetSliceState, type FleetStateRecord } from './fleet-state.js';
 import { type PrivateStateSecurity } from './private-state.js';
 import type { FleetRuntimePaths } from './runtime-paths.js';
 export interface FleetClientEffects {
+    /** Monotonic-enough wall clock for observation bookkeeping (tests inject). */
+    now?: () => number;
     requestId?: () => string;
     send?: typeof sendFleetControlRequest;
+    /** Poll pause; resolves early when the signal aborts (tests inject). */
+    sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
 }
+/** A supervisor whose authenticated status keeps answering with the same
+ * heartbeat for this long is not making progress. The supervisor writes its
+ * heartbeat every 5 s; Windows identity captures can block its loop longer.
+ * The window must also span enough consecutive status reads (see
+ * `waitForOperationOutcome`), so a host sleep that jumps the clock cannot
+ * trip it before the supervisor's next heartbeat. */
+export declare const FLEET_SUPERVISOR_HEARTBEAT_STALE_MS: Readonly<{
+    default: 30000;
+    win32: 60000;
+}>;
+/** Defaults for watching a supervised operation. None of them is an operation
+ * deadline: without an explicit cap the client waits for the real outcome. */
+export declare const FLEET_OPERATION_OBSERVATION: Readonly<{
+    pollMs: 200;
+    /** Progress is reported on every Slice change and at least this often. */
+    progressIntervalMs: 30000;
+    /** Status (heartbeat and Slice progress) is read at most this often. */
+    statusIntervalMs: 2000;
+    /** Consecutive unreachable polls tolerated before the wait fails. */
+    unreachableLimit: 6;
+}>;
+export interface FleetOperationProgress {
+    elapsedMs: number;
+    operation: FleetOperationStateRecord;
+    /** Live state of the operation's Slices from the latest status read. */
+    slices: FleetSliceState[];
+}
+export interface FleetOperationWaitOptions {
+    onProgress?: (progress: FleetOperationProgress) => void;
+    pollMs?: number;
+    /** Ends observation (never the operation) when aborted. */
+    signal?: AbortSignal;
+    /** Explicit observation cap. Absent means wait for the terminal state. */
+    timeoutMs?: number;
+}
+export interface FleetOperationObservationTuning {
+    progressIntervalMs?: number;
+    staleHeartbeatMs?: number;
+    statusIntervalMs?: number;
+    unreachableLimit?: number;
+}
+/** Terminal failure as an error that keeps the supervisor's persisted cause. */
+export declare function fleetOperationFailure(operation: FleetOperationStateRecord): LocalDevContractError;
 export interface FleetOperationSubmission {
     operationId: string;
     state: 'accepted';
 }
 export declare class FleetClient {
     #private;
-    constructor(paths: FleetRuntimePaths, security?: PrivateStateSecurity, effects?: FleetClientEffects);
+    constructor(paths: FleetRuntimePaths, security?: PrivateStateSecurity, effects?: FleetClientEffects, observation?: FleetOperationObservationTuning);
     ping(): Promise<{
         fleetId: string;
         protocolVersion: number;
@@ -25,9 +73,19 @@ export declare class FleetClient {
         slices: readonly string[];
     }, idempotencyKey?: `${string}-${string}-${string}-${string}-${string}`): Promise<FleetOperationSubmission>;
     operationStatus(operationId: string): Promise<FleetOperationStateRecord>;
-    waitForOperation(operationId: string, options?: {
-        pollMs?: number;
-        timeoutMs?: number;
-    }): Promise<FleetOperationStateRecord>;
+    /** Wait for a terminal operation record, `succeeded` or `failed`.
+     *
+     * There is no default deadline: an operation that is still progressing is
+     * observed until it settles. The wait ends early only on an explicit
+     * `timeoutMs` cap (`observation-timeout`), on `signal` abort
+     * (`observation-interrupted`), or when the supervisor itself stops making
+     * progress (`supervisor-unreachable`: repeated unreachable polls or a
+     * heartbeat that no longer advances). Ending observation never cancels the
+     * supervised operation.
+     */
+    waitForOperationOutcome(operationId: string, options?: FleetOperationWaitOptions): Promise<FleetOperationStateRecord>;
+    /** Throwing form: resolves only on `succeeded`; a terminal `failed` record
+     * becomes an error carrying its persisted classification and cause. */
+    waitForOperation(operationId: string, options?: FleetOperationWaitOptions): Promise<FleetOperationStateRecord>;
     shutdown(idempotencyKey?: `${string}-${string}-${string}-${string}-${string}`): Promise<void>;
 }