@atolis-hq/wake 0.4.32 → 0.4.33

package/dist/src/bootstrap/surface-api-applications.d.ts

@@ -1,11 +1,13 @@
 import { type ApiApplications } from '../surfaces/index.js';
 import type { CompositionRoot } from './composition-root.js';
+import { UpdateMaintenancePhase } from './update-maintenance-lease.js';
 export declare function createSurfaceApiApplications(root: CompositionRoot, now: () => string): ApiApplications;
 export declare function readControlPlaneStatus(root: CompositionRoot, now: () => string): Promise<{
     data: {
         maintenanceLease?: {
             failure?: string;
-            phase: import("./update-maintenance-lease.js").UpdateMaintenancePhase;
+            attemptId: string;
+            phase: UpdateMaintenancePhase;
             startedAt: string;
         };
         updatedAt: string;

package/dist/src/bootstrap/surface-api-applications.js

@@ -9,6 +9,7 @@ import { projectionMeta, sampledMeta } from './surface-api-metadata.js';
 import { projectionPage } from './surface-api-projection-pages.js';
 import { createSurfaceWorkApplications } from './surface-api-work-applications.js';
 import { createWorkflowDiagramApplications } from './surface-api-workflow-diagrams.js';
+import { UpdateMaintenancePhase } from './update-maintenance-lease.js';
 import { wakeVersion } from './version.js';
 export function createSurfaceApiApplications(root, now) {
     return {
@@ -366,6 +367,33 @@ function createControlPlaneApplications(root, now) {
             await root.controlPlane.resume(command.idempotencyKey);
             return commandAccepted(command, now());
         },
+        async clearMaintenance(command) {
+            const lease = await root.maintenance.read();
+            if (lease === null ||
+                lease.attemptId !== command.attemptId ||
+                lease.phase !== UpdateMaintenancePhase.Failed)
+                return maintenanceClearConflict(lease);
+            try {
+                await root.maintenance.clearFailed(command.attemptId);
+            }
+            catch {
+                return maintenanceClearConflict(await root.maintenance.read());
+            }
+            return commandAccepted(command, now());
+        },
+    };
+}
+function maintenanceClearConflict(lease) {
+    return {
+        conflict: true,
+        code: 'maintenance-not-clearable',
+        detail: 'The failed maintenance lease is no longer available to clear',
+        retryable: false,
+        ...(lease === null
+            ? {}
+            : {
+                current: { attemptId: lease.attemptId, phase: lease.phase, startedAt: lease.startedAt },
+            }),
     };
 }
 export async function readControlPlaneStatus(root, now) {
@@ -382,6 +410,7 @@ export async function readControlPlaneStatus(root, now) {
                 ? {}
                 : {
                     maintenanceLease: {
+                        attemptId: lease.attemptId,
                         phase: lease.phase,
                         startedAt: lease.startedAt,
                         ...(lease.failure === undefined ? {} : { failure: lease.failure }),

package/dist/src/bootstrap/surface-cli-applications.js

@@ -9,7 +9,7 @@ import { BuiltInActivityName, agentActivityDefinition } from '../activities/inde
 import { IntakeHost, ResidentHost, TickHost, } from '../control-plane/index.js';
 import { ExecutionFailureCode, RunStatus, isActiveRunStatus, loadPromptTemplate, } from '../execution/index.js';
 import { ResourceCorrelationRole, resourceId } from '../resources/index.js';
-import { DockerProcessError, createApiDispatcher, createLoggedDockerCli, createPackagedAssetSource, createPairingGrant, createProcessLogSink, createSandboxDockerPort, createSurfaceHttpServer, drainProcessOutput, loadOrCreateCredentials, promoteSandboxImage, redeemPairingGrant, replaceAccessKey, runDoctor, runSandbox, runSandboxEntrypoint, runSandboxSetup, runSelfUpdateLatestLoop, runTargetSmoke, verifyResidentStart, waitForActiveRuns, waitForever, } from '../surfaces/index.js';
+import { DockerProcessError, createApiDispatcher, createLoggedDockerCli, createPackagedAssetSource, createPairingGrant, createProcessLogSink, createSandboxDockerPort, createSurfaceHttpServer, describeSandboxStartupFailure, drainProcessOutput, loadOrCreateCredentials, promoteSandboxImage, redeemPairingGrant, replaceAccessKey, runDoctor, runSandbox, runSandboxEntrypoint, runSandboxSetup, runSelfUpdateLatestLoop, runTargetSmoke, verifyResidentStart, waitForActiveRuns, waitForever, } from '../surfaces/index.js';
 import { WorkStreamKind, workItemId } from '../work/index.js';
 import { loadConfig } from './config/load-config.js';
 import { createNpmUpdatePort } from './npm-update-port.js';
@@ -427,7 +427,12 @@ async function deploySandboxTag(root, docker, tag, image, overrides) {
         : sandboxWakeInvocation(root);
     const healthcheckRoot = `/tmp/wake-self-update-healthcheck-${tag}`;
     await port.build();
-    await port.update();
+    try {
+        await port.update();
+    }
+    catch (error) {
+        throw await describeSandboxStartupFailure(docker, root.config.host.sandbox.containerName, error);
+    }
     await verifyResidentStart(docker, root.config.host.sandbox.containerName, [...wakeInvocation, 'start', '--wake-root', '/wake'].join(' '));
     await port.exec([...wakeInvocation, 'init', healthcheckRoot]);
     await port.exec([...wakeInvocation, 'tick', '--wake-root', healthcheckRoot, '--no-sandbox']);
@@ -456,6 +461,16 @@ function createOperationalApplications(root) {
                 },
             },
         }),
+        maintenance: async (arguments_) => {
+            const command = withoutOperationalWakeRoot(arguments_);
+            if (command.length !== 2 || command[0] !== 'clear' || command[1] !== '--failed')
+                throw new Error('wake maintenance clear requires --failed');
+            const lease = await root.maintenance.read();
+            if (lease === null)
+                return { cleared: false };
+            await root.maintenance.clearFailed(lease.attemptId);
+            return { cleared: true, tag: lease.tag };
+        },
         sandboxSetup: async (arguments_) => {
             if (arguments_.length > 0)
                 throw new Error('wake sandbox-setup accepts no arguments');
@@ -766,6 +781,19 @@ function selfUpdateLoopInterval(arguments_) {
         throw new Error('wake self-update --loop-interval-ms must be a positive integer');
     return interval;
 }
+function withoutOperationalWakeRoot(arguments_) {
+    const result = [];
+    for (let index = 0; index < arguments_.length; index += 1) {
+        if (arguments_[index] !== '--wake-root') {
+            result.push(arguments_[index]);
+            continue;
+        }
+        if (arguments_[index + 1] === undefined)
+            throw new Error('wake maintenance requires --wake-root <path>');
+        index += 1;
+    }
+    return result;
+}
 function delay(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }

package/dist/src/bootstrap/update-maintenance-lease.d.ts

@@ -20,5 +20,6 @@ export interface UpdateMaintenanceLease {
     transition(phase: Exclude<UpdateMaintenancePhase, typeof UpdateMaintenancePhase.Failed>, attemptId?: string): Promise<UpdateMaintenanceState>;
     fail(error: unknown, attemptId?: string): Promise<UpdateMaintenanceState>;
     clear(attemptId?: string): Promise<void>;
+    clearFailed(attemptId: string): Promise<void>;
 }
 export declare function createUpdateMaintenanceLease(wakeRoot: string, now?: () => string, createAttemptId?: () => string, isProcessAlive?: (pid: number) => boolean): UpdateMaintenanceLease;

package/dist/src/bootstrap/update-maintenance-lease.js

@@ -72,6 +72,15 @@ export function createUpdateMaintenanceLease(wakeRoot, now = () => new Date().to
                 await rm(path, { force: true });
             });
         },
+        async clearFailed(attemptId) {
+            await withLeaseLock(path, async () => {
+                const current = await requireState(path);
+                requireOwnership(current, attemptId);
+                if (current.phase !== UpdateMaintenancePhase.Failed)
+                    throw new Error('Only a failed maintenance lease can be cleared by an operator');
+                await rm(path, { force: true });
+            });
+        },
     };
 }
 function requireOwnership(state, attemptId) {

package/dist/src/bootstrap/version.js

@@ -124,6 +124,6 @@ export function resolveWakeVersion(options = {}) {
         return `g${headHash.slice(0, 7)}`;
     return '0.1.0-dev';
 }
-export const wakeVersion = "v0.4.32";
+export const wakeVersion = "v0.4.33";
 /** The registry-installable version used by packaged sandbox images. */
 export const wakePackageVersion = packageVersion(defaultRepoRoot) ?? wakeVersion;

package/dist/src/surfaces/api/contracts/control-plane.d.ts

@@ -11,6 +11,7 @@ export interface ControlPlaneStatusResponse {
      * lease exists, including a failed one -- see update-maintenance-lease.ts.
      */
     readonly maintenanceLease?: {
+        readonly attemptId: string;
         readonly phase: string;
         readonly startedAt: string;
         readonly failure?: string;

package/dist/src/surfaces/api/routes/applications.d.ts

@@ -20,6 +20,9 @@ export type ApiResourceResult<T> = ResourceResponse<T>;
 export interface ApiCommandRequest {
     readonly idempotencyKey: string;
 }
+export interface ApiClearMaintenanceRequest extends ApiCommandRequest {
+    readonly attemptId: string;
+}
 export type ApiRunResolutionRequest = (ApiCommandRequest & {
     readonly status: typeof RunStatus.Succeeded;
     readonly outcome: unknown;
@@ -46,6 +49,7 @@ export interface ApiApplications {
         status(): Promise<ApiResourceResult<ControlPlaneStatusResponse>>;
         pause?(command: ApiCommandRequest): Promise<ApiCommandResult>;
         resume?(command: ApiCommandRequest): Promise<ApiCommandResult>;
+        clearMaintenance?(command: ApiClearMaintenanceRequest): Promise<ApiCommandResult>;
     };
     readonly work: {
         list(query: CollectionQuery): Promise<ApiCollectionPage<WorkItemResponse>>;

package/dist/src/surfaces/api/routes/commands.js

@@ -10,6 +10,9 @@ export async function dispatchCommand(applications, url, body) {
     const work = await dispatchWorkCommand(applications, url.pathname, body);
     if (work !== undefined)
         return work;
+    const maintenance = await dispatchMaintenanceClear(applications, url.pathname, body);
+    if (maintenance !== undefined)
+        return maintenance;
     const request = commandRequest(body);
     if (isHttpResponse(request))
         return request;
@@ -78,6 +81,8 @@ async function dispatchControlCommand(applications, pathname, request) {
     const name = controlCommandName(pathname);
     if (name === undefined)
         return undefined;
+    if (name === 'clear-maintenance')
+        return undefined;
     const status = await applications.controlPlane.status();
     const operation = applications.controlPlane[name];
     return operation === undefined
@@ -89,7 +94,33 @@ function controlCommandName(pathname) {
     if (!pathname.startsWith(prefix))
         return undefined;
     const name = pathname.slice(prefix.length);
-    return name === 'pause' || name === 'resume' ? name : undefined;
+    return name === 'pause' || name === 'resume' || name === 'clear-maintenance' ? name : undefined;
+}
+async function dispatchMaintenanceClear(applications, pathname, body) {
+    if (pathname !== '/api/v1/control-plane/commands/clear-maintenance')
+        return undefined;
+    const request = clearMaintenanceRequest(body);
+    if (isHttpResponse(request))
+        return request;
+    const operation = applications.controlPlane.clearMaintenance;
+    const status = await applications.controlPlane.status();
+    return operation === undefined
+        ? unavailable('clear-maintenance', status.data)
+        : accepted(await operation(request), applications.now());
+}
+function clearMaintenanceRequest(body) {
+    if (!isObject(body))
+        return invalidRequest('idempotencyKey', 'A JSON object with an idempotency key is required');
+    if (Object.keys(body).some((key) => key !== 'idempotencyKey' && key !== 'attemptId'))
+        return invalidRequest('', 'The command body contains unknown fields');
+    const command = commandRequest({ idempotencyKey: body.idempotencyKey });
+    if (isHttpResponse(command))
+        return command;
+    if (typeof body.attemptId !== 'string' || body.attemptId.trim() === '')
+        return invalidRequest('attemptId', 'Must be a non-empty string');
+    if (body.attemptId.length > 200)
+        return invalidRequest('attemptId', 'Must be at most 200 characters');
+    return { ...command, attemptId: body.attemptId };
 }
 async function dispatchRunnerCommand(applications, pathname, request) {
     const match = /^\/api\/v1\/runners\/([^/]+)\/commands\/(pause|unpause)$/.exec(pathname);

package/dist/src/surfaces/api/routes/control-plane.d.ts

@@ -1 +1 @@
-export declare const controlPlaneRoutes: readonly ["/api/v1/control-plane/status", "/api/v1/control-plane/commands/pause", "/api/v1/control-plane/commands/resume"];
+export declare const controlPlaneRoutes: readonly ["/api/v1/control-plane/status", "/api/v1/control-plane/commands/pause", "/api/v1/control-plane/commands/resume", "/api/v1/control-plane/commands/clear-maintenance"];

package/dist/src/surfaces/api/routes/control-plane.js

@@ -2,4 +2,5 @@ export const controlPlaneRoutes = [
     '/api/v1/control-plane/status',
     '/api/v1/control-plane/commands/pause',
     '/api/v1/control-plane/commands/resume',
+    '/api/v1/control-plane/commands/clear-maintenance',
 ];

package/dist/src/surfaces/api/routes/index.d.ts

@@ -1,4 +1,4 @@
 import type { ApiDispatcher } from '../http-server.js';
 import type { ApiApplications } from './applications.js';
-export type { ApiApplications, ApiCollectionPage, ApiCommandRequest, ApiResourceResult, ApiRunResolutionRequest, ApiSystemApplications, CollectionQuery, } from './applications.js';
+export type { ApiApplications, ApiClearMaintenanceRequest, ApiCollectionPage, ApiCommandRequest, ApiResourceResult, ApiRunResolutionRequest, ApiSystemApplications, CollectionQuery, } from './applications.js';
 export declare function createApiDispatcher(applications: ApiApplications): ApiDispatcher;

package/dist/src/surfaces/cli/infrastructure/sandbox-startup-failure.d.ts

@@ -0,0 +1,7 @@
+import { type DockerCli } from './docker-cli.js';
+/**
+ * Adds the short-lived replacement container's logs to a rollout failure
+ * before rollback removes that container. Docker otherwise reports only the
+ * follow-on `exec` failure, which hides the actual entrypoint error.
+ */
+export declare function describeSandboxStartupFailure(docker: DockerCli, containerName: string, error: unknown): Promise<Error>;

package/dist/src/surfaces/cli/infrastructure/sandbox-startup-failure.js

@@ -0,0 +1,33 @@
+import { DockerProcessError } from './docker-cli.js';
+import { scrubProcessLog } from './process-log.js';
+/**
+ * Adds the short-lived replacement container's logs to a rollout failure
+ * before rollback removes that container. Docker otherwise reports only the
+ * follow-on `exec` failure, which hides the actual entrypoint error.
+ */
+export async function describeSandboxStartupFailure(docker, containerName, error) {
+    const failure = formatDockerError(error);
+    try {
+        const output = await docker.invoke(['logs', '--tail', '100', containerName], {
+            suppressOutput: true,
+        });
+        const logs = scrubProcessLog(`${output.stdout}${output.stderr}`).trim();
+        if (logs.length > 0)
+            return new Error(`Sandbox replacement "${containerName}" failed during startup: ${failure}\n` +
+                `Container logs:\n${logs}`, { cause: error });
+    }
+    catch (logsError) {
+        return new Error(`Sandbox replacement "${containerName}" failed during startup: ${failure}. ` +
+            `Could not collect its logs: ${formatDockerError(logsError)}`, { cause: error });
+    }
+    return new Error(`Sandbox replacement "${containerName}" failed during startup: ${failure}`, {
+        cause: error,
+    });
+}
+function formatDockerError(error) {
+    if (error instanceof DockerProcessError) {
+        const output = `${error.result.stdout}${error.result.stderr}`.trim();
+        return output.length === 0 ? error.message : `${error.message}: ${scrubProcessLog(output)}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/surfaces/cli/main.d.ts

@@ -5,6 +5,9 @@ export interface HostOptions {
     readonly port?: number;
     readonly wakeRoot?: string;
 }
+export declare const WakeOperationalCommand: {
+    readonly Maintenance: "maintenance";
+};
 export type WakeCommand = ({
     readonly kind: 'tick' | 'start' | 'stop';
 } & {
@@ -37,7 +40,7 @@ export type WakeCommand = ({
     readonly rebuildProjections: boolean;
     readonly wakeRoot?: string;
 } | {
-    readonly kind: 'init' | 'doctor' | 'sandbox-setup' | 'sandbox-entrypoint' | 'self-update' | 'smoke';
+    readonly kind: 'init' | 'doctor' | typeof WakeOperationalCommand.Maintenance | 'sandbox-setup' | 'sandbox-entrypoint' | 'self-update' | 'smoke';
     readonly arguments: readonly string[];
 } | {
     readonly kind: 'sandbox';
@@ -59,6 +62,7 @@ export interface WakeCliApplications {
     readonly operational?: {
         readonly init: (arguments_: readonly string[]) => Promise<unknown>;
         readonly doctor: (arguments_: readonly string[]) => Promise<unknown>;
+        readonly maintenance: (arguments_: readonly string[]) => Promise<unknown>;
         readonly sandbox: (arguments_: readonly string[]) => Promise<unknown>;
         readonly sandboxSetup: (arguments_: readonly string[]) => Promise<unknown>;
         readonly sandboxEntrypoint: (arguments_: readonly string[]) => Promise<unknown>;

package/dist/src/surfaces/cli/main.js

@@ -1,6 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import qrcodeTerminal from 'qrcode-terminal';
 import { ExecutionStreamKind, RunStatus } from '../../execution/index.js';
+import { defineClosedVocabulary } from '../../kernel/index.js';
+export const WakeOperationalCommand = defineClosedVocabulary({
+    Maintenance: 'maintenance',
+});
 const defaultBudget = { maxAdvances: 100, maxRuns: 100, maxDurationMs: 30_000 };
 /** Parses Surface vocabulary only; Bootstrap supplies every application facade. */
 // eslint-disable-next-line complexity -- command vocabulary is intentionally exhaustive at the Surface boundary.
@@ -29,6 +33,7 @@ export function parseWakeCommand(arguments_) {
             return parseResidentCommand(command, arguments_.slice(1));
         case 'init':
         case 'doctor':
+        case WakeOperationalCommand.Maintenance:
         case 'sandbox-setup':
         case 'sandbox-entrypoint':
         case 'sandbox':
@@ -153,6 +158,9 @@ export async function runWakeCommand(command, applications, output, signal) {
         case 'doctor':
             writeResult(output, await operational(applications).doctor(command.arguments));
             return;
+        case WakeOperationalCommand.Maintenance:
+            writeResult(output, await operational(applications).maintenance(command.arguments));
+            return;
         case 'sandbox':
             writeResult(output, await operational(applications).sandbox(command.arguments));
             return;

package/dist/src/surfaces/cli/usage.js

@@ -16,6 +16,7 @@ export const usage = [
     '  wake correlate             Manually correlate a resource to a work item',
     '  wake run resolve           Resolve an escalated ambiguous run',
     '  wake doctor                Diagnose config/GitHub/Docker/sandbox setup problems',
+    '  wake maintenance clear     Clear an abandoned failed self-update maintenance lease',
     '  wake --version             Print the installed Wake version',
     '  wake --help                Show this message',
     '',
@@ -25,6 +26,7 @@ export const usage = [
     '  wake api                   Run the target API surface',
     '  wake sandbox-entrypoint    Run the sandbox resident entrypoint',
     '  wake self-update           Safely update Wake from npm or a source checkout',
+    '  wake maintenance clear --failed',
     '',
     'Getting started:',
     '  1. wake init ./wake-home',

package/dist/src/surfaces/index.d.ts

@@ -42,6 +42,7 @@ export * from './cli/commands/ui.js';
 export * from './cli/commands/validate-state.js';
 export * from './cli/infrastructure/docker-cli.js';
 export * from './cli/infrastructure/process-log.js';
+export * from './cli/infrastructure/sandbox-startup-failure.js';
 export * from './cli/main.js';
 export * from './cli/usage.js';
 export * from './contracts/config.js';

package/dist/src/surfaces/index.js

@@ -42,6 +42,7 @@ export * from './cli/commands/ui.js';
 export * from './cli/commands/validate-state.js';
 export * from './cli/infrastructure/docker-cli.js';
 export * from './cli/infrastructure/process-log.js';
+export * from './cli/infrastructure/sandbox-startup-failure.js';
 export * from './cli/main.js';
 export * from './cli/usage.js';
 export * from './contracts/config.js';