@jinn-network/client 0.1.2 → 0.1.3-canary.12cf8b76

package/dist/solvernets/daemon-init.js

@@ -0,0 +1,431 @@
+/**
+ * Daemon-side bootstrap of the SolverNet subsystem.
+ *
+ * Spec: `spec/2026-05-05-solvernet-creation-and-launch.md` Task 11 (daemon
+ * startup integration). Wires the persistence, recovery, and operator
+ * catalog surfaces so the daemon can resume in-flight launches/lifecycle
+ * transitions and serve the operator catalog UI.
+ *
+ * This module is intentionally THIN: it composes existing pieces (`SolverNetStore`,
+ * `recoverInFlightLaunches`, `recoverInFlightLifecycleTransitions`, and the
+ * `IdentityRegistryBackedSolverNetRegistryClient`) into a single
+ * `initSolverNetSubsystem(deps)` call that `main.ts` invokes once after the
+ * `FleetBootstrapper` finishes. Task 11 sets up the SCAFFOLDING; Task 12
+ * is responsible for the gating refactor that swaps out the legacy
+ * `collectTestnetAutoTaskGenerators` path for owned launched-record-driven
+ * generator construction.
+ *
+ * Order of operations (mirrors the per-section ordering in
+ * `launch-state-machine.ts` and `lifecycle-transitions.ts`):
+ *
+ *   1. Resume any record stuck in `status: 'launching'` →
+ *      `recoverInFlightLaunches`. Safe to call when no records are in flight.
+ *   2. Resume any record with `lifecycleProgress` set →
+ *      `recoverInFlightLifecycleTransitions`. Same safety property.
+ *   3. Load owned records → identify which ones have
+ *      `status === 'launched' && generatorEnabled`; those are the
+ *      "ready-to-spawn" set the next-task generator wiring will iterate.
+ *   4. Start the operator catalog refresher loop (interval-driven) so the
+ *      daemon API can hand SPA reads without a synchronous subgraph round
+ *      trip on every poll.
+ *
+ * Out of scope for Task 11 (do NOT add here):
+ *
+ *   - Actually constructing `prediction.v1` generators per launched record
+ *     (Task 12).
+ *   - Wiring the catalog cache into the API server's `/v1/solvernets/*`
+ *     endpoints (Task 14/15).
+ *   - Removing the legacy `collectTestnetAutoTaskGenerators` path
+ *     (Task 12).
+ *
+ * Day-1 SubgraphClient note: the canonical Jinn subgraph has not yet
+ * surfaced the `solvernet-manifest:` setMetadata index (Task 25 wires the
+ * extension). Until then, callers may pass `createNoopSubgraphClient()` so
+ * `recoverInFlightLaunches` and `listLaunched` return empty arrays
+ * gracefully — recovery only short-circuits via subgraph events on
+ * mempool-drop (rare); the catalog refresher logs a one-line warning when
+ * it observes the no-op path so the operator can see the wiring is
+ * incomplete. Production wiring happens in Task 25.
+ */
+import { uploadToIpfs, fetchFromIpfs, } from '../adapters/mech/ipfs.js';
+import { IDENTITY_REGISTRY_SET_METADATA_ABI, } from '../erc8004/abis.js';
+import { IdentityRegistryBackedSolverNetRegistryClient, } from './registry-client-erc8004.js';
+import { recoverInFlightLaunches, } from './launch-state-machine.js';
+import { recoverInFlightLifecycleTransitions, } from './lifecycle-transitions.js';
+// ── Catalog refresh defaults ────────────────────────────────────────────────
+/**
+ * How often the operator catalog cache is refreshed against the registry
+ * client. 30 seconds is conservative — operators rarely launch multiple
+ * SolverNets per minute, and the SPA's join-flow polling is on a similar
+ * cadence. Tunable via `initSolverNetSubsystem.catalogRefreshIntervalMs`.
+ */
+export const DEFAULT_CATALOG_REFRESH_INTERVAL_MS = 30_000;
+// ── Implementation ──────────────────────────────────────────────────────────
+/**
+ * Initialise the SolverNet subsystem at daemon startup.
+ *
+ * Call after `FleetBootstrapper` resolves (so the master Safe + agent EOA
+ * referenced by launched records are available) and before any task
+ * generators are constructed.
+ *
+ * Errors during the recovery scans are captured per-record into
+ * `recovery.inFlightLaunches.failed` / `recovery.inFlightLifecycle.failed`
+ * so a single broken record cannot block daemon startup. Errors during
+ * the initial catalog refresh are logged and stored on the cache; the
+ * refresher continues ticking.
+ */
+export async function initSolverNetSubsystem(deps) {
+    const logger = deps.logger ?? {
+        warn: (msg) => console.warn(msg),
+        info: (msg) => console.log(msg),
+    };
+    // Step 1 — resume in-flight launches. The state machine is forward-only
+    // and idempotent under retry, so this is safe even when no records are
+    // in flight.
+    const inFlightLaunches = await recoverInFlightLaunches({
+        store: deps.store,
+        ipfs: deps.ipfs,
+        publisher: deps.publisher,
+        subgraph: deps.subgraph,
+        awaitTxConfirmation: deps.awaitTxConfirmation,
+        resolveSigner: deps.resolveSigner,
+        // The launch-recovery path needs a generator spawner. Task 11 leaves
+        // it as a no-op — Task 12 wires the real spawner. Recovery only fires
+        // it on a record that crashed mid-spawn-phase; in that case advancing
+        // to `status: 'launched'` without an active generator is the
+        // recoverable state, and Task 12's startup code will spawn it from
+        // the `pendingGenerators` list below.
+        spawnGenerator: async () => undefined,
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    if (inFlightLaunches.failed.length > 0) {
+        logger.warn(`[solvernet] launch recovery: ${inFlightLaunches.resumed} resumed, ` +
+            `${inFlightLaunches.failed.length} failed`);
+    }
+    else if (inFlightLaunches.resumed > 0) {
+        logger.info(`[solvernet] launch recovery: ${inFlightLaunches.resumed} resumed`);
+    }
+    // Step 2 — resume in-flight lifecycle transitions.
+    const inFlightLifecycle = await recoverInFlightLifecycleTransitions({
+        store: deps.store,
+        registry: deps.registryClient,
+        signer: deps.lifecycleSigner,
+        subgraph: deps.subgraph,
+        awaitTxConfirmation: deps.awaitTxConfirmation,
+        // Task 12 will wire real start/stop generator callbacks (the
+        // counterparts to the launch spawner above). Until then, lifecycle
+        // resume only flips on-disk status — Task 12's per-record generator
+        // construction runs after this return.
+        startGenerator: async () => undefined,
+        stopGenerator: async () => undefined,
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    if (inFlightLifecycle.failed.length > 0) {
+        logger.warn(`[solvernet] lifecycle recovery: ${inFlightLifecycle.resumed} resumed, ` +
+            `${inFlightLifecycle.failed.length} failed`);
+    }
+    else if (inFlightLifecycle.resumed > 0) {
+        logger.info(`[solvernet] lifecycle recovery: ${inFlightLifecycle.resumed} resumed`);
+    }
+    // Step 3 — load post-recovery records and split into the spawn-ready set.
+    // Each spawn-ready entry carries a `recordRef` and a `configRef` that the
+    // generator factory (`makePredictionV1GeneratorForLaunchedRecord`) closes
+    // over. Lifecycle transitions and the SolverNet config API endpoint mutate
+    // these refs at runtime so the per-tick gate and runtime config update
+    // within one cadence — no daemon restart. Defaults for the runtime config
+    // are an empty object: the generator falls back to its built-in defaults
+    // until the operator edits cadence / allowlist / caps via Task 14.
+    const records = await deps.store.loadOwnedRecords();
+    const pendingGenerators = records
+        .filter((r) => r.status === 'launched' && r.generatorEnabled)
+        .map((record) => ({
+        record,
+        recordRef: { current: record },
+        // Seed configRef from the record's persisted generatorConfig if present
+        // (set by Task 14's `PATCH /v1/solvernets/launched/:id/generator-config`
+        // endpoint), otherwise use an empty config so the generator falls back
+        // to its built-in defaults.
+        configRef: {
+            current: (record.generatorConfig ?? {}),
+        },
+    }));
+    logger.info(`[solvernet] loaded ${records.length} owned record(s); ` +
+        `${pendingGenerators.length} ready for generator spawn`);
+    // Step 4 — start the catalog refresher.
+    const catalog = createCatalogCache({
+        registryClient: deps.registryClient,
+        network: deps.network,
+        intervalMs: deps.catalogRefreshIntervalMs ?? DEFAULT_CATALOG_REFRESH_INTERVAL_MS,
+        scheduler: deps.scheduler,
+        autoRefresh: !deps.disableCatalogAutoRefresh,
+        logger,
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+    });
+    // Best-effort initial refresh so the API has something to serve as soon as
+    // the SPA polls. We do not block startup on the result — a registry that
+    // can't be reached should not gate the daemon coming up.
+    catalog.refresh().catch(() => {
+        // Already captured into catalog.lastError; nothing to do here.
+    });
+    return {
+        records,
+        pendingGenerators,
+        catalog,
+        registryClient: deps.registryClient,
+        recovery: {
+            inFlightLaunches,
+            inFlightLifecycle,
+        },
+        stop() {
+            catalog.stop();
+        },
+    };
+}
+function createCatalogCache(config) {
+    let snapshot = [];
+    let lastRefreshedAt = null;
+    let lastError = null;
+    const now = config.now ?? (() => new Date());
+    const setInt = config.scheduler?.setInterval ?? ((cb, ms) => setInterval(cb, ms));
+    const clearInt = config.scheduler?.clearInterval ?? ((h) => clearInterval(h));
+    let handle = null;
+    async function refresh() {
+        try {
+            const summaries = await config.registryClient.listLaunched({ network: config.network });
+            snapshot = summaries;
+            lastRefreshedAt = now();
+            lastError = null;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            lastError = { message, at: now() };
+            config.logger.warn(`[solvernet] catalog refresh failed: ${message}`);
+        }
+    }
+    if (config.autoRefresh) {
+        handle = setInt(() => {
+            void refresh();
+        }, config.intervalMs);
+    }
+    return {
+        getCatalog: () => snapshot,
+        refresh,
+        stop() {
+            if (handle !== null) {
+                clearInt(handle);
+                handle = null;
+            }
+        },
+        lastRefreshedAt: () => lastRefreshedAt,
+        lastError: () => lastError,
+    };
+}
+// ── Adapter helpers ─────────────────────────────────────────────────────────
+//
+// `main.ts` will use these to build the production deps for
+// `initSolverNetSubsystem`. They are exported here so a future test that
+// wants the production adapter (rather than a hand-rolled mock) can opt in.
+/**
+ * Wrap the existing global `uploadToIpfs` / `fetchFromIpfs` helpers in the
+ * `IpfsClient` interface used by the SolverNet registry client. Same
+ * canonical-JSON semantics as the rest of the daemon.
+ */
+export function createIpfsClientAdapter(args) {
+    return {
+        upload: (data) => uploadToIpfs(args.registryUrl, data),
+        fetch: (cid) => fetchFromIpfs(args.gatewayUrl, cid),
+    };
+}
+/**
+ * Day-1 stub `SubgraphClient` returning empty arrays for both queries. The
+ * real subgraph extension lands in Task 25; until then the launch state
+ * machine and registry catalog still function (recovery only consults
+ * the subgraph on mempool-drop, which is rare; catalog refresh produces an
+ * empty list, which the SPA renders as "no SolverNets launched yet" — a
+ * truthful zero state until Task 25 indexes the events).
+ *
+ * Exported so tests can pin a deterministic baseline.
+ */
+export function createNoopSubgraphClient() {
+    return {
+        async fetchSetMetadataEvents() {
+            return [];
+        },
+        async fetchSetMetadataEventsForCid() {
+            return [];
+        },
+    };
+}
+/**
+ * jinn-mono-{follow-up}: real subgraph adapter that queries the deployed
+ * Jinn subgraph (e.g. https://api.studio.thegraph.com/query/.../jinn-testnet/...)
+ * for `SolverNetManifestEvent` rows and JCS-decodes each event's payload
+ * bytes into the typed lifecycle payload. Replaces `createNoopSubgraphClient`
+ * for any daemon that reads `JINN_SUBGRAPH_URL`.
+ *
+ * The schema only stores `solvernet-manifest:<cid>` events (lifecycle and
+ * launch share the prefix). `keyPrefix` is therefore an effective filter:
+ * the entity itself encodes that constraint, so we do not pass it to the
+ * GraphQL query. Callers passing a different prefix get an empty list.
+ */
+export function createGraphqlSubgraphClient(args) {
+    const url = args.url;
+    async function runQuery(query, variables) {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ query, variables }),
+        });
+        if (!response.ok) {
+            throw new Error(`subgraph query failed: ${response.status} ${response.statusText}`);
+        }
+        const json = (await response.json());
+        if (json.errors && json.errors.length > 0) {
+            throw new Error(`subgraph errors: ${json.errors.map((e) => e.message).join('; ')}`);
+        }
+        return {
+            solverNetManifestEvents: json.data?.solverNetManifestEvents ?? [],
+        };
+    }
+    function decodePayload(rowPayloadHex) {
+        const bytes = hexToBytes(rowPayloadHex);
+        const json = new TextDecoder().decode(bytes);
+        const parsed = JSON.parse(json);
+        return parsed;
+    }
+    function rowToEvent(row) {
+        return {
+            agentId: String(row.agentId),
+            key: String(row.metadataKey),
+            payload: decodePayload(String(row.payload)),
+            blockNumber: Number(row.blockNumber),
+            transactionIndex: Number(row.transactionIndex ?? 0),
+        };
+    }
+    return {
+        async fetchSetMetadataEvents(opts) {
+            if (opts.keyPrefix !== 'solvernet-manifest:') {
+                // The schema entity is hardcoded to this prefix; any other prefix
+                // would yield zero rows. Keep behaviour consistent with the noop.
+                return [];
+            }
+            const sinceBlock = typeof opts.sinceBlock === 'number' ? opts.sinceBlock : 0;
+            const query = `
+        query MetadataEventsSince($sinceBlock: BigInt!) {
+          solverNetManifestEvents(
+            where: { blockNumber_gte: $sinceBlock }
+            orderBy: blockNumber
+            orderDirection: asc
+            first: 1000
+          ) {
+            agentId
+            metadataKey
+            payload
+            blockNumber
+            transactionIndex
+          }
+        }
+      `;
+            const { solverNetManifestEvents } = await runQuery(query, {
+                sinceBlock: String(sinceBlock),
+            });
+            return solverNetManifestEvents.map(rowToEvent);
+        },
+        async fetchSetMetadataEventsForCid(opts) {
+            const query = `
+        query MetadataEventsForCid($manifestCid: String!) {
+          solverNetManifestEvents(
+            where: { manifestCid: $manifestCid }
+            orderBy: blockNumber
+            orderDirection: asc
+            first: 1000
+          ) {
+            agentId
+            metadataKey
+            payload
+            blockNumber
+            transactionIndex
+          }
+        }
+      `;
+            const { solverNetManifestEvents } = await runQuery(query, {
+                manifestCid: opts.manifestCid,
+            });
+            return solverNetManifestEvents.map(rowToEvent);
+        },
+    };
+}
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0) {
+        throw new Error(`invalid hex payload length: ${clean.length}`);
+    }
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * Adapter that turns a viem (walletClient, publicClient, identityRegistryAddress)
+ * triple into a `MetadataPublisher` whose `value` is treated as raw bytes
+ * (the JCS-encoded SolverNet lifecycle payload), bypassing the
+ * `IdentityPublisher`'s ABI-encoded execution-payload tuple. Production
+ * `main.ts` constructs one of these alongside the existing `IdentityPublisher`
+ * — they share the same on-chain `setMetadata` ABI but encode different
+ * payload schemas under different `metadataKey` prefixes.
+ *
+ * `signer` from the call site is passed through but unused here — the
+ * walletClient is bound at construction time. The interface keeps it so
+ * tests can swap in a mock that does inspect it.
+ */
+export function createMetadataPublisherFromViem(args) {
+    return {
+        async setMetadata({ agentId, key, value }) {
+            const account = args.walletClient.account;
+            if (!account) {
+                throw new Error('createMetadataPublisherFromViem: walletClient has no account configured');
+            }
+            const chain = args.walletClient.chain;
+            if (!chain) {
+                throw new Error('createMetadataPublisherFromViem: walletClient has no chain configured');
+            }
+            const txHash = await args.walletClient.writeContract({
+                address: args.identityRegistryAddress,
+                abi: IDENTITY_REGISTRY_SET_METADATA_ABI,
+                functionName: 'setMetadata',
+                // viem's bytes input accepts `0x`-prefixed hex; convert from Uint8Array.
+                args: [BigInt(agentId), key, uint8ArrayToHex(value)],
+                account,
+                chain,
+            });
+            const receipt = await args.publicClient.waitForTransactionReceipt({ hash: txHash });
+            return {
+                txHash,
+                blockNumber: Number(receipt.blockNumber),
+            };
+        },
+    };
+}
+/**
+ * Build a production `IdentityRegistryBackedSolverNetRegistryClient` from a
+ * pre-built deps bundle. Convenience wrapper kept here so `main.ts` only
+ * imports from `./solvernets/daemon-init.js` for the whole subsystem.
+ */
+export function createDefaultRegistryClient(args) {
+    return new IdentityRegistryBackedSolverNetRegistryClient({
+        ipfs: args.ipfs,
+        publisher: args.publisher,
+        subgraph: args.subgraph,
+        network: args.network,
+    });
+}
+// ── Internals ───────────────────────────────────────────────────────────────
+function uint8ArrayToHex(bytes) {
+    let hex = '0x';
+    for (const b of bytes) {
+        hex += b.toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+//# sourceMappingURL=daemon-init.js.map

package/dist/solvernets/daemon-init.js.map

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

package/dist/solvernets/launch-state-machine.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Forward-only checkpointed launch state machine for SolverNet creation.
+ *
+ * Spec: `spec/2026-05-05-solvernet-creation-and-launch.md` §10 (the launch
+ * action) and §6.2 (the `LaunchedSolverNetRecord.launchProgress` shape).
+ *
+ * The five phases — each persisted to disk *before* the side effect runs —
+ * give the daemon a recovery checkpoint at every boundary:
+ *
+ *   pinning      → upload canonical manifest JSON to IPFS
+ *   recording    → atomic-write the launched record to disk with the cid
+ *   broadcasting → submit IdentityRegistry.setMetadata tx
+ *   confirming   → wait for tx receipt (or detect anchored event in subgraph)
+ *   spawning     → start the launcher-owned generator
+ *   → status: 'launched', launchProgress: undefined
+ *
+ * Idempotency invariants (per spec §10):
+ *
+ *   - IPFS pin: same canonical body → same cid (content-addressed). Re-pinning
+ *     is free and produces no protocol-level duplicate.
+ *   - setMetadata: event-only, harmless to re-fire — most-recent-wins
+ *     resolver picks the latest. We still avoid unnecessary re-broadcasts by
+ *     scanning the subgraph for an existing event under the cid before
+ *     re-firing.
+ *   - Disk write: atomic-rename via the SolverNetStore.
+ *   - spawnGenerator: caller-owned. The state machine assumes the spawner
+ *     guards against double-spawn for a given record (Task 12 wires the
+ *     real launcher).
+ *
+ * Architectural choice: the state machine takes ipfs / publisher / subgraph
+ * directly (not the wrapped `SolverNetRegistryClient`). The registry client's
+ * `publishManifest` collapses pin+broadcast into one call, which is
+ * incompatible with the spec's per-phase checkpointing. By holding the
+ * lower-level deps here we can place a disk checkpoint between every phase.
+ *
+ * The state machine never throws on caller-recoverable errors (broadcast
+ * revert, mempool drop, RPC timeout). Instead, it persists `txError` to the
+ * record and rethrows the error so the caller (launch UI / daemon scan) can
+ * decide whether to retry. After `maxAttempts` failed attempts the record
+ * flips to `status: 'failed'`; a manual reset to 'launching' + clear of
+ * `txError` makes the record retryable again.
+ */
+import type { SolverNetManifestV1 } from '../vendor/@jinn-network/sdk/dist/solvernets/index.js';
+import { type IpfsClient, type MetadataPublisher, type SubgraphClient } from './registry-client-erc8004.js';
+import type { SignerWithAgentEoa } from './registry-client.js';
+import { type LaunchedSolverNetRecord, type SolverNetStore } from './store.js';
+/**
+ * Default ceiling on retries before a record is marked `status: 'failed'`.
+ * Tunable via `LaunchActionDeps.maxAttempts`.
+ */
+export declare const DEFAULT_MAX_ATTEMPTS = 5;
+export interface LaunchActionDeps {
+    store: SolverNetStore;
+    ipfs: IpfsClient;
+    publisher: MetadataPublisher;
+    subgraph: SubgraphClient;
+    spawnGenerator: (record: LaunchedSolverNetRecord) => Promise<void>;
+    /**
+     * Resolve a tx hash to a confirmed receipt. Implementations may poll an
+     * RPC, watch logs, or wrap viem's `waitForTransactionReceipt`. Throwing is
+     * the signal that the tx is missing from the mempool / chain — the state
+     * machine then consults the subgraph before deciding to re-broadcast.
+     */
+    awaitTxConfirmation: (txHash: `0x${string}`) => Promise<{
+        blockNumber: number;
+    }>;
+    now?: () => Date;
+    maxAttempts?: number;
+}
+/**
+ * Used by `recoverInFlightLaunches` to translate a record's
+ * `launcherAgentId` into the in-process signer that owns it. In production
+ * the daemon always runs a single launcher, so this is usually `() =>
+ * theOnlySigner`. The interface keeps the door open for multi-launcher
+ * daemons.
+ */
+export type ResolveSigner = (launcherAgentId: string) => Promise<SignerWithAgentEoa>;
+export declare class LaunchAction {
+    private readonly deps;
+    private readonly now;
+    private readonly maxAttempts;
+    constructor(deps: LaunchActionDeps);
+    /**
+     * Launch a new SolverNet from a signed manifest. Forward-only; advances
+     * through pinning → recording → broadcasting → confirming → spawning.
+     *
+     * If a record with the same `solverNetId` already exists, the call is
+     * delegated to `resume()` (idempotent): an already-`launched` record is
+     * returned unchanged; an in-flight record continues from its checkpoint.
+     *
+     * Throws on side-effect failure (revert, RPC error, etc). The record on
+     * disk reflects the failed phase + `txError`; the caller can either retry
+     * via `resume(record)` or, after `maxAttempts`, mark the record as failed
+     * and surface the error.
+     */
+    launch(args: {
+        manifest: SolverNetManifestV1;
+        signer: SignerWithAgentEoa;
+        /**
+         * jinn-mono-jnr1: per-record runtime config from the wizard (cadence,
+         * caps, allow/blocklists). Persisted onto the launched record so the
+         * generator factory's `configRef` seeds with the operator's choice
+         * instead of falling back to DEFAULTS. Optional — empty / undefined
+         * means "use DEFAULTS for everything", which preserves the legacy
+         * behaviour for callers that don't yet pass this through.
+         */
+        generatorConfig?: Record<string, unknown>;
+    }): Promise<LaunchedSolverNetRecord>;
+    /**
+     * Resume an in-flight launch from its current checkpoint. Safe to call
+     * multiple times for the same record; idempotent under the invariants in
+     * the module-level docblock.
+     */
+    resume(args: {
+        record: LaunchedSolverNetRecord;
+        signer: SignerWithAgentEoa;
+        /**
+         * The manifest body. Required only for resume paths that may need to
+         * re-pin (none currently — recording is the first checkpoint that
+         * carries a cid). Carried through so future phases can re-canonicalize
+         * if needed.
+         */
+        manifest?: SolverNetManifestV1;
+    }): Promise<LaunchedSolverNetRecord>;
+    /**
+     * Phase 3 — broadcasting. Submit setMetadata; capture txHash. Persist the
+     * record at `confirming` *with* the txHash before returning.
+     *
+     * Pre-broadcast guard: scan the subgraph for an existing event under this
+     * cid. If one exists, the broadcast already happened (possibly in a prior
+     * crash that lost the txHash) — short-circuit straight to confirming.
+     */
+    private runBroadcastingPhase;
+    /**
+     * Phase 4 — confirming. Wait for the receipt for the recorded txHash.
+     *
+     * If the tx is missing from the mempool / chain, fall back to the
+     * subgraph: if the cid has a setMetadata event, treat as confirmed (block
+     * number from the event); otherwise re-broadcast.
+     */
+    private runConfirmingPhase;
+    /**
+     * Phase 5 — spawning. Hand the launched record to the generator-spawner.
+     * On success, finalize the record: clear `launchProgress`, flip `status`
+     * to 'launched', stamp `statusUpdatedAt`.
+     */
+    private runSpawningPhase;
+}
+/**
+ * Scan the launched-records directory and resume any record whose
+ * `status === 'launching'`. Returns counts of successful resumes and any
+ * per-record errors (so a single broken record cannot block daemon startup).
+ *
+ * Daemons should call this once at boot, before starting the generator
+ * loops — Task 12 wires the call site.
+ */
+export declare function recoverInFlightLaunches(deps: LaunchActionDeps & {
+    resolveSigner: ResolveSigner;
+}): Promise<{
+    resumed: number;
+    failed: Array<{
+        solverNetId: string;
+        error: Error;
+    }>;
+}>;