@a1hvdy/cc-openclaw 0.11.0 → 0.12.0

package/dist/src/lib/stale-pid-files.js

@@ -0,0 +1,40 @@
+/**
+ * Stale PID-keyed file cleanup — for status/sentinel files named `<pid>.json`
+ * in a tee directory, removes entries whose PID is no longer alive.
+ *
+ * Extracted from `live-card.ts` 2026-05-14. Pure-function utility with a
+ * dir-parameter shape so future callers (other PID-keyed sentinel patterns)
+ * can reuse without duplicating the kill(pid, 0) liveness probe.
+ *
+ * The original file-extension was `.json`; expose it as a parameter so this
+ * is forward-compatible with `.sock`, `.lock`, etc.
+ */
+import { readdirSync, unlinkSync } from 'node:fs';
+/**
+ * Remove `<pid><ext>` files in `dir` whose PID no longer exists.
+ * Silent on missing directory. Per-file errors are swallowed — this is
+ * best-effort cleanup, not a correctness guarantee.
+ */
+export function cleanStalePidFiles(dir, ext = '.json') {
+    try {
+        const files = readdirSync(dir);
+        for (const file of files) {
+            if (!file.endsWith(ext))
+                continue;
+            const pid = parseInt(file.replace(ext, ''), 10);
+            if (isNaN(pid))
+                continue;
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                try {
+                    unlinkSync(`${dir}/${file}`);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch { /* directory doesn't exist — nothing to clean */ }
+}
+//# sourceMappingURL=stale-pid-files.js.map

package/dist/src/lib/stale-pid-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-pid-files.js","sourceRoot":"","sources":["../../../src/lib/stale-pid-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,MAAc,OAAO;IACnE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YAChD,IAAI,KAAK,CAAC,GAAG,CAAC;gBAAE,SAAS;YACzB,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC;oBAAC,UAAU,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,gDAAgD,CAAC,CAAC;AAC9D,CAAC"}

package/dist/src/lifecycle/boot.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Boot — 7-phase lifecycle orchestrator.
+ *
+ * Phase order (PRP §3.2 G6):
+ *   1. validate-config      → ConfigSchema.parse(env + openclaw.json)
+ *   2. import-upstream      → dynamic import("openclaw")
+ *   3. validate-upstream    → PatchManifest.validate() — ALL probes; fail-loud
+ *   4. install-patches      → PatchManifest.install() — atomic after probes pass
+ *   5. wire-handlers        → EventBus subscribers wired BEFORE traffic
+ *   6. start-server         → openai-compat HTTP listener up
+ *   7. schedule-jobs        → registry snapshot + watchdog timers
+ *      → ready              → emit "boot.ready" event
+ *
+ * Every phase fails loud — no silent skip.
+ * <300 LOC target; dependencies injected to allow dry-running phases 1-3
+ * from `cc-openclaw doctor`.
+ */
+import { type Config } from '../config/schema.js';
+import { type StartServerOptions } from './phase-start-server.js';
+import { PatchManifest } from './patch-manifest.js';
+import { EventBus } from '../observability/event-bus.js';
+import { SessionRegistry } from '../persistence/session-registry.js';
+export type BootPhase = 'validate-config' | 'import-upstream' | 'validate-upstream' | 'install-patches' | 'wire-handlers' | 'start-server' | 'schedule-jobs' | 'ready';
+export interface BootOptions {
+    manifest?: PatchManifest;
+    bus?: EventBus;
+    registry?: SessionRegistry;
+    serverOptions?: StartServerOptions;
+    /**
+     * When true, stops after phase 3 (validate-upstream) without installing
+     * patches or starting the server. Used by `cc-openclaw doctor`.
+     */
+    dryRun?: boolean;
+}
+export declare class Boot {
+    private readonly manifest;
+    private readonly bus;
+    private readonly registry;
+    private readonly serverOptions;
+    private readonly dryRun;
+    constructor(opts?: BootOptions);
+    /**
+     * Run all 7 phases (or phases 1-3 in dry-run mode).
+     * Throws BootPhaseError wrapping the underlying error with a phase key.
+     */
+    run(): Promise<Config>;
+    private runPhase;
+}
+export declare class BootPhaseError extends Error {
+    readonly phase: BootPhase;
+    readonly cause: Error;
+    constructor(phase: BootPhase, cause: Error);
+    /** True when the underlying error is a DriftError (phase 3 failure). */
+    get isDrift(): boolean;
+    /** True when the underlying error is a ConfigInvalid (phase 1 failure). */
+    get isConfigInvalid(): boolean;
+    /** Remediation message suitable for `cc-openclaw doctor` output. */
+    remediation(): string;
+}

package/dist/src/lifecycle/boot.js

@@ -0,0 +1,132 @@
+/**
+ * Boot — 7-phase lifecycle orchestrator.
+ *
+ * Phase order (PRP §3.2 G6):
+ *   1. validate-config      → ConfigSchema.parse(env + openclaw.json)
+ *   2. import-upstream      → dynamic import("openclaw")
+ *   3. validate-upstream    → PatchManifest.validate() — ALL probes; fail-loud
+ *   4. install-patches      → PatchManifest.install() — atomic after probes pass
+ *   5. wire-handlers        → EventBus subscribers wired BEFORE traffic
+ *   6. start-server         → openai-compat HTTP listener up
+ *   7. schedule-jobs        → registry snapshot + watchdog timers
+ *      → ready              → emit "boot.ready" event
+ *
+ * Every phase fails loud — no silent skip.
+ * <300 LOC target; dependencies injected to allow dry-running phases 1-3
+ * from `cc-openclaw doctor`.
+ */
+import { DriftError, ConfigInvalid } from '../lib/domain-error.js';
+import { validateConfig } from './phase-validate-config.js';
+import { importUpstream } from './phase-import-upstream.js';
+import { validateUpstream } from './phase-validate-upstream.js';
+import { installPatches } from './phase-install-patches.js';
+import { wireHandlers } from './phase-wire-handlers.js';
+import { startServer } from './phase-start-server.js';
+import { scheduleJobs } from './phase-schedule-jobs.js';
+import { PatchManifest } from './patch-manifest.js';
+import { EventBus } from '../observability/event-bus.js';
+import { SessionRegistry } from '../persistence/session-registry.js';
+// ── Boot class ────────────────────────────────────────────────────────────────
+export class Boot {
+    manifest;
+    bus;
+    registry;
+    serverOptions;
+    dryRun;
+    constructor(opts = {}) {
+        this.manifest = opts.manifest ?? new PatchManifest();
+        this.bus = opts.bus ?? new EventBus();
+        this.registry = opts.registry ?? new SessionRegistry();
+        this.serverOptions = opts.serverOptions ?? {};
+        this.dryRun = opts.dryRun ?? false;
+    }
+    /**
+     * Run all 7 phases (or phases 1-3 in dry-run mode).
+     * Throws BootPhaseError wrapping the underlying error with a phase key.
+     */
+    async run() {
+        // Phase 1 — validate-config
+        const config = await this.runPhase('validate-config', () => {
+            return validateConfig();
+        });
+        // Phase 2 — import-upstream
+        const upstreamNs = await this.runPhase('import-upstream', () => importUpstream());
+        // Phase 3 — validate-upstream
+        await this.runPhase('validate-upstream', () => validateUpstream(this.manifest, upstreamNs));
+        if (this.dryRun) {
+            return config;
+        }
+        // Phase 4 — install-patches
+        await this.runPhase('install-patches', () => {
+            installPatches(this.manifest, upstreamNs);
+        });
+        // Phase 5 — wire-handlers (BEFORE traffic)
+        await this.runPhase('wire-handlers', () => {
+            wireHandlers(this.bus);
+        });
+        // Phase 6 — start-server
+        await this.runPhase('start-server', () => startServer(this.serverOptions));
+        // Phase 7 — schedule-jobs
+        await this.runPhase('schedule-jobs', () => {
+            scheduleJobs(this.registry);
+        });
+        // Ready
+        this.bus.emit('boot.ready', { config });
+        return config;
+    }
+    // ── Internal ────────────────────────────────────────────────────────────────
+    async runPhase(phase, fn) {
+        try {
+            return await Promise.resolve(fn());
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            const phaseError = new BootPhaseError(phase, error);
+            throw phaseError;
+        }
+    }
+}
+// ── BootPhaseError ────────────────────────────────────────────────────────────
+export class BootPhaseError extends Error {
+    phase;
+    cause;
+    constructor(phase, cause) {
+        super(`Boot failed at phase "${phase}": ${cause.message}`);
+        this.phase = phase;
+        this.cause = cause;
+        this.name = 'BootPhaseError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** True when the underlying error is a DriftError (phase 3 failure). */
+    get isDrift() {
+        return this.cause instanceof DriftError;
+    }
+    /** True when the underlying error is a ConfigInvalid (phase 1 failure). */
+    get isConfigInvalid() {
+        return this.cause instanceof ConfigInvalid;
+    }
+    /** Remediation message suitable for `cc-openclaw doctor` output. */
+    remediation() {
+        if (this.isConfigInvalid) {
+            const ci = this.cause;
+            return [
+                `Phase "${this.phase}" failed: configuration invalid.`,
+                `Check env vars (OPENCLAW_CC_OPENCLAW_ACTIVE, CC_OPENCLAW_*) and`,
+                `~/.openclaw/openclaw.json.`,
+                `Issues:`,
+                ...ci.issues.map((i) => `  - ${i}`),
+            ].join('\n');
+        }
+        if (this.isDrift) {
+            const de = this.cause;
+            return [
+                `Phase "${this.phase}" failed: upstream Claude Code shape has drifted.`,
+                `Run "openclaw update" to refresh cc-openclaw, or pin the Claude Code version.`,
+                `Failing specs:`,
+                ...de.failedSpecs.map((s) => `  - [${s.id}] ${s.reason}`),
+            ].join('\n');
+        }
+        return `Phase "${this.phase}" failed: ${this.cause.message}`;
+    }
+}
+//# sourceMappingURL=boot.js.map

package/dist/src/lifecycle/boot.js.map

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

package/dist/src/lifecycle/patch-manifest.d.ts

@@ -0,0 +1,82 @@
+/**
+ * PatchManifest — declarative registry for prototype-patch specs.
+ *
+ * Each PatchSpec declares:
+ *   - expectedShape: synchronous probe (signature / property existence)
+ *   - expectedBehavior: async runtime probe (tiny smoke test)
+ *   - install / uninstall: the actual mutation
+ *
+ * Boot phase 3 calls validate() — runs ALL probes.
+ * If ANY fail, throws DriftError listing every failing spec.
+ * Boot is refused; nothing is installed. No silent no-ops.
+ *
+ * Boot phase 4 calls install() — installs ALL specs atomically
+ * (i.e. only after validate() has passed).
+ */
+export interface PatchSpec<T = unknown> {
+    /** Stable identifier used in drift reports and mutation tests. */
+    id: string;
+    /** e.g. "claude-code/dist/session/SessionManager" — informational */
+    targetModule: string;
+    /** e.g. "SessionManager.prototype.startSession" — informational */
+    targetSymbol: string;
+    /**
+     * Resolve the live target. Called once per probe + install operation.
+     * Each spec resolves its own target — different specs target different
+     * upstream symbols, so a single global target is the wrong abstraction.
+     *
+     * **Async-compatible** (since Phase E#3 architectural finding 2026-05-13):
+     * may return `T` directly OR a `Promise<T>`. ESM upstream packages with
+     * top-level await (e.g. `openclaw`) cannot be loaded via sync `require()`;
+     * they require `await import()`. PatchManifest awaits the return value
+     * uniformly. Per PRP §3.2 G1.
+     */
+    resolve: () => T | Promise<T>;
+    /**
+     * Synchronous shape probe. Returns true when the symbol exists with the
+     * expected signature (property count, method name, etc.).
+     * Must NOT mutate the target.
+     */
+    expectedShape: (target: T) => boolean;
+    /**
+     * Async behavior probe. Returns true when a minimal smoke invocation
+     * demonstrates the expected behavior contract.
+     * Must NOT mutate the target; must be fast (<100ms).
+     */
+    expectedBehavior: (target: T) => Promise<boolean>;
+    /**
+     * Apply the patch. Called only after validate() passes for all specs.
+     */
+    install: (target: T) => void;
+    /**
+     * Revert the patch. Called on emergency rollback or unload.
+     */
+    uninstall: (target: T) => void;
+}
+export declare class PatchManifest {
+    private readonly specs;
+    private installed;
+    /**
+     * Register a PatchSpec. Order of registration determines install order.
+     * Idempotent on same id — re-registering the same id is a no-op.
+     */
+    register<T = unknown>(spec: PatchSpec<T>): void;
+    /**
+     * Boot phase 3: run ALL expectedShape + expectedBehavior probes.
+     * If any fail, throws DriftError listing ALL failures.
+     * Never installs on probe failure.
+     */
+    validate(): Promise<void>;
+    /**
+     * Boot phase 4: install ALL specs.
+     * Must only be called after validate() passes (enforced by Boot orchestrator).
+     */
+    install(): Promise<void>;
+    /**
+     * Emergency rollback — uninstalls in reverse registration order.
+     */
+    uninstall(): Promise<void>;
+    get isInstalled(): boolean;
+    get size(): number;
+    ids(): string[];
+}

package/dist/src/lifecycle/patch-manifest.js

@@ -0,0 +1,126 @@
+/**
+ * PatchManifest — declarative registry for prototype-patch specs.
+ *
+ * Each PatchSpec declares:
+ *   - expectedShape: synchronous probe (signature / property existence)
+ *   - expectedBehavior: async runtime probe (tiny smoke test)
+ *   - install / uninstall: the actual mutation
+ *
+ * Boot phase 3 calls validate() — runs ALL probes.
+ * If ANY fail, throws DriftError listing every failing spec.
+ * Boot is refused; nothing is installed. No silent no-ops.
+ *
+ * Boot phase 4 calls install() — installs ALL specs atomically
+ * (i.e. only after validate() has passed).
+ */
+import { DriftError } from '../lib/domain-error.js';
+// ── PatchManifest class ───────────────────────────────────────────────────────
+export class PatchManifest {
+    specs = [];
+    installed = false;
+    /**
+     * Register a PatchSpec. Order of registration determines install order.
+     * Idempotent on same id — re-registering the same id is a no-op.
+     */
+    register(spec) {
+        const existing = this.specs.find((s) => s.id === spec.id);
+        if (existing)
+            return;
+        this.specs.push(spec);
+    }
+    /**
+     * Boot phase 3: run ALL expectedShape + expectedBehavior probes.
+     * If any fail, throws DriftError listing ALL failures.
+     * Never installs on probe failure.
+     */
+    async validate() {
+        const failures = [];
+        for (const spec of this.specs) {
+            // Resolve target — each spec resolves its own upstream symbol.
+            // Awaiting handles both sync (T) and async (Promise<T>) returns.
+            let target;
+            try {
+                target = await spec.resolve();
+            }
+            catch (err) {
+                failures.push({
+                    id: spec.id,
+                    reason: `resolve threw: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+            // Shape probe — synchronous
+            let shapeOk = false;
+            try {
+                shapeOk = spec.expectedShape(target);
+            }
+            catch (err) {
+                shapeOk = false;
+                failures.push({
+                    id: spec.id,
+                    reason: `expectedShape threw: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+            if (!shapeOk) {
+                failures.push({ id: spec.id, reason: 'expectedShape returned false' });
+                continue;
+            }
+            // Behavior probe — async
+            let behaviorOk = false;
+            try {
+                behaviorOk = await spec.expectedBehavior(target);
+            }
+            catch (err) {
+                failures.push({
+                    id: spec.id,
+                    reason: `expectedBehavior threw: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+            if (!behaviorOk) {
+                failures.push({ id: spec.id, reason: 'expectedBehavior returned false' });
+            }
+        }
+        if (failures.length > 0) {
+            throw new DriftError(failures);
+        }
+    }
+    /**
+     * Boot phase 4: install ALL specs.
+     * Must only be called after validate() passes (enforced by Boot orchestrator).
+     */
+    async install() {
+        for (const spec of this.specs) {
+            const target = await spec.resolve();
+            spec.install(target);
+        }
+        this.installed = true;
+    }
+    /**
+     * Emergency rollback — uninstalls in reverse registration order.
+     */
+    async uninstall() {
+        for (let i = this.specs.length - 1; i >= 0; i--) {
+            try {
+                const spec = this.specs[i];
+                const target = await spec.resolve();
+                spec.uninstall(target);
+            }
+            catch {
+                // Best-effort; continue uninstalling others.
+            }
+        }
+        this.installed = false;
+    }
+    get isInstalled() {
+        return this.installed;
+    }
+    get size() {
+        return this.specs.length;
+    }
+    ids() {
+        return this.specs.map((s) => s.id);
+    }
+}
+//# sourceMappingURL=patch-manifest.js.map

package/dist/src/lifecycle/patch-manifest.js.map

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

package/dist/src/lifecycle/phase-import-upstream.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Phase 2 — import-upstream
+ *
+ * Dynamically imports the "openclaw" package and returns its namespace as
+ * `unknown`. Zero `any`. The caller (boot.ts / phase 3) is responsible for
+ * narrowing the shape via PatchManifest.validate().
+ *
+ * Using a variable-held specifier prevents tsc from attempting static
+ * resolution of the peer-dependency at build time (same pattern as doctor.ts
+ * check_bridge_wiring).
+ */
+export declare function importUpstream(): Promise<unknown>;

package/dist/src/lifecycle/phase-import-upstream.js

@@ -0,0 +1,18 @@
+/**
+ * Phase 2 — import-upstream
+ *
+ * Dynamically imports the "openclaw" package and returns its namespace as
+ * `unknown`. Zero `any`. The caller (boot.ts / phase 3) is responsible for
+ * narrowing the shape via PatchManifest.validate().
+ *
+ * Using a variable-held specifier prevents tsc from attempting static
+ * resolution of the peer-dependency at build time (same pattern as doctor.ts
+ * check_bridge_wiring).
+ */
+export async function importUpstream() {
+    // Held in a variable to suppress tsc static-resolution attempt.
+    const specifier = 'openclaw';
+    const ns = await import(specifier);
+    return ns;
+}
+//# sourceMappingURL=phase-import-upstream.js.map

package/dist/src/lifecycle/phase-import-upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-import-upstream.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-import-upstream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,gEAAgE;IAChE,MAAM,SAAS,GAAG,UAAU,CAAC;IAC7B,MAAM,EAAE,GAAY,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/src/lifecycle/phase-install-patches.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Phase 4 — install-patches
+ *
+ * Calls manifest.install() atomically — only reached after phase 3
+ * (validate-upstream) passes. All probes have already confirmed the
+ * expected shape; install proceeds without further checks.
+ *
+ * On any install error, attempts manifest.uninstall() as best-effort rollback
+ * before re-throwing so boot fails loud.
+ */
+import type { PatchManifest } from './patch-manifest.js';
+export declare function installPatches(manifest: PatchManifest, _upstreamNs: unknown): Promise<void>;

package/dist/src/lifecycle/phase-install-patches.js

@@ -0,0 +1,31 @@
+/**
+ * Phase 4 — install-patches
+ *
+ * Calls manifest.install() atomically — only reached after phase 3
+ * (validate-upstream) passes. All probes have already confirmed the
+ * expected shape; install proceeds without further checks.
+ *
+ * On any install error, attempts manifest.uninstall() as best-effort rollback
+ * before re-throwing so boot fails loud.
+ */
+export async function installPatches(manifest, _upstreamNs) {
+    // Note: upstreamNs is unused — each PatchSpec resolves its own target via
+    // PatchSpec.resolve() (PRP §3.2 G1). The parameter is kept in the signature
+    // for boot.ts wiring symmetry; spec.resolve() implementations close over
+    // their own upstream symbol lookups. Async since v1.0.0-rc1 to support
+    // ESM upstream packages with top-level await.
+    try {
+        await manifest.install();
+    }
+    catch (err) {
+        // Best-effort rollback before propagating.
+        try {
+            await manifest.uninstall();
+        }
+        catch {
+            // Rollback failure is secondary; original error takes precedence.
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=phase-install-patches.js.map

package/dist/src/lifecycle/phase-install-patches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-install-patches.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-install-patches.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAuB,EAAE,WAAoB;IAChF,0EAA0E;IAC1E,4EAA4E;IAC5E,yEAAyE;IACzE,uEAAuE;IACvE,8CAA8C;IAC9C,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,2CAA2C;QAC3C,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;QACpE,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/src/lifecycle/phase-schedule-jobs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Phase 7 — schedule-jobs
+ *
+ * Sets up recurring background tasks (stub):
+ *   - SessionRegistry.snapshot() on a configurable interval (default 5 min)
+ *   - Stalled-session watchdog timer
+ *   - Runaway-loop watchdog
+ *
+ * Phase E wires real timers here.
+ */
+import type { SessionRegistry } from '../persistence/session-registry.js';
+export declare function scheduleJobs(_registry: SessionRegistry): void;

package/dist/src/lifecycle/phase-schedule-jobs.js

@@ -0,0 +1,15 @@
+/**
+ * Phase 7 — schedule-jobs
+ *
+ * Sets up recurring background tasks (stub):
+ *   - SessionRegistry.snapshot() on a configurable interval (default 5 min)
+ *   - Stalled-session watchdog timer
+ *   - Runaway-loop watchdog
+ *
+ * Phase E wires real timers here.
+ */
+export function scheduleJobs(_registry) {
+    // Phase E: wire setInterval for registry.snapshot() + watchdog timers.
+    // Stub — no-op in Phase D.
+}
+//# sourceMappingURL=phase-schedule-jobs.js.map

package/dist/src/lifecycle/phase-schedule-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-schedule-jobs.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-schedule-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,UAAU,YAAY,CAAC,SAA0B;IACrD,uEAAuE;IACvE,2BAA2B;AAC7B,CAAC"}

package/dist/src/lifecycle/phase-start-server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Phase 6 — start-server
+ *
+ * Starts the openai-compat HTTP server (stub).
+ * Phase E wires the real server instantiation here.
+ */
+export interface StartServerOptions {
+    /** Port the openai-compat HTTP server listens on. Default: 18796. */
+    port?: number;
+}
+export declare function startServer(_opts?: StartServerOptions): Promise<void>;

package/dist/src/lifecycle/phase-start-server.js

@@ -0,0 +1,11 @@
+/**
+ * Phase 6 — start-server
+ *
+ * Starts the openai-compat HTTP server (stub).
+ * Phase E wires the real server instantiation here.
+ */
+export async function startServer(_opts = {}) {
+    // Phase E: instantiate EmbeddedServer / openai-compat HTTP listener here.
+    // Stub — no-op in Phase D.
+}
+//# sourceMappingURL=phase-start-server.js.map

package/dist/src/lifecycle/phase-start-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-start-server.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-start-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAA4B,EAAE;IAC9D,0EAA0E;IAC1E,2BAA2B;AAC7B,CAAC"}

package/dist/src/lifecycle/phase-validate-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Phase 1 — validate-config
+ *
+ * Calls ConfigSchema.parse(loadConfigSources()).
+ * Throws ConfigInvalid (wrapping zod issues) on failure.
+ * Boot refuses with a phase-keyed message.
+ */
+import { type Config } from '../config/schema.js';
+export declare function validateConfig(): Config;

package/dist/src/lifecycle/phase-validate-config.js

@@ -0,0 +1,25 @@
+/**
+ * Phase 1 — validate-config
+ *
+ * Calls ConfigSchema.parse(loadConfigSources()).
+ * Throws ConfigInvalid (wrapping zod issues) on failure.
+ * Boot refuses with a phase-keyed message.
+ */
+import { ZodError } from 'zod';
+import { ConfigSchema } from '../config/schema.js';
+import { loadConfigSources } from '../config/loader.js';
+import { ConfigInvalid } from '../lib/domain-error.js';
+export function validateConfig() {
+    const raw = loadConfigSources();
+    try {
+        return ConfigSchema.parse(raw);
+    }
+    catch (err) {
+        if (err instanceof ZodError) {
+            const issues = err.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+            throw new ConfigInvalid('configuration validation failed', issues);
+        }
+        throw new ConfigInvalid('configuration validation failed (unexpected error)', [String(err)]);
+    }
+}
+//# sourceMappingURL=phase-validate-config.js.map

package/dist/src/lifecycle/phase-validate-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-validate-config.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-validate-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAe,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,MAAM,IAAI,aAAa,CAAC,iCAAiC,EAAE,MAAM,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,IAAI,aAAa,CACrB,oDAAoD,EACpD,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CACd,CAAC;IACJ,CAAC;AACH,CAAC"}