@gzeoneth/gov-tracker 0.1.0

package/dist/cli/lib/cli.d.ts

@@ -0,0 +1,92 @@
+/**
+ * CLI Utilities for Monitor Script
+ *
+ * NOTE: This is CLI application code that demonstrates SDK usage, not library code.
+ * Developers should treat this as part of the CLI application, not as part of the SDK API.
+ *
+ * Provides RPC option parsing, provider creation, transaction execution,
+ * and the core monitoring cycle. This is monitor-specific code, not part of the SDK.
+ */
+import { Command, Option } from "commander";
+import { ethers } from "ethers";
+import { ProposalStageTracker, TrackedStage, TrackingResult, TrackingCheckpoint, PreparedTransaction, PrepareResult, isElectionGovernor, DiscoveredProposal, DiscoveredTimelockOp, DiscoveryWatermarks } from "../../index";
+export { isElectionGovernor };
+/** Default block lag to prevent reorg issues */
+export declare const DEFAULT_BLOCK_LAG = 12;
+/** Default max age in days for re-tracking incomplete proposals */
+export declare const DEFAULT_MAX_AGE_DAYS = 60;
+/** Maximum consecutive errors before skipping an item */
+export declare const MAX_CONSECUTIVE_ERRORS = 5;
+export declare const rpcOptions: Option[];
+export declare function addOptions(cmd: Command, opts: Option[]): void;
+export interface ProviderBundle {
+    l2Provider: ethers.providers.JsonRpcProvider;
+    l1Provider: ethers.providers.JsonRpcProvider;
+    novaProvider: ethers.providers.JsonRpcProvider;
+}
+export declare function createProvidersFromOptions(opts: {
+    l2Rpc?: string;
+    l1Rpc?: string;
+    novaRpc?: string;
+}): ProviderBundle;
+export declare function requirePrivateKeyForWrite(opts: {
+    write?: boolean;
+    privateKey?: string;
+}): void;
+export declare function createSigner(privateKey: string): ethers.Wallet;
+export declare function executeTransaction(prepared: PreparedTransaction, signer: ethers.Wallet, providers: ProviderBundle): Promise<{
+    success: boolean;
+    txHash?: string;
+    error?: string;
+}>;
+export declare function formatDryRun(prepared: PreparedTransaction): string;
+export declare function formatTrackingResult(result: TrackingResult, label?: string): string;
+export declare function formatStagesBrief(stages: TrackedStage[]): string;
+export declare function formatCacheStatus(checkpoints: Map<string, TrackingCheckpoint>): string;
+export declare function runWithLoop(cycleFn: () => Promise<void>, options: {
+    loop: boolean;
+    intervalMs: number;
+    healthCheckUrl?: string;
+}): Promise<void>;
+export interface TrackCallbackResult {
+    key: string;
+    result: TrackingResult | null;
+    prepared?: PreparedTransaction;
+    error?: string;
+}
+export interface TrackCallbackReturn {
+    shouldRetrack?: boolean;
+}
+export interface MonitorRunOptions {
+    prepare?: boolean;
+    force?: boolean;
+    preparePending?: boolean;
+    onTrack?: (result: TrackCallbackResult) => Promise<TrackCallbackReturn | void> | void;
+    startBlock?: number;
+    blockLag?: number;
+    maxChainDepth?: number;
+    maxAgeDays?: number;
+    /** Number of concurrent tracking operations (default: 1 = sequential) */
+    concurrency?: number;
+}
+export interface MonitorRunResult {
+    tracked: number;
+    prepared: number;
+    errors: number;
+    retracked: number;
+}
+export declare function runMonitorCycle(tracker: ProposalStageTracker, l2Provider: ethers.providers.Provider, options?: MonitorRunOptions): Promise<{
+    result: MonitorRunResult;
+    proposals: DiscoveredProposal[];
+    timelockOps: DiscoveredTimelockOp[];
+    watermarks: DiscoveryWatermarks;
+}>;
+export declare function trackAndPrepare(tracker: ProposalStageTracker, txHash: string, options?: {
+    prepare?: boolean;
+    force?: boolean;
+    preparePending?: boolean;
+}): Promise<{
+    results: TrackingResult[];
+    preparations: PrepareResult[];
+}>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli/lib/cli.d.ts.map

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

package/dist/cli/lib/cli.js

@@ -0,0 +1,562 @@
+"use strict";
+/**
+ * CLI Utilities for Monitor Script
+ *
+ * NOTE: This is CLI application code that demonstrates SDK usage, not library code.
+ * Developers should treat this as part of the CLI application, not as part of the SDK API.
+ *
+ * Provides RPC option parsing, provider creation, transaction execution,
+ * and the core monitoring cycle. This is monitor-specific code, not part of the SDK.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rpcOptions = exports.MAX_CONSECUTIVE_ERRORS = exports.DEFAULT_MAX_AGE_DAYS = exports.DEFAULT_BLOCK_LAG = exports.isElectionGovernor = void 0;
+exports.addOptions = addOptions;
+exports.createProvidersFromOptions = createProvidersFromOptions;
+exports.requirePrivateKeyForWrite = requirePrivateKeyForWrite;
+exports.createSigner = createSigner;
+exports.executeTransaction = executeTransaction;
+exports.formatDryRun = formatDryRun;
+exports.formatTrackingResult = formatTrackingResult;
+exports.formatStagesBrief = formatStagesBrief;
+exports.formatCacheStatus = formatCacheStatus;
+exports.runWithLoop = runWithLoop;
+exports.runMonitorCycle = runMonitorCycle;
+exports.trackAndPrepare = trackAndPrepare;
+const commander_1 = require("commander");
+const ethers_1 = require("ethers");
+const p_limit_1 = __importDefault(require("p-limit"));
+const index_1 = require("../../index");
+Object.defineProperty(exports, "isElectionGovernor", { enumerable: true, get: function () { return index_1.isElectionGovernor; } });
+const logger_1 = require("../../utils/logger");
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default block lag to prevent reorg issues */
+exports.DEFAULT_BLOCK_LAG = 12;
+/** Default max age in days for re-tracking incomplete proposals */
+exports.DEFAULT_MAX_AGE_DAYS = 60;
+/** Maximum consecutive errors before skipping an item */
+exports.MAX_CONSECUTIVE_ERRORS = 5;
+// ============================================================================
+// RPC Configuration
+// ============================================================================
+exports.rpcOptions = [
+    new commander_1.Option("--l2-rpc <url>", "L2 RPC URL").env("ARB1_RPC"),
+    new commander_1.Option("--l1-rpc <url>", "L1 RPC URL").env("ETH_RPC"),
+    new commander_1.Option("--nova-rpc <url>", "Nova RPC URL").env("NOVA_RPC"),
+];
+function addOptions(cmd, opts) {
+    opts.forEach((o) => cmd.addOption(o));
+}
+function createProvidersFromOptions(opts) {
+    const l2Rpc = opts.l2Rpc || process.env.ARB1_RPC || index_1.DEFAULT_RPC_URLS.ARB_ONE;
+    const l1Rpc = opts.l1Rpc || process.env.ETH_RPC;
+    const novaRpc = opts.novaRpc || process.env.NOVA_RPC || index_1.DEFAULT_RPC_URLS.NOVA;
+    if (!l1Rpc) {
+        throw new Error("L1 RPC URL required (--l1-rpc or ETH_RPC env var)");
+    }
+    return {
+        l2Provider: new ethers_1.ethers.providers.JsonRpcProvider(l2Rpc),
+        l1Provider: new ethers_1.ethers.providers.JsonRpcProvider(l1Rpc),
+        novaProvider: new ethers_1.ethers.providers.JsonRpcProvider(novaRpc),
+    };
+}
+// ============================================================================
+// Signer Creation
+// ============================================================================
+function requirePrivateKeyForWrite(opts) {
+    if (opts.write && !opts.privateKey) {
+        console.error("Error: --write requires --private-key or PRIVATE_KEY env var");
+        process.exit(1);
+    }
+}
+function createSigner(privateKey) {
+    return new ethers_1.ethers.Wallet(privateKey.startsWith("0x") ? privateKey : "0x" + privateKey);
+}
+// ============================================================================
+// Transaction Execution
+// ============================================================================
+const RETRYABLE_MAX_RETRIES = 10;
+const RETRYABLE_RETRY_DELAY_MS = 5000;
+async function executeTransaction(prepared, signer, providers) {
+    const isRetryable = prepared.description?.toLowerCase().includes("retryable") ?? false;
+    for (let attempt = 1; attempt <= (isRetryable ? RETRYABLE_MAX_RETRIES : 1); attempt++) {
+        try {
+            const provider = prepared.chain === "L1"
+                ? providers.l1Provider
+                : prepared.chain === "NOVA"
+                    ? providers.novaProvider
+                    : providers.l2Provider;
+            const connectedSigner = signer.connect(provider);
+            console.log(`\nExecuting on ${prepared.chain}: ${prepared.description}`);
+            console.log(`  To: ${prepared.to}`);
+            if (prepared.value !== "0")
+                console.log(`  Value: ${prepared.value}`);
+            const tx = await connectedSigner.sendTransaction({
+                to: prepared.to,
+                data: prepared.data,
+                value: prepared.value,
+            });
+            console.log(`  Tx sent: ${tx.hash}`);
+            const receipt = await tx.wait();
+            console.log(`  Confirmed in block ${receipt.blockNumber}`);
+            return { success: true, txHash: tx.hash };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // For retryables, check if already redeemed
+            if (isRetryable &&
+                (message.includes("REDEEMED") ||
+                    message.includes("already redeemed") ||
+                    message.includes("NoTicketWithID"))) {
+                console.log(`  Retryable already redeemed, treating as success`);
+                return { success: true };
+            }
+            if (!isRetryable || attempt >= RETRYABLE_MAX_RETRIES) {
+                return { success: false, error: message };
+            }
+            console.log(`  Retry ${attempt}/${RETRYABLE_MAX_RETRIES} failed: ${message}`);
+            console.log(`  Retrying in ${RETRYABLE_RETRY_DELAY_MS / 1000}s...`);
+            await new Promise((resolve) => setTimeout(resolve, RETRYABLE_RETRY_DELAY_MS));
+        }
+    }
+    return { success: false, error: "Unexpected retry loop exit" };
+}
+// ============================================================================
+// Output Formatting
+// ============================================================================
+function formatDryRun(prepared) {
+    const lines = [
+        `[DRY RUN] ${prepared.description}`,
+        `  Chain: ${prepared.chain}`,
+        `  To: ${prepared.to}`,
+    ];
+    if (prepared.operationId)
+        lines.push(`  OperationId: ${prepared.operationId}`);
+    if (prepared.value !== "0")
+        lines.push(`  Value: ${prepared.value}`);
+    lines.push(`  Data: ${prepared.data}`);
+    if (prepared.hashValidation) {
+        lines.push(prepared.hashValidation.isValid
+            ? `  Hash Valid: YES`
+            : `  WARNING: Hash validation failed - ${prepared.hashValidation.error}`);
+    }
+    return lines.join("\n");
+}
+function formatTrackingResult(result, label) {
+    const lines = [];
+    if (label)
+        lines.push(`--- ${label} ---`);
+    const timelockStage = result.stages.find((s) => s.type === "L2_TIMELOCK");
+    const operationId = timelockStage?.data.operationId;
+    const isSecurityCouncil = timelockStage?.data.isSecurityCouncilOperation === true;
+    const scNonce = timelockStage?.data.securityCouncilNonce;
+    if (operationId)
+        lines.push(`OperationId: ${operationId}`);
+    if (isSecurityCouncil && scNonce)
+        lines.push(`Security Council Nonce: ${scNonce}`);
+    if (result.isElection)
+        lines.push(`Type: createElection`);
+    lines.push(`Complete: ${result.isComplete}`);
+    lines.push(`Stages: ${result.stages.length}\n`);
+    for (let i = 0; i < result.stages.length; i++) {
+        const stage = result.stages[i];
+        const title = (0, index_1.formatStageTitle)(stage.type);
+        // Transaction links
+        const txLines = [];
+        for (const tx of stage.transactions) {
+            const desc = tx.description ?? "tx";
+            txLines.push(`      ${desc}: ${tx.hash}\n        ${(0, index_1.getStageTransactionUrl)(tx)}`);
+        }
+        // ETA info
+        let etaInfo = "";
+        if (stage.timing?.eta) {
+            etaInfo = ` | ETA: ${new Date(stage.timing.eta * 1000).toISOString()}`;
+        }
+        else if (stage.status === "NOT_STARTED") {
+            const expectedEta = (0, index_1.calculateExpectedEta)(result.stages, i);
+            if (expectedEta) {
+                etaInfo = ` | Expected: ~${new Date(expectedEta * 1000).toISOString()}`;
+            }
+        }
+        // Retryable info
+        let retryableInfo = "";
+        if (stage.type === "RETRYABLE_EXECUTED") {
+            const ticketCount = stage.data.ticketCount;
+            const creationDetails = stage.data.creationDetails;
+            const redeemedCount = stage.data.redeemedCount;
+            const pendingCount = stage.data.pendingCount;
+            if (ticketCount && ticketCount > 0) {
+                const arb1Count = creationDetails?.filter((d) => d.targetChain === "Arb1").length ?? 0;
+                const novaCount = creationDetails?.filter((d) => d.targetChain === "Nova").length ?? 0;
+                const chains = [arb1Count > 0 && `${arb1Count} Arb1`, novaCount > 0 && `${novaCount} Nova`]
+                    .filter(Boolean)
+                    .join(", ");
+                retryableInfo = ` [${ticketCount} ticket${ticketCount !== 1 ? "s" : ""}: ${chains}`;
+                if (stage.status === "COMPLETED") {
+                    retryableInfo += ` - all redeemed]`;
+                }
+                else if (pendingCount && pendingCount > 0) {
+                    retryableInfo += ` - ${redeemedCount ?? 0} redeemed, ${pendingCount} pending]`;
+                }
+                else {
+                    retryableInfo += `]`;
+                }
+            }
+        }
+        lines.push(`  ${title}: ${stage.status}${retryableInfo}${etaInfo}`);
+        lines.push(...txLines);
+    }
+    return lines.join("\n").concat("\n");
+}
+function formatStagesBrief(stages) {
+    const summary = (0, index_1.getTrackingStatusSummary)(stages);
+    const current = (0, index_1.getCurrentStage)(stages);
+    const title = current ? (0, index_1.formatStageTitle)(current.type) : "Complete";
+    return `${title}: ${current?.status ?? "DONE"} (${summary.completed}/${summary.total})`;
+}
+function formatCacheStatus(checkpoints) {
+    let proposalTotal = 0, proposalComplete = 0, proposalActive = 0, proposalFailed = 0;
+    let timelockTotal = 0, timelockComplete = 0, timelockActive = 0, timelockFailed = 0;
+    let electionTotal = 0, electionComplete = 0;
+    for (const [, checkpoint] of checkpoints) {
+        const stages = checkpoint.cachedData?.completedStages ?? [];
+        const isComplete = stages.length > 0 && (0, index_1.areAllStagesComplete)(stages);
+        const errorCount = checkpoint.metadata?.errorCount ?? 0;
+        const isFailed = errorCount >= exports.MAX_CONSECUTIVE_ERRORS;
+        const input = checkpoint.input;
+        if (input.type === "governor") {
+            if ((0, index_1.isElectionGovernor)(input.governorAddress)) {
+                electionTotal++;
+                if (isComplete)
+                    electionComplete++;
+            }
+            else {
+                proposalTotal++;
+                if (isComplete)
+                    proposalComplete++;
+                else if (isFailed)
+                    proposalFailed++;
+                else
+                    proposalActive++;
+            }
+        }
+        else if (input.type === "timelock") {
+            timelockTotal++;
+            if (isComplete)
+                timelockComplete++;
+            else if (isFailed)
+                timelockFailed++;
+            else
+                timelockActive++;
+        }
+    }
+    const lines = [
+        `Total cached: ${checkpoints.size}`,
+        ``,
+        `Proposals: ${proposalTotal}`,
+        `  Complete: ${proposalComplete}`,
+        `  Active: ${proposalActive}`,
+    ];
+    if (proposalFailed > 0)
+        lines.push(`  Failed: ${proposalFailed}`);
+    lines.push(``, `Timelock Ops: ${timelockTotal}`, `  Complete: ${timelockComplete}`, `  Active: ${timelockActive}`);
+    if (timelockFailed > 0)
+        lines.push(`  Failed: ${timelockFailed}`);
+    if (electionTotal > 0)
+        lines.push(``, `Elections: ${electionTotal} (${electionComplete} complete)`);
+    return lines.join("\n");
+}
+// ============================================================================
+// Loop Runner
+// ============================================================================
+async function waitWithChunks(ms) {
+    const MAX_CHUNK = 60 * 60 * 1000; // 1 hour max per chunk
+    let remaining = ms;
+    while (remaining > 0) {
+        await new Promise((resolve) => setTimeout(resolve, Math.min(remaining, MAX_CHUNK)));
+        remaining -= MAX_CHUNK;
+    }
+}
+async function runWithLoop(cycleFn, options) {
+    if (!options.loop) {
+        await cycleFn();
+        return;
+    }
+    let consecutiveErrors = 0;
+    let running = true;
+    process.on("SIGINT", () => {
+        running = false;
+        console.log("\nGracefully shutting down...");
+    });
+    while (running) {
+        try {
+            await cycleFn();
+            consecutiveErrors = 0;
+        }
+        catch (error) {
+            console.error("Cycle error:", error.message);
+            consecutiveErrors = Math.min(consecutiveErrors + 1, 10);
+            const backoffMs = Math.min(5000 * Math.pow(2, consecutiveErrors - 1), 300000);
+            console.log(`Backing off for ${backoffMs / 1000}s after ${consecutiveErrors} consecutive errors`);
+            await waitWithChunks(backoffMs);
+        }
+        if (options.healthCheckUrl) {
+            try {
+                await fetch(options.healthCheckUrl, { method: "GET" });
+            }
+            catch {
+                // Silently ignore health check errors
+            }
+        }
+        if (running)
+            await waitWithChunks(options.intervalMs);
+    }
+}
+// ============================================================================
+// Stage Preparation
+// ============================================================================
+const PREPARABLE_STAGE_TYPES = [
+    "L2_TIMELOCK",
+    "L1_TIMELOCK",
+    "L2_TO_L1_MESSAGE",
+    "RETRYABLE_EXECUTED",
+];
+async function prepareStagesForResult(tracker, stages, options) {
+    const preparations = [];
+    let prepared;
+    let count = 0;
+    if (!options.prepare)
+        return { preparations, count };
+    if (options.force) {
+        // Historical validation: prepare COMPLETED timelock stages
+        for (const stage of stages) {
+            if (stage.status === "COMPLETED" && (0, index_1.isTimelockStage)(stage.type)) {
+                const prepResult = await tracker.prepareTransaction(stage, { force: true });
+                preparations.push(prepResult);
+                if (prepResult.success) {
+                    count++;
+                    prepared = prepResult.prepared;
+                }
+            }
+        }
+    }
+    else if (options.preparePending) {
+        // Pre-execution: prepare PENDING stages
+        for (const stage of stages) {
+            const isPreparable = PREPARABLE_STAGE_TYPES.includes(stage.type);
+            if (isPreparable && stage.status === "PENDING") {
+                const prepResult = await tracker.prepareTransaction(stage, { force: true });
+                preparations.push(prepResult);
+                if (prepResult.success) {
+                    count++;
+                    prepared = prepResult.prepared;
+                }
+            }
+        }
+    }
+    else {
+        // Normal: prepare only READY stages
+        const ready = (0, index_1.findExecutableStage)(stages);
+        if (ready) {
+            const prepResult = await tracker.prepareTransaction(ready, {});
+            preparations.push(prepResult);
+            if (prepResult.success) {
+                count++;
+                prepared = prepResult.prepared;
+            }
+        }
+    }
+    return { prepared, preparations, count };
+}
+// ============================================================================
+// Monitor Cycle
+// ============================================================================
+/** Create a short scope name from a tracking key */
+function shortScope(key) {
+    // "tx:0x1234...abcd" -> "0x1234..abcd"
+    if (key.startsWith("tx:0x")) {
+        const hash = key.slice(3);
+        return hash.slice(0, 6) + ".." + hash.slice(-4);
+    }
+    return key.slice(0, 12);
+}
+async function runMonitorCycle(tracker, l2Provider, options = {}) {
+    const tipBlock = await l2Provider.getBlockNumber();
+    const blockLag = options.blockLag ?? exports.DEFAULT_BLOCK_LAG;
+    const currentBlock = Math.max(0, tipBlock - blockLag);
+    const concurrency = options.concurrency ?? 1;
+    const limit = (0, p_limit_1.default)(concurrency);
+    // Optional startBlock override (watermarks are exclusive, so subtract 1)
+    const startBlockWatermarks = options.startBlock
+        ? {
+            constitutionalGovernor: options.startBlock - 1,
+            nonConstitutionalGovernor: options.startBlock - 1,
+            electionNomineeGovernor: options.startBlock - 1,
+            electionMemberGovernor: options.startBlock - 1,
+            l2ConstitutionalTimelock: options.startBlock - 1,
+            l2NonConstitutionalTimelock: options.startBlock - 1,
+        }
+        : undefined;
+    const targets = (0, index_1.buildDefaultTargets)();
+    const discoveryResult = await tracker.discoverAll(targets, currentBlock, startBlockWatermarks);
+    const result = { tracked: 0, prepared: 0, errors: 0, retracked: 0 };
+    const trackedKeys = new Set();
+    const trackedOperationIds = new Set();
+    async function track(key, trackFn) {
+        if (trackedKeys.has(key))
+            return;
+        trackedKeys.add(key);
+        // Wrap tracking in scope for debug logging
+        await (0, logger_1.withScope)(shortScope(key), async () => {
+            try {
+                const trackResult = await trackFn();
+                result.tracked++;
+                if (trackResult.timelockLink?.operationId) {
+                    trackedOperationIds.add(trackResult.timelockLink.operationId.toLowerCase());
+                }
+                const prepResult = await prepareStagesForResult(tracker, trackResult.stages, options);
+                result.prepared += prepResult.count;
+                const callbackResult = await options.onTrack?.({
+                    key,
+                    result: trackResult,
+                    prepared: prepResult.prepared,
+                });
+                if (callbackResult?.shouldRetrack) {
+                    trackedKeys.delete(key);
+                    await track(key, trackFn);
+                }
+            }
+            catch (error) {
+                result.errors++;
+                // Wrap error callback in try-catch to prevent nested errors from propagating
+                try {
+                    await options.onTrack?.({
+                        key,
+                        result: null,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                catch (callbackError) {
+                    // Log the callback error but don't let it mask the original error
+                    console.error(`Error in onTrack callback for ${key}:`, callbackError instanceof Error ? callbackError.message : String(callbackError));
+                }
+            }
+        });
+    }
+    // Query incomplete checkpoints first to avoid duplicate tracking
+    const maxAgeDays = options.maxAgeDays ?? exports.DEFAULT_MAX_AGE_DAYS;
+    const incompleteCheckpoints = await tracker.queryIncompleteCheckpoints({
+        maxAgeDays,
+        maxErrorCount: exports.MAX_CONSECUTIVE_ERRORS,
+    });
+    // Extract operationIds from governor checkpoints
+    const governorOperationIds = new Set();
+    for (const { checkpoint } of incompleteCheckpoints) {
+        if (checkpoint.input.type === "governor") {
+            const stages = checkpoint.cachedData.completedStages ?? [];
+            const opId = (0, index_1.extractOperationId)(stages);
+            if (opId)
+                governorOperationIds.add(opId.toLowerCase());
+        }
+    }
+    // Phase 1: Track proposals and incomplete governor checkpoints first
+    // This populates trackedOperationIds so we can filter TLOs correctly
+    const proposalTasks = [];
+    // 1a. Newly discovered proposals
+    for (const p of discoveryResult.proposals) {
+        const key = `tx:${p.creationTxHash.toLowerCase()}`;
+        proposalTasks.push({
+            key,
+            fn: async () => {
+                const results = await tracker.trackByTxHash(p.creationTxHash);
+                if (results.length === 0)
+                    throw new Error(`No proposal found in tx ${p.creationTxHash}`);
+                return results[0];
+            },
+        });
+    }
+    // 1b. Incomplete governor checkpoints to re-track (excluding elections)
+    const nonElectionCheckpoints = incompleteCheckpoints.filter(({ checkpoint }) => {
+        if (checkpoint.input.type === "governor")
+            return !(0, index_1.isElectionGovernor)(checkpoint.input.governorAddress);
+        return true;
+    });
+    result.retracked = nonElectionCheckpoints.length;
+    for (const { key, checkpoint } of nonElectionCheckpoints) {
+        if (checkpoint.input.type === "governor") {
+            proposalTasks.push({
+                key,
+                fn: () => tracker.trackFromCheckpoint(checkpoint),
+            });
+        }
+    }
+    // Run proposal tasks first to populate trackedOperationIds
+    await Promise.all(proposalTasks.map((task) => limit(() => track(task.key, task.fn))));
+    // Phase 2: Track TLOs (filter out those already tracked via proposals)
+    const timelockTasks = [];
+    // 2a. Newly discovered timelock operations (filter duplicates)
+    for (const op of discoveryResult.timelockOps) {
+        const opIdLower = op.operationId.toLowerCase();
+        // Skip if already tracked via proposal (either from cache or just tracked)
+        if (governorOperationIds.has(opIdLower))
+            continue;
+        if (trackedOperationIds.has(opIdLower))
+            continue;
+        const key = `tx:${op.scheduledTxHash.toLowerCase()}`;
+        timelockTasks.push({
+            key,
+            fn: async () => {
+                const results = await tracker.trackByTxHash(op.scheduledTxHash);
+                if (results.length === 0)
+                    throw new Error(`No timelock operation found in tx ${op.scheduledTxHash}`);
+                const matchingResult = results.find((r) => {
+                    if (r.input.type === "timelock")
+                        return r.input.operationId.toLowerCase() === opIdLower;
+                    return r.timelockLink?.operationId?.toLowerCase() === opIdLower;
+                });
+                trackedOperationIds.add(opIdLower);
+                return matchingResult ?? results[0];
+            },
+        });
+    }
+    // 2b. Incomplete timelock checkpoints to re-track
+    for (const { key, checkpoint } of nonElectionCheckpoints) {
+        if (checkpoint.input.type === "timelock") {
+            const operationId = checkpoint.input.operationId;
+            // Skip if already tracked via proposal
+            if (operationId && governorOperationIds.has(operationId.toLowerCase()))
+                continue;
+            if (operationId && trackedOperationIds.has(operationId.toLowerCase()))
+                continue;
+            timelockTasks.push({
+                key,
+                fn: () => tracker.trackFromCheckpoint(checkpoint),
+            });
+        }
+    }
+    // Run timelock tasks
+    await Promise.all(timelockTasks.map((task) => limit(() => track(task.key, task.fn))));
+    return {
+        result,
+        proposals: discoveryResult.proposals,
+        timelockOps: discoveryResult.timelockOps,
+        watermarks: discoveryResult.watermarks,
+    };
+}
+// ============================================================================
+// Track and Prepare (for single-item tracking)
+// ============================================================================
+async function trackAndPrepare(tracker, txHash, options = {}) {
+    const results = await tracker.trackByTxHash(txHash);
+    const preparations = [];
+    for (const result of results) {
+        const prepResult = await prepareStagesForResult(tracker, result.stages, options);
+        preparations.push(...prepResult.preparations);
+    }
+    return { results, preparations };
+}
+//# sourceMappingURL=cli.js.map