@atolis-hq/wake 0.2.31 → 0.2.33

package/dist/src/adapters/fs/resource-index.js

@@ -1,6 +1,11 @@
 import { createHash } from 'node:crypto';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
 import { acquireFileLock } from '../../lib/lock.js';
 import { readJsonFile, writeJsonFile } from '../../lib/json-file.js';
+import { isMissingPathError, stateHealthIssue, StateHealthError, } from '../../lib/state-health.js';
+const shardContentsSchema = z.record(z.string(), z.string());
 /**
  * Addresses a resource uri to one of 256 shards.
  *
@@ -15,11 +20,48 @@ export function shardFor(resourceUri) {
 }
 async function readShard(file) {
     try {
-        return await readJsonFile(file);
+        return shardContentsSchema.parse(await readJsonFile(file));
     }
-    catch {
-        return {};
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return {};
+        }
+        throw new StateHealthError([
+            stateHealthIssue({
+                surface: 'reverse-index',
+                kind: 'corrupted',
+                path: file,
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        ]);
+    }
+}
+export async function validateResourceIndex(paths) {
+    const issues = [];
+    const entries = await readdir(paths.resourceIndexRoot, { withFileTypes: true }).catch((error) => {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            continue;
+        }
+        const file = join(paths.resourceIndexRoot, entry.name);
+        try {
+            shardContentsSchema.parse(await readJsonFile(file));
+        }
+        catch (error) {
+            issues.push(stateHealthIssue({
+                surface: 'reverse-index',
+                kind: 'corrupted',
+                path: file,
+                message: error instanceof Error ? error.message : String(error),
+            }));
+        }
     }
+    return issues;
 }
 // acquireFileLock is a non-blocking try-lock: when contended it returns
 // { acquired: false } immediately rather than waiting. register/retract have

package/dist/src/adapters/fs/state-store.js

@@ -1,15 +1,27 @@
 import { access, appendFile, mkdir, readFile, readdir, rename } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { validateResourceIndex } from './resource-index.js';
 import { parseEventEnvelope, parseIssueStateRecord, parseLedger, parseRunRecord, parseSourceStateRecord, } from '../../domain/schema.js';
 import { isTerminalStage } from '../../domain/stages.js';
 import { appendJsonLine, readJsonFile, writeJsonFile } from '../../lib/json-file.js';
 import { createWakePaths } from '../../lib/paths.js';
+import { isMissingPathError, stateHealthIssue, StateHealthError, throwIfUnhealthy, } from '../../lib/state-health.js';
 async function readIssueStateFile(file) {
     try {
         return parseIssueStateRecord(await readJsonFile(file));
     }
-    catch {
-        return null;
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return null;
+        }
+        throw new StateHealthError([
+            stateHealthIssue({
+                surface: 'state',
+                kind: 'corrupted',
+                path: file,
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        ]);
     }
 }
 async function readRunRecordFile(file) {
@@ -24,24 +36,136 @@ async function readEventFile(file) {
     try {
         const raw = await readFile(file, 'utf8');
         const envelopes = [];
+        let lineNumber = 0;
         for (const line of raw.split('\n')) {
+            lineNumber += 1;
             const trimmed = line.trim();
             if (trimmed.length === 0) {
                 continue;
             }
-            const parsed = JSON.parse(trimmed);
-            if (parsed !== null &&
-                typeof parsed === 'object' &&
-                'eventId' in parsed &&
-                'sourceEventType' in parsed) {
+            try {
+                const parsed = JSON.parse(trimmed);
                 envelopes.push(parseEventEnvelope(parsed));
             }
+            catch (error) {
+                throw new StateHealthError([
+                    stateHealthIssue({
+                        surface: 'events',
+                        kind: 'corrupted',
+                        path: `${file}:${lineNumber}`,
+                        message: error instanceof Error ? error.message : String(error),
+                    }),
+                ]);
+            }
         }
         return envelopes;
     }
-    catch {
-        return [];
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+        if (error instanceof StateHealthError) {
+            throw error;
+        }
+        throw new StateHealthError([
+            stateHealthIssue({
+                surface: 'events',
+                kind: 'corrupted',
+                path: file,
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        ]);
+    }
+}
+async function collectIssueStateIssues(paths) {
+    const issues = [];
+    const visit = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true }).catch((error) => {
+            if (isMissingPathError(error)) {
+                return [];
+            }
+            throw error;
+        });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (entry.name === 'index') {
+                    continue;
+                }
+                await visit(join(dir, entry.name));
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.json')) {
+                continue;
+            }
+            const file = join(dir, entry.name);
+            try {
+                parseIssueStateRecord(await readJsonFile(file));
+            }
+            catch (error) {
+                issues.push(stateHealthIssue({
+                    surface: 'state',
+                    kind: 'corrupted',
+                    path: file,
+                    message: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        }
+    };
+    await visit(join(paths.dataRoot, 'state'));
+    return issues;
+}
+async function collectEventIssues(paths) {
+    const issues = [];
+    const eventLogFiles = await readdir(join(paths.dataRoot, 'events'), {
+        withFileTypes: true,
+    }).catch((error) => {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of eventLogFiles) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl')) {
+            continue;
+        }
+        try {
+            await readEventFile(join(paths.dataRoot, 'events', entry.name));
+        }
+        catch (error) {
+            if (error instanceof StateHealthError) {
+                issues.push(...error.issues);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    const eventEnvelopeFiles = await readdir(join(paths.dataRoot, 'events-by-id'), {
+        withFileTypes: true,
+    }).catch((error) => {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of eventEnvelopeFiles) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            continue;
+        }
+        const file = join(paths.dataRoot, 'events-by-id', entry.name);
+        try {
+            parseEventEnvelope(await readJsonFile(file));
+        }
+        catch (error) {
+            issues.push(stateHealthIssue({
+                surface: 'events',
+                kind: 'corrupted',
+                path: file,
+                message: error instanceof Error ? error.message : String(error),
+            }));
+        }
     }
+    return issues;
 }
 function issueArchiveAgeDate(item) {
     const stageChangedAt = item.wake.stageHistory.at(-1)?.changedAt;
@@ -153,8 +277,11 @@ export function createStateStore({ wakeRoot }) {
             try {
                 return parseLedger(await readJsonFile(paths.ledgerFile));
             }
-            catch {
-                return null;
+            catch (error) {
+                if (isMissingPathError(error)) {
+                    return null;
+                }
+                throw error;
             }
         },
         async writeIssueState(record) {
@@ -206,8 +333,11 @@ export function createStateStore({ wakeRoot }) {
             try {
                 return parseSourceStateRecord(await readJsonFile(paths.sourceStateFile(source, key)));
             }
-            catch {
-                return null;
+            catch (error) {
+                if (isMissingPathError(error)) {
+                    return null;
+                }
+                throw error;
             }
         },
         async appendEventEnvelope(record) {
@@ -224,66 +354,75 @@ export function createStateStore({ wakeRoot }) {
             try {
                 return parseEventEnvelope(await readJsonFile(paths.eventEnvelopeFile(eventId)));
             }
-            catch {
-                return null;
+            catch (error) {
+                if (isMissingPathError(error)) {
+                    return null;
+                }
+                throw new StateHealthError([
+                    stateHealthIssue({
+                        surface: 'events',
+                        kind: 'corrupted',
+                        path: paths.eventEnvelopeFile(eventId),
+                        message: error instanceof Error ? error.message : String(error),
+                    }),
+                ]);
             }
         },
         async listIssueStates(options = {}) {
             const stateRoot = join(paths.dataRoot, 'state');
-            try {
-                const items = [];
-                const includeArchived = options.includeArchived ?? false;
-                const archiveOptions = options.archiveFreshnessDays === undefined
-                    ? null
-                    : {
-                        archiveFreshnessDays: options.archiveFreshnessDays,
-                        now: options.now ?? new Date(),
-                    };
-                // state/ is flat: state/<workId>.json, plus state/archive/ and the
-                // reverse index's own state/index/ shards. Only those two subdirectories
-                // exist, and index/ holds `{ resourceUri: workItemKey }` maps that are
-                // not projections at all — skip it rather than parse-and-discard.
-                const visit = async (dir, isArchive) => {
-                    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
-                    for (const entry of entries) {
-                        if (entry.isDirectory()) {
-                            if (entry.name === 'index') {
-                                continue;
-                            }
-                            if (entry.name === 'archive' && includeArchived) {
-                                await visit(join(dir, entry.name), true);
-                            }
-                            continue;
-                        }
-                        if (!entry.isFile() || !entry.name.endsWith('.json')) {
-                            continue;
-                        }
-                        const file = join(dir, entry.name);
-                        const record = await readIssueStateFile(file);
-                        if (record === null) {
+            const items = [];
+            const includeArchived = options.includeArchived ?? false;
+            const archiveOptions = options.archiveFreshnessDays === undefined
+                ? null
+                : {
+                    archiveFreshnessDays: options.archiveFreshnessDays,
+                    now: options.now ?? new Date(),
+                };
+            // state/ is flat: state/<workId>.json, plus state/archive/ and the
+            // reverse index's own state/index/ shards. Only those two subdirectories
+            // exist, and index/ holds `{ resourceUri: workItemKey }` maps that are
+            // not projections at all — skip it rather than parse-and-discard.
+            const visit = async (dir, isArchive) => {
+                const entries = await readdir(dir, { withFileTypes: true }).catch((error) => {
+                    if (isMissingPathError(error)) {
+                        return [];
+                    }
+                    throw error;
+                });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        if (entry.name === 'index') {
                             continue;
                         }
-                        if (archiveOptions !== null &&
-                            !isArchive &&
-                            shouldArchiveIssueState(record, archiveOptions)) {
-                            const archivePath = paths.archivedWorkItemStateFile(record.workItemKey);
-                            await mkdir(dirname(archivePath), { recursive: true });
-                            await rename(file, archivePath).catch(() => undefined);
-                            continue;
+                        if (entry.name === 'archive' && includeArchived) {
+                            await visit(join(dir, entry.name), true);
                         }
-                        items.push(record);
+                        continue;
                     }
-                };
-                await visit(stateRoot, false);
-                const byWorkItemKey = new Map();
-                for (const item of items) {
-                    byWorkItemKey.set(item.workItemKey, item);
+                    if (!entry.isFile() || !entry.name.endsWith('.json')) {
+                        continue;
+                    }
+                    const file = join(dir, entry.name);
+                    const record = await readIssueStateFile(file);
+                    if (record === null)
+                        continue;
+                    if (archiveOptions !== null &&
+                        !isArchive &&
+                        shouldArchiveIssueState(record, archiveOptions)) {
+                        const archivePath = paths.archivedWorkItemStateFile(record.workItemKey);
+                        await mkdir(dirname(archivePath), { recursive: true });
+                        await rename(file, archivePath).catch(() => undefined);
+                        continue;
+                    }
+                    items.push(record);
                 }
-                return [...byWorkItemKey.values()].sort((left, right) => left.workItemKey.localeCompare(right.workItemKey));
-            }
-            catch {
-                return [];
+            };
+            await visit(stateRoot, false);
+            const byWorkItemKey = new Map();
+            for (const item of items) {
+                byWorkItemKey.set(item.workItemKey, item);
             }
+            return [...byWorkItemKey.values()].sort((left, right) => left.workItemKey.localeCompare(right.workItemKey));
         },
         async listEventEnvelopes() {
             const eventsRoot = join(paths.dataRoot, 'events');
@@ -295,14 +434,22 @@ export function createStateStore({ wakeRoot }) {
                 }
                 return envelopes;
             }
-            catch {
-                return [];
+            catch (error) {
+                if (isMissingPathError(error)) {
+                    return [];
+                }
+                throw error;
             }
         },
         async listRecentEventEnvelopes(filter = {}) {
             const limit = filter.limit ?? 200;
             const eventsRoot = join(paths.dataRoot, 'events');
-            const files = (await readdir(eventsRoot).catch(() => []))
+            const files = (await readdir(eventsRoot).catch((error) => {
+                if (isMissingPathError(error)) {
+                    return [];
+                }
+                throw error;
+            }))
                 .filter((file) => file.endsWith('.jsonl'))
                 .sort()
                 .reverse();
@@ -360,5 +507,17 @@ export function createStateStore({ wakeRoot }) {
         async readEventLog(date) {
             return readFile(paths.eventFile(date), 'utf8');
         },
+        async validateStateHealth() {
+            const issues = [
+                ...(await collectEventIssues(paths)),
+                ...(await collectIssueStateIssues(paths)),
+                ...(await validateResourceIndex(paths)),
+            ];
+            return { healthy: issues.length === 0, issues };
+        },
+        async assertStateHealthy() {
+            const report = await this.validateStateHealth();
+            throwIfUnhealthy(report.issues);
+        },
     };
 }

package/dist/src/adapters/github/github-client.js

@@ -66,6 +66,14 @@ export function createGitHubClient(token) {
                 }),
             });
         },
+        async getIssue(owner, repo, issueNumber) {
+            const { data } = await octokit.rest.issues.get({
+                owner,
+                repo,
+                issue_number: issueNumber,
+            });
+            return data;
+        },
         async createComment(owner, repo, issueNumber, body) {
             return octokit.rest.issues.createComment({
                 owner,

package/dist/src/adapters/github/github-issues-work-source.js

@@ -185,6 +185,9 @@ export async function readControlPlaneUiUrl(wakeRoot) {
         return undefined;
     }
 }
+function isGitHubNotFound(error) {
+    return error instanceof Error && error.status === 404;
+}
 export function formatGitHubError(error) {
     if (error instanceof Error) {
         const octokit = error;
@@ -301,6 +304,71 @@ export function createGitHubIssuesWorkSource(deps) {
         return deps.stateStore.readIssueState(workItemKey);
     }
     return {
+        async refreshForDispatch(input) {
+            const repoRef = input.projection.issue.repo;
+            if (deps.client.getIssue === undefined) {
+                return null;
+            }
+            if (!deps.config.sources.github.repos.includes(repoRef)) {
+                return null;
+            }
+            const [owner, repo] = repoRef.split('/');
+            if (owner === undefined || repo === undefined) {
+                return null;
+            }
+            const ingestedAt = deps.now().toISOString();
+            let issue;
+            try {
+                issue = await deps.client.getIssue(owner, repo, input.projection.issue.number);
+            }
+            catch (error) {
+                if (isGitHubNotFound(error)) {
+                    return {
+                        events: [],
+                        sourceRevision: `github:issue:${repoRef}#${input.projection.issue.number}@missing`,
+                        sourceExists: false,
+                    };
+                }
+                throw error;
+            }
+            const events = [];
+            if (input.projection.issue.updatedAt !== issue.updated_at) {
+                events.push(normalizeTicketUpsert({
+                    repo: repoRef,
+                    issue,
+                    ingestedAt,
+                    expectedEcho: isExpectedLabelEcho(issue, input.projection),
+                }));
+            }
+            const comments = await deps.client.listComments(owner, repo, input.projection.issue.number, deps.config.sources.github.polling.commentPageSize);
+            let latestCommentRevision = '';
+            for (const comment of comments) {
+                if (comment.updated_at > latestCommentRevision) {
+                    latestCommentRevision = comment.updated_at;
+                }
+                const known = input.projection.comments.find((entry) => entry.id === String(comment.id));
+                if (known?.updatedAt === comment.updated_at) {
+                    continue;
+                }
+                if (input.projection.wake.expectedEcho.commentIds.includes(String(comment.id))) {
+                    continue;
+                }
+                events.push(normalizeTicketCommentEvent({
+                    repo: repoRef,
+                    issueNumber: input.projection.issue.number,
+                    comment,
+                    ingestedAt,
+                    ...(deps.selfLogin === undefined ? {} : { selfLogin: deps.selfLogin }),
+                    ...(known?.updatedAt === undefined ? {} : { existingUpdatedAt: known.updatedAt }),
+                }));
+            }
+            return {
+                events,
+                sourceRevision: latestCommentRevision.length > 0
+                    ? `github:issue:${repoRef}#${issue.number}@${issue.updated_at};comments@${latestCommentRevision}`
+                    : `github:issue:${repoRef}#${issue.number}@${issue.updated_at}`,
+            };
+        },
         async pollEvents(_input) {
             const ingestedAt = deps.now().toISOString();
             const events = [];

package/dist/src/core/sink-router.js

@@ -4,6 +4,18 @@ export function createWorkSourceFanIn(sources) {
             const batches = await Promise.all(sources.map((source) => source.pollEvents(input)));
             return batches.flat();
         },
+        async refreshForDispatch(input) {
+            for (const source of sources) {
+                if (source.refreshForDispatch === undefined) {
+                    continue;
+                }
+                const result = await source.refreshForDispatch(input);
+                if (result !== null) {
+                    return result;
+                }
+            }
+            return null;
+        },
     };
 }
 function intentKind(event) {

package/dist/src/core/tick-runner.js

@@ -21,6 +21,15 @@ function latestHumanCommentId(candidate) {
     const human = candidate.comments.filter((c) => !c.isBotAuthored);
     return human.at(-1)?.id;
 }
+function projectedSourceRevision(projection) {
+    const latestCommentUpdatedAt = projection.comments
+        .map((comment) => comment.updatedAt)
+        .sort()
+        .at(-1);
+    return latestCommentUpdatedAt === undefined
+        ? `${projection.issue.repo}#${projection.issue.number}@${projection.issue.updatedAt}`
+        : `${projection.issue.repo}#${projection.issue.number}@${projection.issue.updatedAt};comments@${latestCommentUpdatedAt}`;
+}
 function isLateralReadOnlyAction(action, config) {
     return isCustomCommandAction(action, config);
 }
@@ -221,6 +230,18 @@ export function createTickRunner(deps) {
                 processStartedAt: record.workerProcessStartedAt,
             }));
     }
+    async function hasSchedulerCapacity(now) {
+        const runRecords = await deps.stateStore.listRunRecords();
+        for (const record of runRecords) {
+            if (record.status !== 'running') {
+                continue;
+            }
+            if (await isRunningRecordActive(record, now)) {
+                return false;
+            }
+        }
+        return true;
+    }
     async function parkConfigDriftedProjections(projections) {
         let parked = false;
         for (const projection of projections) {
@@ -314,10 +335,31 @@ export function createTickRunner(deps) {
             if (await parkConfigDriftedProjections(projections)) {
                 return { status: 'processed' };
             }
-            const candidate = projections.find((issue) => policy.resolveNextEligibleAction(issue, deps.config) !== null);
+            let candidate = projections.find((issue) => policy.resolveNextEligibleAction(issue, deps.config) !== null);
             if (candidate === undefined) {
                 return { status: 'idle' };
             }
+            let sourceRevision = projectedSourceRevision(candidate);
+            let refresh;
+            try {
+                refresh = await deps.workSource.refreshForDispatch?.({ projection: candidate });
+            }
+            catch {
+                return { status: 'idle' };
+            }
+            if (refresh !== undefined && refresh !== null) {
+                if (refresh.sourceExists === false) {
+                    return { status: 'idle' };
+                }
+                sourceRevision = refresh.sourceRevision;
+                if (refresh.events.length > 0) {
+                    await ingestInboundEvents(refresh.events);
+                    candidate = (await deps.stateStore.readIssueState(candidate.workItemKey)) ?? candidate;
+                }
+            }
+            if (policy.resolveNextEligibleAction(candidate, deps.config) === null) {
+                return { status: 'idle' };
+            }
             const workflow = workflowForProjection(candidate, deps.config);
             if (workflow === null) {
                 return { status: 'idle' };
@@ -444,6 +486,9 @@ export function createTickRunner(deps) {
             if (routing === null) {
                 return { status: 'idle' };
             }
+            if (!(await hasSchedulerCapacity(deps.clock.now()))) {
+                return { status: 'idle' };
+            }
             const runId = `run-${candidate.issue.number}-${deps.clock.now().getTime()}`;
             const lease = createRunLease({ clock: deps.clock, ownerInstanceId });
             const workerIdentity = currentProcessIdentity();
@@ -461,6 +506,9 @@ export function createTickRunner(deps) {
                 lease,
                 workerPid: workerIdentity.pid,
                 workerProcessStartedAt: workerIdentity.processStartedAt,
+                metadata: {
+                    sourceRevision,
+                },
             };
             await deps.stateStore.writeRunRecord(runningRecord);
             async function transitionRunLifecycle(lifecycle) {
@@ -489,6 +537,7 @@ export function createTickRunner(deps) {
                     action,
                     priorStage: candidate.wake.stage,
                     claimedStage,
+                    sourceRevision,
                 },
             });
             await deps.stateStore.appendEventEnvelope(claimedEvent);
@@ -768,6 +817,7 @@ export function createTickRunner(deps) {
                     executionOutcome: 'PROCESS_FAILED',
                     summary: err instanceof Error ? err.message : String(err),
                     metadata: {
+                        ...failedRecord.metadata,
                         failureClass: 'infra',
                     },
                 });
@@ -857,6 +907,7 @@ export function createTickRunner(deps) {
         runIntakeTick,
         runRunnerTick,
         async runTick() {
+            await deps.stateStore.assertStateHealthy();
             const intakeResult = await runIntakeTick();
             if (intakeResult.status === 'locked') {
                 return intakeResult;

package/dist/src/lib/state-health.js

@@ -0,0 +1,30 @@
+export class StateHealthError extends Error {
+    issues;
+    constructor(issues) {
+        super(formatStateHealthErrorMessage(issues));
+        this.name = 'StateHealthError';
+        this.issues = issues;
+    }
+}
+export function isNodeErrnoException(error) {
+    return error instanceof Error && 'code' in error;
+}
+export function isMissingPathError(error) {
+    return isNodeErrnoException(error) && error.code === 'ENOENT';
+}
+export function stateHealthIssue(input) {
+    return input;
+}
+export function throwIfUnhealthy(issues) {
+    if (issues.length > 0) {
+        throw new StateHealthError(issues);
+    }
+}
+export function formatStateHealthErrorMessage(issues) {
+    if (issues.length === 0) {
+        return 'Wake control-plane state is healthy';
+    }
+    const first = issues[0];
+    const suffix = issues.length === 1 ? '' : ` and ${issues.length - 1} more issue(s)`;
+    return `Wake control-plane state is unhealthy: ${first.surface} ${first.kind} at ${first.path}: ${first.message}${suffix}`;
+}

package/dist/src/main.js

@@ -36,6 +36,7 @@ import { systemClock } from './lib/clock.js';
 import { createDetachedProcessLogSink } from './lib/detached-process-logging.js';
 import { readJsonFile } from './lib/json-file.js';
 import { resolveLogMaxBytes, resolveLogRotateCheckIntervalMs } from './lib/log-rotation.js';
+import { StateHealthError } from './lib/state-health.js';
 import { configuredTicketSource } from './domain/sources.js';
 import { wakeVersion } from './version.js';
 function commandArgsBeforeTerminator(args) {
@@ -578,6 +579,7 @@ export async function buildRuntime(args) {
 }
 async function runTick(args) {
     const runtime = await buildRuntime(args);
+    await runtime.stateStore.assertStateHealthy();
     const outcome = await runtime.tickRunner.runTick();
     console.log(JSON.stringify(outcome, null, 2));
     if (outcome.status !== 'processed' ||
@@ -593,6 +595,7 @@ async function runTick(args) {
 }
 async function runStart(args) {
     const runtime = await buildRuntime(args);
+    await runtime.stateStore.assertStateHealthy();
     const runnerOverride = readFlagBeforeCommandTerminator('--runner', args);
     await runStartupPreflight(runtime.config, {
         ...(runnerOverride === undefined ? {} : { runnerOverride }),
@@ -625,6 +628,26 @@ async function runStart(args) {
     process.on('SIGTERM', stop);
     await controlPlane.start();
 }
+function printStateHealthReport(report) {
+    if (report.healthy) {
+        console.log('wake validate-state: control-plane state is healthy');
+        return;
+    }
+    console.error('wake validate-state: control-plane state is unhealthy');
+    for (const issue of report.issues) {
+        console.error(`  - ${issue.surface} ${issue.kind}: ${issue.path}: ${issue.message}`);
+    }
+}
+async function runValidateState(args) {
+    const wakeRoot = resolve(readFlagBeforeCommandTerminator('--wake-root', args) ?? process.cwd());
+    const stateStore = createStateStore({ wakeRoot });
+    await stateStore.ensureWakeRoot();
+    const report = await stateStore.validateStateHealth();
+    printStateHealthReport(report);
+    if (!report.healthy) {
+        process.exitCode = 1;
+    }
+}
 function resolveSmokEntry(config, kind) {
     for (const entry of Object.values(config.runners)) {
         if (entry.kind === 'fake') {
@@ -747,6 +770,7 @@ export function printUsage(stream) {
         '  wake sandbox <subcommand>  Build/run/manage the Docker sandbox (build, up, update, down, stop, self-update, setup, exec, logs, resume)',
         '  wake tick                  Run one control-plane tick',
         '  wake start                 Run the resident loop',
+        '  wake validate-state        Validate .wake/ control-plane state health',
         '  wake stop                  Stop the sandbox container gracefully',
         '  wake smoke                 Smoke-test the configured runner',
         '  wake ui                    Run the control-plane UI server',
@@ -759,14 +783,14 @@ export function printUsage(stream) {
         '  1. wake init ./wake-home',
         '  2. cd wake-home && wake start',
         '',
-        'Runtime commands (tick/start/ui/smoke/correlate) auto-delegate into the sandbox',
+        'Runtime commands (tick/start/ui/smoke/correlate/validate-state) auto-delegate into the sandbox',
         'when docker/Dockerfile exists at --wake-root (i.e. after `wake sandbox build`),',
         'defaulting --wake-root to the current directory. Pass --no-sandbox to run',
         'directly on the host instead.',
         '',
     ].join('\n'));
 }
-const runtimeCommands = new Set(['tick', 'start', 'ui', 'smoke', 'correlate']);
+const runtimeCommands = new Set(['tick', 'start', 'ui', 'smoke', 'correlate', 'validate-state']);
 export async function dispatchMainCommand(input) {
     const command = input.args[0] ?? 'help';
     if (command === '--version' || command === '-v') {
@@ -825,9 +849,15 @@ export async function dispatchMainCommand(input) {
         else if (command === 'smoke') {
             await input.runSmoke(hostArgs);
         }
-        else {
+        else if (command === 'correlate') {
             await input.runCorrelate(hostArgs);
         }
+        else {
+            if (input.runValidateState === undefined) {
+                throw new CliUsageError('validate-state command is not available in this runtime');
+            }
+            await input.runValidateState(hostArgs);
+        }
         return;
     }
     printUsage(process.stderr);
@@ -953,6 +983,7 @@ async function main() {
         runSmoke,
         runUi,
         runCorrelate,
+        runValidateState,
         execIntoSandbox: async (commandArgs) => {
             const withoutBypassFlag = commandArgs.filter((arg) => arg !== '--no-sandbox');
             const wakeRootIndex = withoutBypassFlag.indexOf('--wake-root');
@@ -975,6 +1006,13 @@ main().catch((error) => {
     if (error instanceof CliUsageError) {
         console.error(error.message);
     }
+    else if (error instanceof StateHealthError) {
+        console.error(error.message);
+        for (const issue of error.issues) {
+            console.error(`  - ${issue.surface} ${issue.kind}: ${issue.path}: ${issue.message}`);
+        }
+        process.exitCode = 1;
+    }
     else {
         console.error(error);
     }

package/dist/src/version.js

@@ -124,4 +124,4 @@ export function resolveWakeVersion(options = {}) {
     }
     return '0.1.0-dev';
 }
-export const wakeVersion = "g18ca5a7";
+export const wakeVersion = "g03d77d6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolis-hq/wake",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Local autonomous agent control plane for software development",
   "license": "Apache-2.0",
   "repository": {