@spectratools/assembly-cli 0.6.0 → 0.8.1

package/dist/cli.js

@@ -4,7 +4,7 @@
 import { readFileSync, realpathSync } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
-import { Cli as Cli6, z as z6 } from "incur";
+import { Cli as Cli6, z as z7 } from "incur";
 
 // src/commands/_common.ts
 import { checksumAddress, weiToEth } from "@spectratools/cli-shared";
@@ -59,7 +59,8 @@ function jsonSafe(value) {
 }
 
 // src/commands/council.ts
-import { Cli, z } from "incur";
+import { Cli, z as z2 } from "incur";
+import { parseEther } from "viem";
 
 // src/contracts/CouncilSeats.abi.json
 var CouncilSeats_abi_default = [
@@ -4328,12 +4329,79 @@ function createAssemblyPublicClient(rpcUrl) {
     transport: http(rpcUrl ?? process.env.ABSTRACT_RPC_URL ?? "https://api.mainnet.abs.xyz")
   });
 }
+function createAssemblyWalletClient(account, rpcUrl) {
+  return createWalletClient({
+    account,
+    chain: abstractMainnet,
+    transport: http(rpcUrl ?? process.env.ABSTRACT_RPC_URL ?? "https://api.mainnet.abs.xyz")
+  });
+}
 
-// src/commands/council.ts
-var env = z.object({
+// src/commands/_write-utils.ts
+import {
+  createPrivateKeySigner,
+  executeTx
+} from "@spectratools/tx-shared";
+import { z } from "incur";
+var writeEnv = z.object({
+  PRIVATE_KEY: z.string().describe("Private key (0x-prefixed 32-byte hex) for signing transactions"),
   ABSTRACT_RPC_URL: z.string().optional().describe("Abstract RPC URL override")
 });
-var timestampOutput = z.union([z.number(), z.string()]);
+var writeOptions = z.object({
+  "dry-run": z.boolean().default(false).describe("Simulate the transaction without broadcasting"),
+  "gas-limit": z.string().optional().describe("Gas limit override (in gas units)"),
+  "max-fee": z.string().optional().describe("Max fee per gas override in wei (EIP-1559)"),
+  nonce: z.number().optional().describe("Nonce override")
+});
+function resolveAccount(env6) {
+  const signer = createPrivateKeySigner(env6.PRIVATE_KEY);
+  return signer.account;
+}
+function formatTxResult(result) {
+  if (result.status === "dry-run") {
+    return {
+      status: "dry-run",
+      estimatedGas: result.estimatedGas.toString(),
+      simulationResult: jsonSafe(result.simulationResult)
+    };
+  }
+  return {
+    status: result.status,
+    hash: result.hash,
+    blockNumber: Number(result.blockNumber),
+    gasUsed: result.gasUsed.toString(),
+    from: result.from,
+    to: result.to,
+    ...result.effectiveGasPrice !== void 0 ? { effectiveGasPrice: result.effectiveGasPrice.toString() } : {}
+  };
+}
+async function assemblyWriteTx(opts) {
+  const { env: env6, options, address, abi, functionName, args, value } = opts;
+  const account = resolveAccount(env6);
+  const publicClient = createAssemblyPublicClient(env6.ABSTRACT_RPC_URL);
+  const walletClient = createAssemblyWalletClient(account, env6.ABSTRACT_RPC_URL);
+  const result = await executeTx({
+    publicClient,
+    walletClient,
+    account,
+    address,
+    abi,
+    functionName,
+    ...args !== void 0 ? { args } : {},
+    ...value !== void 0 ? { value } : {},
+    dryRun: options["dry-run"],
+    ...options["gas-limit"] ? { gasLimit: BigInt(options["gas-limit"]) } : {},
+    ...options["max-fee"] ? { maxFeePerGas: BigInt(options["max-fee"]) } : {},
+    ...options.nonce !== void 0 ? { nonce: options.nonce } : {}
+  });
+  return formatTxResult(result);
+}
+
+// src/commands/council.ts
+var env = z2.object({
+  ABSTRACT_RPC_URL: z2.string().optional().describe("Abstract RPC URL override")
+});
+var timestampOutput = z2.union([z2.number(), z2.string()]);
 function decodeSeat(value) {
   const [owner, startAt, endAt, forfeited] = value;
   return { owner, startAt, endAt, forfeited };
@@ -4342,10 +4410,14 @@ function decodeAuction(value) {
   const [highestBidder, highestBid, settled] = value;
   return { highestBidder, highestBid, settled };
 }
-function deriveAuctionStatus(params) {
-  if (params.settled) return "settled";
-  if (params.currentTimestamp < params.windowEnd) return "bidding";
-  return "closed";
+function deriveAuctionExecutionState(params) {
+  if (params.settled) return { executionStatus: "settled", bidExecutableNow: false };
+  const isCurrentAuctionSlot = params.day === Number(params.currentAuctionDay) && params.slot === Number(params.currentAuctionSlot);
+  if (params.currentTimestamp < params.windowEnd) {
+    if (isCurrentAuctionSlot) return { executionStatus: "open_now", bidExecutableNow: true };
+    return { executionStatus: "upcoming", bidExecutableNow: false };
+  }
+  return { executionStatus: "closed_unsettled", bidExecutableNow: false };
 }
 var council = Cli.create("council", {
   description: "Inspect council seats, members, auctions, and seat parameters."
@@ -4353,15 +4425,15 @@ var council = Cli.create("council", {
 council.command("seats", {
   description: "List all council seats and their occupancy windows.",
   env,
-  output: z.array(
-    z.object({
-      id: z.number(),
-      owner: z.string(),
+  output: z2.array(
+    z2.object({
+      id: z2.number(),
+      owner: z2.string(),
       startAt: timestampOutput,
-      startAtRelative: z.string(),
+      startAtRelative: z2.string(),
       endAt: timestampOutput,
-      endAtRelative: z.string(),
-      forfeited: z.boolean()
+      endAtRelative: z2.string(),
+      forfeited: z2.boolean()
     })
   ),
   examples: [{ description: "List all council seats" }],
@@ -4398,17 +4470,17 @@ council.command("seats", {
 });
 council.command("seat", {
   description: "Get detailed seat information for a specific seat id.",
-  args: z.object({
-    id: z.coerce.number().int().nonnegative().describe("Seat id (0-indexed)")
+  args: z2.object({
+    id: z2.coerce.number().int().nonnegative().describe("Seat id (0-indexed)")
   }),
   env,
-  output: z.object({
-    id: z.number(),
-    owner: z.string(),
+  output: z2.object({
+    id: z2.number(),
+    owner: z2.string(),
     startAt: timestampOutput,
     endAt: timestampOutput,
-    forfeited: z.boolean(),
-    endAtRelative: z.string()
+    forfeited: z2.boolean(),
+    endAtRelative: z2.string()
   }),
   examples: [{ args: { id: 0 }, description: "Inspect seat #0" }],
   async run(c) {
@@ -4445,10 +4517,10 @@ council.command("seat", {
 council.command("members", {
   description: "List currently active council members and voting power.",
   env,
-  output: z.array(
-    z.object({
-      address: z.string(),
-      votingPower: z.number()
+  output: z2.array(
+    z2.object({
+      address: z2.string(),
+      votingPower: z2.number()
     })
   ),
   examples: [{ description: "List active council members" }],
@@ -4494,13 +4566,13 @@ council.command("members", {
 });
 council.command("is-member", {
   description: "Check whether an address is currently a council member.",
-  args: z.object({
-    address: z.string().describe("Address to check")
+  args: z2.object({
+    address: z2.string().describe("Address to check")
   }),
   env,
-  output: z.object({
-    address: z.string(),
-    isMember: z.boolean()
+  output: z2.object({
+    address: z2.string(),
+    isMember: z2.boolean()
   }),
   examples: [
     {
@@ -4521,13 +4593,13 @@ council.command("is-member", {
 });
 council.command("voting-power", {
   description: "Get the current voting power for an address.",
-  args: z.object({
-    address: z.string().describe("Address to inspect")
+  args: z2.object({
+    address: z2.string().describe("Address to inspect")
   }),
   env,
-  output: z.object({
-    address: z.string(),
-    votingPower: z.number()
+  output: z2.object({
+    address: z2.string(),
+    votingPower: z2.number()
   }),
   examples: [
     {
@@ -4549,19 +4621,21 @@ council.command("voting-power", {
 council.command("auctions", {
   description: "List recent and current council auction slots and leading bids.",
   env,
-  output: z.object({
-    currentDay: z.number(),
-    currentSlot: z.number(),
-    auctions: z.array(
-      z.object({
-        day: z.number(),
-        slot: z.number(),
-        highestBidder: z.string(),
-        highestBid: z.string(),
-        settled: z.boolean(),
+  output: z2.object({
+    currentDay: z2.number(),
+    currentSlot: z2.number(),
+    auctions: z2.array(
+      z2.object({
+        day: z2.number(),
+        slot: z2.number(),
+        highestBidder: z2.string(),
+        highestBid: z2.string(),
+        settled: z2.boolean(),
         windowEnd: timestampOutput,
-        windowEndRelative: z.string(),
-        status: z.enum(["bidding", "closed", "settled"])
+        windowEndRelative: z2.string(),
+        bidExecutableNow: z2.boolean(),
+        executionStatus: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"]),
+        status: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"])
       })
     )
   }),
@@ -4619,19 +4693,27 @@ council.command("auctions", {
         currentSlot: asNum(slot),
         auctions: recent.map((x, i) => {
           const windowEnd = windowEnds[i];
+          const dayValue = Number(x.day);
+          const execution = deriveAuctionExecutionState({
+            day: dayValue,
+            slot: x.slot,
+            currentAuctionDay: day,
+            currentAuctionSlot: slot,
+            settled: auctions[i].settled,
+            windowEnd,
+            currentTimestamp
+          });
           return {
-            day: Number(x.day),
+            day: dayValue,
             slot: x.slot,
             highestBidder: toChecksum(auctions[i].highestBidder),
             highestBid: eth(auctions[i].highestBid),
             settled: auctions[i].settled,
             windowEnd: timeValue(windowEnd, c.format),
             windowEndRelative: relTime(windowEnd),
-            status: deriveAuctionStatus({
-              settled: auctions[i].settled,
-              windowEnd,
-              currentTimestamp
-            })
+            bidExecutableNow: execution.bidExecutableNow,
+            executionStatus: execution.executionStatus,
+            status: execution.executionStatus
           };
         })
       },
@@ -4649,20 +4731,22 @@ council.command("auctions", {
 });
 council.command("auction", {
   description: "Get one auction slot by day + slot.",
-  args: z.object({
-    day: z.coerce.number().int().nonnegative().describe("Auction day index"),
-    slot: z.coerce.number().int().nonnegative().describe("Slot index within day")
+  args: z2.object({
+    day: z2.coerce.number().int().nonnegative().describe("Auction day index"),
+    slot: z2.coerce.number().int().nonnegative().describe("Slot index within day")
   }),
   env,
-  output: z.object({
-    day: z.number(),
-    slot: z.number(),
-    highestBidder: z.string(),
-    highestBid: z.string(),
-    settled: z.boolean(),
+  output: z2.object({
+    day: z2.number(),
+    slot: z2.number(),
+    highestBidder: z2.string(),
+    highestBid: z2.string(),
+    settled: z2.boolean(),
     windowEnd: timestampOutput,
-    windowEndRelative: z.string(),
-    status: z.enum(["bidding", "closed", "settled"])
+    windowEndRelative: z2.string(),
+    bidExecutableNow: z2.boolean(),
+    executionStatus: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"]),
+    status: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"])
   }),
   examples: [{ args: { day: 0, slot: 0 }, description: "Inspect day 0, slot 0 auction" }],
   async run(c) {
@@ -4679,7 +4763,7 @@ council.command("auction", {
         retryable: false
       });
     }
-    const [auctionTuple, windowEnd, latestBlock] = await Promise.all([
+    const [auctionTuple, windowEnd, latestBlock, currentAuctionDay, currentAuctionSlot] = await Promise.all([
       client.readContract({
         abi: councilSeatsAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
@@ -4692,11 +4776,30 @@ council.command("auction", {
         functionName: "auctionWindowEnd",
         args: [BigInt(c.args.day), c.args.slot]
       }),
-      client.getBlock({ blockTag: "latest" })
+      client.getBlock({ blockTag: "latest" }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionDay"
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionSlot"
+      })
     ]);
     const auction = decodeAuction(auctionTuple);
     const windowEndTimestamp = windowEnd;
     const currentTimestamp = latestBlock.timestamp;
+    const execution = deriveAuctionExecutionState({
+      day: c.args.day,
+      slot: c.args.slot,
+      currentAuctionDay,
+      currentAuctionSlot,
+      settled: auction.settled,
+      windowEnd: windowEndTimestamp,
+      currentTimestamp
+    });
     return c.ok({
       day: c.args.day,
       slot: c.args.slot,
@@ -4705,24 +4808,22 @@ council.command("auction", {
       settled: auction.settled,
       windowEnd: timeValue(windowEndTimestamp, c.format),
       windowEndRelative: relTime(windowEndTimestamp),
-      status: deriveAuctionStatus({
-        settled: auction.settled,
-        windowEnd: windowEndTimestamp,
-        currentTimestamp
-      })
+      bidExecutableNow: execution.bidExecutableNow,
+      executionStatus: execution.executionStatus,
+      status: execution.executionStatus
     });
   }
 });
 council.command("pending-refund", {
   description: "Get pending refundable bid amount for an address.",
-  args: z.object({
-    address: z.string().describe("Bidder address")
+  args: z2.object({
+    address: z2.string().describe("Bidder address")
   }),
   env,
-  output: z.object({
-    address: z.string(),
-    pendingRefund: z.string(),
-    pendingRefundWei: z.string()
+  output: z2.object({
+    address: z2.string(),
+    pendingRefund: z2.string(),
+    pendingRefundWei: z2.string()
   }),
   examples: [
     {
@@ -4748,13 +4849,13 @@ council.command("pending-refund", {
 council.command("params", {
   description: "Read council seat term and auction scheduling parameters.",
   env,
-  output: z.object({
-    SEAT_TERM: z.number(),
-    AUCTION_SLOT_DURATION: z.number(),
-    AUCTION_SLOTS_PER_DAY: z.number(),
-    auctionEpochStart: z.number(),
-    auctionWindowStart: z.number(),
-    auctionWindowEnd: z.number()
+  output: z2.object({
+    SEAT_TERM: z2.number(),
+    AUCTION_SLOT_DURATION: z2.number(),
+    AUCTION_SLOTS_PER_DAY: z2.number(),
+    auctionEpochStart: z2.number(),
+    auctionWindowStart: z2.number(),
+    auctionWindowEnd: z2.number()
   }),
   examples: [{ description: "Inspect council seat + auction timing constants" }],
   async run(c) {
@@ -4805,13 +4906,347 @@ council.command("params", {
     });
   }
 });
+var txResultOutput = z2.union([
+  z2.object({
+    status: z2.enum(["success", "reverted"]),
+    hash: z2.string(),
+    blockNumber: z2.number(),
+    gasUsed: z2.string(),
+    from: z2.string(),
+    to: z2.string().nullable(),
+    effectiveGasPrice: z2.string().optional()
+  }),
+  z2.object({
+    status: z2.literal("dry-run"),
+    estimatedGas: z2.string(),
+    simulationResult: z2.unknown()
+  })
+]);
+council.command("bid", {
+  description: "Place a bid on a council seat auction (payable).",
+  hint: "Requires PRIVATE_KEY environment variable for signing.",
+  args: z2.object({
+    day: z2.coerce.number().int().nonnegative().describe("Auction day index"),
+    slot: z2.coerce.number().int().nonnegative().describe("Slot index within day")
+  }),
+  options: writeOptions.extend({
+    amount: z2.string().describe('ETH amount to bid (e.g. "0.1")')
+  }),
+  env: writeEnv,
+  output: z2.object({
+    day: z2.number(),
+    slot: z2.number(),
+    bidAmount: z2.string(),
+    tx: txResultOutput
+  }),
+  examples: [
+    {
+      args: { day: 0, slot: 0 },
+      options: { amount: "0.1" },
+      description: "Bid 0.1 ETH on day 0, slot 0"
+    }
+  ],
+  async run(c) {
+    const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    let amountWei;
+    try {
+      amountWei = parseEther(c.options.amount);
+    } catch {
+      return c.error({
+        code: "INVALID_AMOUNT",
+        message: `Invalid ETH amount: "${c.options.amount}". Provide a decimal number (e.g. "0.1").`,
+        retryable: false
+      });
+    }
+    if (amountWei <= 0n) {
+      return c.error({
+        code: "INVALID_AMOUNT",
+        message: "Bid amount must be greater than zero.",
+        retryable: false
+      });
+    }
+    const slotsPerDay = await client.readContract({
+      abi: councilSeatsAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+      functionName: "AUCTION_SLOTS_PER_DAY"
+    });
+    if (c.args.slot >= Number(slotsPerDay)) {
+      return c.error({
+        code: "OUT_OF_RANGE",
+        message: `Slot ${c.args.slot} does not exist (max: ${Number(slotsPerDay) - 1})`,
+        retryable: false
+      });
+    }
+    const [auctionTuple, windowEnd, latestBlock, currentAuctionDay, currentAuctionSlot] = await Promise.all([
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "auctions",
+        args: [BigInt(c.args.day), c.args.slot]
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "auctionWindowEnd",
+        args: [BigInt(c.args.day), c.args.slot]
+      }),
+      client.getBlock({ blockTag: "latest" }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionDay"
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionSlot"
+      })
+    ]);
+    const auction = decodeAuction(auctionTuple);
+    const windowEndTimestamp = windowEnd;
+    const currentTimestamp = latestBlock.timestamp;
+    const execution = deriveAuctionExecutionState({
+      day: c.args.day,
+      slot: c.args.slot,
+      currentAuctionDay,
+      currentAuctionSlot,
+      settled: auction.settled,
+      windowEnd: windowEndTimestamp,
+      currentTimestamp
+    });
+    if (execution.executionStatus === "settled") {
+      return c.error({
+        code: "AUCTION_SETTLED",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is already settled. Winner: ${toChecksum(auction.highestBidder)}.`,
+        retryable: false
+      });
+    }
+    if (execution.executionStatus === "upcoming") {
+      return c.error({
+        code: "AUCTION_NOT_ACTIVE",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is not the currently active slot. Current bid-executable slot is day=${Number(currentAuctionDay)}, slot=${Number(currentAuctionSlot)}.`,
+        retryable: false
+      });
+    }
+    if (execution.executionStatus === "closed_unsettled") {
+      return c.error({
+        code: "AUCTION_CLOSED",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) bidding window has ended. Use "council settle" instead.`,
+        retryable: false
+      });
+    }
+    if (auction.highestBid >= amountWei) {
+      return c.error({
+        code: "BID_TOO_LOW",
+        message: `Bid of ${c.options.amount} ETH is not higher than current highest bid of ${eth(auction.highestBid)}. Increase your bid amount.`,
+        retryable: false
+      });
+    }
+    const txResult = await assemblyWriteTx({
+      env: c.env,
+      options: c.options,
+      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+      abi: councilSeatsAbi,
+      functionName: "bid",
+      args: [BigInt(c.args.day), c.args.slot],
+      value: amountWei
+    });
+    return c.ok(
+      {
+        day: c.args.day,
+        slot: c.args.slot,
+        bidAmount: `${c.options.amount} ETH`,
+        tx: txResult
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "council auction",
+              args: { day: String(c.args.day), slot: String(c.args.slot) },
+              description: "Check auction status"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+council.command("settle", {
+  description: "Settle a completed council seat auction.",
+  hint: "Requires PRIVATE_KEY environment variable for signing.",
+  args: z2.object({
+    day: z2.coerce.number().int().nonnegative().describe("Auction day index"),
+    slot: z2.coerce.number().int().nonnegative().describe("Slot index within day")
+  }),
+  options: writeOptions,
+  env: writeEnv,
+  output: z2.object({
+    day: z2.number(),
+    slot: z2.number(),
+    highestBidder: z2.string(),
+    highestBid: z2.string(),
+    tx: txResultOutput
+  }),
+  examples: [
+    {
+      args: { day: 0, slot: 0 },
+      description: "Settle the auction for day 0, slot 0"
+    }
+  ],
+  async run(c) {
+    const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const slotsPerDay = await client.readContract({
+      abi: councilSeatsAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+      functionName: "AUCTION_SLOTS_PER_DAY"
+    });
+    if (c.args.slot >= Number(slotsPerDay)) {
+      return c.error({
+        code: "OUT_OF_RANGE",
+        message: `Slot ${c.args.slot} does not exist (max: ${Number(slotsPerDay) - 1})`,
+        retryable: false
+      });
+    }
+    const [auctionTuple, windowEnd, latestBlock, currentAuctionDay, currentAuctionSlot] = await Promise.all([
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "auctions",
+        args: [BigInt(c.args.day), c.args.slot]
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "auctionWindowEnd",
+        args: [BigInt(c.args.day), c.args.slot]
+      }),
+      client.getBlock({ blockTag: "latest" }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionDay"
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionSlot"
+      })
+    ]);
+    const auction = decodeAuction(auctionTuple);
+    const windowEndTimestamp = windowEnd;
+    const currentTimestamp = latestBlock.timestamp;
+    const execution = deriveAuctionExecutionState({
+      day: c.args.day,
+      slot: c.args.slot,
+      currentAuctionDay,
+      currentAuctionSlot,
+      settled: auction.settled,
+      windowEnd: windowEndTimestamp,
+      currentTimestamp
+    });
+    if (execution.executionStatus === "settled") {
+      return c.error({
+        code: "ALREADY_SETTLED",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is already settled.`,
+        retryable: false
+      });
+    }
+    if (execution.executionStatus === "open_now") {
+      return c.error({
+        code: "AUCTION_STILL_ACTIVE",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is still accepting bids. Window ends ${relTime(windowEndTimestamp)}.`,
+        retryable: false
+      });
+    }
+    if (execution.executionStatus === "upcoming") {
+      return c.error({
+        code: "AUCTION_STILL_ACTIVE",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is not yet the active slot. Current slot is day=${Number(currentAuctionDay)}, slot=${Number(currentAuctionSlot)}.`,
+        retryable: false
+      });
+    }
+    const txResult = await assemblyWriteTx({
+      env: c.env,
+      options: c.options,
+      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+      abi: councilSeatsAbi,
+      functionName: "settleAuction",
+      args: [BigInt(c.args.day), c.args.slot]
+    });
+    return c.ok(
+      {
+        day: c.args.day,
+        slot: c.args.slot,
+        highestBidder: toChecksum(auction.highestBidder),
+        highestBid: eth(auction.highestBid),
+        tx: txResult
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "council seats",
+              description: "View updated council seats"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+council.command("withdraw-refund", {
+  description: "Withdraw pending bid refunds for the signer address.",
+  hint: "Requires PRIVATE_KEY environment variable for signing.",
+  options: writeOptions,
+  env: writeEnv,
+  output: z2.object({
+    address: z2.string(),
+    refundAmount: z2.string(),
+    refundAmountWei: z2.string(),
+    tx: txResultOutput.optional()
+  }),
+  examples: [{ description: "Withdraw all pending bid refunds" }],
+  async run(c) {
+    const account = resolveAccount(c.env);
+    const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const pendingAmount = await client.readContract({
+      abi: councilSeatsAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+      functionName: "pendingReturns",
+      args: [account.address]
+    });
+    if (pendingAmount === 0n) {
+      return c.ok({
+        address: toChecksum(account.address),
+        refundAmount: "0 ETH",
+        refundAmountWei: "0"
+      });
+    }
+    const txResult = await assemblyWriteTx({
+      env: c.env,
+      options: c.options,
+      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+      abi: councilSeatsAbi,
+      functionName: "withdrawRefund"
+    });
+    return c.ok({
+      address: toChecksum(account.address),
+      refundAmount: eth(pendingAmount),
+      refundAmountWei: pendingAmount.toString(),
+      tx: txResult
+    });
+  }
+});
 
 // src/commands/forum.ts
-import { Cli as Cli2, z as z2 } from "incur";
-var env2 = z2.object({
-  ABSTRACT_RPC_URL: z2.string().optional().describe("Abstract RPC URL override")
+import { Cli as Cli2, z as z3 } from "incur";
+var env2 = z3.object({
+  ABSTRACT_RPC_URL: z3.string().optional().describe("Abstract RPC URL override")
 });
-var timestampOutput2 = z2.union([z2.number(), z2.string()]);
+var timestampOutput2 = z3.union([z3.number(), z3.string()]);
 function decodeThread(value) {
   const [id, kind, author, createdAt, category, title, body, proposalId, petitionId] = value;
   return {
@@ -4869,19 +5304,19 @@ var forum = Cli2.create("forum", {
 forum.command("threads", {
   description: "List forum threads with author and creation metadata.",
   env: env2,
-  output: z2.object({
-    threads: z2.array(
-      z2.object({
-        id: z2.number(),
-        kind: z2.number(),
-        author: z2.string(),
+  output: z3.object({
+    threads: z3.array(
+      z3.object({
+        id: z3.number(),
+        kind: z3.number(),
+        author: z3.string(),
         createdAt: timestampOutput2,
-        createdAtRelative: z2.string(),
-        category: z2.string().nullable().optional(),
-        title: z2.string().nullable().optional()
+        createdAtRelative: z3.string(),
+        category: z3.string().nullable().optional(),
+        title: z3.string().nullable().optional()
       })
     ),
-    count: z2.number()
+    count: z3.number()
   }),
   examples: [{ description: "List all forum threads" }],
   async run(c) {
@@ -4930,13 +5365,13 @@ forum.command("threads", {
 });
 forum.command("thread", {
   description: "Get one thread and all comments associated with it.",
-  args: z2.object({
-    id: z2.coerce.number().int().positive().describe("Thread id (1-indexed)")
+  args: z3.object({
+    id: z3.coerce.number().int().positive().describe("Thread id (1-indexed)")
   }),
   env: env2,
-  output: z2.object({
-    thread: z2.record(z2.string(), z2.unknown()),
-    comments: z2.array(z2.record(z2.string(), z2.unknown()))
+  output: z3.object({
+    thread: z3.record(z3.string(), z3.unknown()),
+    comments: z3.array(z3.record(z3.string(), z3.unknown()))
   }),
   examples: [{ args: { id: 1 }, description: "Fetch thread #1 and its comments" }],
   async run(c) {
@@ -4986,11 +5421,11 @@ forum.command("thread", {
 });
 forum.command("comments", {
   description: "List comments for a thread id.",
-  args: z2.object({
-    threadId: z2.coerce.number().int().positive().describe("Thread id to filter comments by")
+  args: z3.object({
+    threadId: z3.coerce.number().int().positive().describe("Thread id to filter comments by")
   }),
   env: env2,
-  output: z2.array(z2.record(z2.string(), z2.unknown())),
+  output: z3.array(z3.record(z3.string(), z3.unknown())),
   examples: [{ args: { threadId: 1 }, description: "List comments for thread #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
@@ -5017,11 +5452,11 @@ forum.command("comments", {
 });
 forum.command("comment", {
   description: "Get one comment by comment id.",
-  args: z2.object({
-    id: z2.coerce.number().int().positive().describe("Comment id (1-indexed)")
+  args: z3.object({
+    id: z3.coerce.number().int().positive().describe("Comment id (1-indexed)")
   }),
   env: env2,
-  output: z2.record(z2.string(), z2.unknown()),
+  output: z3.record(z3.string(), z3.unknown()),
   examples: [{ args: { id: 1 }, description: "Fetch comment #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
@@ -5049,7 +5484,7 @@ forum.command("comment", {
 forum.command("petitions", {
   description: "List petitions submitted in the forum contract.",
   env: env2,
-  output: z2.array(z2.record(z2.string(), z2.unknown())),
+  output: z3.array(z3.record(z3.string(), z3.unknown())),
   examples: [{ description: "List all petitions" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
@@ -5074,11 +5509,11 @@ forum.command("petitions", {
 });
 forum.command("petition", {
   description: "Get one petition plus whether proposer already signed it.",
-  args: z2.object({
-    id: z2.coerce.number().int().positive().describe("Petition id (1-indexed)")
+  args: z3.object({
+    id: z3.coerce.number().int().positive().describe("Petition id (1-indexed)")
   }),
   env: env2,
-  output: z2.object({ proposerSigned: z2.boolean() }).passthrough(),
+  output: z3.object({ proposerSigned: z3.boolean() }).passthrough(),
   examples: [{ args: { id: 1 }, description: "Fetch petition #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
@@ -5113,15 +5548,15 @@ forum.command("petition", {
 });
 forum.command("has-signed", {
   description: "Check whether an address signed a petition.",
-  args: z2.object({
-    petitionId: z2.coerce.number().int().positive().describe("Petition id (1-indexed)"),
-    address: z2.string().describe("Signer address to check")
+  args: z3.object({
+    petitionId: z3.coerce.number().int().positive().describe("Petition id (1-indexed)"),
+    address: z3.string().describe("Signer address to check")
   }),
   env: env2,
-  output: z2.object({
-    petitionId: z2.number(),
-    address: z2.string(),
-    hasSigned: z2.boolean()
+  output: z3.object({
+    petitionId: z3.number(),
+    address: z3.string(),
+    hasSigned: z3.boolean()
   }),
   examples: [
     {
@@ -5146,11 +5581,11 @@ forum.command("has-signed", {
 forum.command("stats", {
   description: "Read top-level forum counters and petition threshold.",
   env: env2,
-  output: z2.object({
-    threadCount: z2.number(),
-    commentCount: z2.number(),
-    petitionCount: z2.number(),
-    petitionThresholdBps: z2.number()
+  output: z3.object({
+    threadCount: z3.number(),
+    commentCount: z3.number(),
+    petitionCount: z3.number(),
+    petitionThresholdBps: z3.number()
   }),
   examples: [{ description: "Get forum counts and petition threshold" }],
   async run(c) {
@@ -5187,11 +5622,11 @@ forum.command("stats", {
 });
 
 // src/commands/governance.ts
-import { Cli as Cli3, z as z3 } from "incur";
-var env3 = z3.object({
-  ABSTRACT_RPC_URL: z3.string().optional().describe("Abstract RPC URL override")
+import { Cli as Cli3, z as z4 } from "incur";
+var env3 = z4.object({
+  ABSTRACT_RPC_URL: z4.string().optional().describe("Abstract RPC URL override")
 });
-var timestampOutput3 = z3.union([z3.number(), z3.string()]);
+var timestampOutput3 = z4.union([z4.number(), z4.string()]);
 var proposalStatusLabels = {
   0: "pending",
   1: "active",
@@ -5207,31 +5642,31 @@ function proposalStatus(status) {
     statusCode
   };
 }
-var proposalOutputSchema = z3.object({
-  kind: z3.number(),
-  configRiskTier: z3.number(),
-  origin: z3.number(),
-  status: z3.string(),
-  statusCode: z3.number(),
-  proposer: z3.string(),
-  threadId: z3.number(),
-  petitionId: z3.number(),
-  createdAt: z3.number(),
-  deliberationEndsAt: z3.number(),
-  voteStartAt: z3.number(),
-  voteEndAt: z3.number(),
-  timelockEndsAt: z3.number(),
-  activeSeatsSnapshot: z3.number(),
-  forVotes: z3.string(),
-  againstVotes: z3.string(),
-  abstainVotes: z3.string(),
-  amount: z3.string(),
-  snapshotAssetBalance: z3.string(),
-  transferIntent: z3.boolean(),
-  intentDeadline: z3.number(),
-  intentMaxRiskTier: z3.number(),
-  title: z3.string(),
-  description: z3.string()
+var proposalOutputSchema = z4.object({
+  kind: z4.number(),
+  configRiskTier: z4.number(),
+  origin: z4.number(),
+  status: z4.string(),
+  statusCode: z4.number(),
+  proposer: z4.string(),
+  threadId: z4.number(),
+  petitionId: z4.number(),
+  createdAt: z4.number(),
+  deliberationEndsAt: z4.number(),
+  voteStartAt: z4.number(),
+  voteEndAt: z4.number(),
+  timelockEndsAt: z4.number(),
+  activeSeatsSnapshot: z4.number(),
+  forVotes: z4.string(),
+  againstVotes: z4.string(),
+  abstainVotes: z4.string(),
+  amount: z4.string(),
+  snapshotAssetBalance: z4.string(),
+  transferIntent: z4.boolean(),
+  intentDeadline: z4.number(),
+  intentMaxRiskTier: z4.number(),
+  title: z4.string(),
+  description: z4.string()
 });
 function decodeProposal(value) {
   const [
@@ -5320,19 +5755,19 @@ var governance = Cli3.create("governance", {
 governance.command("proposals", {
   description: "List governance proposals with status and vote end time.",
   env: env3,
-  output: z3.object({
-    proposals: z3.array(
-      z3.object({
-        id: z3.number(),
-        kind: z3.number(),
-        status: z3.string(),
-        statusCode: z3.number(),
-        title: z3.string().nullable().optional(),
+  output: z4.object({
+    proposals: z4.array(
+      z4.object({
+        id: z4.number(),
+        kind: z4.number(),
+        status: z4.string(),
+        statusCode: z4.number(),
+        title: z4.string().nullable().optional(),
         voteEndAt: timestampOutput3,
-        voteEndRelative: z3.string()
+        voteEndRelative: z4.string()
       })
     ),
-    count: z3.number()
+    count: z4.number()
   }),
   examples: [{ description: "List all proposals" }],
   async run(c) {
@@ -5380,8 +5815,8 @@ governance.command("proposals", {
 });
 governance.command("proposal", {
   description: "Get full raw proposal details by proposal id.",
-  args: z3.object({
-    id: z3.coerce.number().int().positive().describe("Proposal id (1-indexed)")
+  args: z4.object({
+    id: z4.coerce.number().int().positive().describe("Proposal id (1-indexed)")
   }),
   env: env3,
   output: proposalOutputSchema,
@@ -5413,15 +5848,15 @@ governance.command("proposal", {
 });
 governance.command("has-voted", {
   description: "Check if an address has voted on a proposal.",
-  args: z3.object({
-    proposalId: z3.coerce.number().int().positive().describe("Proposal id (1-indexed)"),
-    address: z3.string().describe("Voter address")
+  args: z4.object({
+    proposalId: z4.coerce.number().int().positive().describe("Proposal id (1-indexed)"),
+    address: z4.string().describe("Voter address")
   }),
   env: env3,
-  output: z3.object({
-    proposalId: z3.number(),
-    address: z3.string(),
-    hasVoted: z3.boolean()
+  output: z4.object({
+    proposalId: z4.number(),
+    address: z4.string(),
+    hasVoted: z4.boolean()
   }),
   examples: [
     {
@@ -5450,19 +5885,19 @@ governance.command("has-voted", {
 governance.command("params", {
   description: "Read governance threshold and timing parameters.",
   env: env3,
-  output: z3.object({
-    deliberationPeriod: z3.number(),
-    votePeriod: z3.number(),
-    quorumBps: z3.number(),
-    constitutionalDeliberationPeriod: z3.number(),
-    constitutionalVotePeriod: z3.number(),
-    constitutionalPassBps: z3.number(),
-    majorPassBps: z3.number(),
-    parameterPassBps: z3.number(),
-    significantPassBps: z3.number(),
-    significantThresholdBps: z3.number(),
-    routineThresholdBps: z3.number(),
-    timelockPeriod: z3.number()
+  output: z4.object({
+    deliberationPeriod: z4.number(),
+    votePeriod: z4.number(),
+    quorumBps: z4.number(),
+    constitutionalDeliberationPeriod: z4.number(),
+    constitutionalVotePeriod: z4.number(),
+    constitutionalPassBps: z4.number(),
+    majorPassBps: z4.number(),
+    parameterPassBps: z4.number(),
+    significantPassBps: z4.number(),
+    significantThresholdBps: z4.number(),
+    routineThresholdBps: z4.number(),
+    timelockPeriod: z4.number()
   }),
   examples: [{ description: "Inspect governance timing and pass thresholds" }],
   async run(c) {
@@ -5507,16 +5942,26 @@ governance.command("params", {
 });
 
 // src/commands/members.ts
-import { Cli as Cli4, z as z4 } from "incur";
+import { TxError } from "@spectratools/tx-shared";
+import { Cli as Cli4, z as z5 } from "incur";
 var DEFAULT_MEMBER_SNAPSHOT_URL = "https://www.theaiassembly.org/api/indexer/members";
 var REGISTERED_EVENT_SCAN_STEP = 100000n;
 var REGISTERED_EVENT_SCAN_TIMEOUT_MS = 2e4;
-var env4 = z4.object({
-  ABSTRACT_RPC_URL: z4.string().optional().describe("Abstract RPC URL override"),
-  ASSEMBLY_INDEXER_URL: z4.string().optional().describe("Optional members snapshot endpoint (default: theaiassembly.org indexer)")
+var MAX_MEMBER_LOOKUP_SUGGESTIONS = 5;
+var env4 = z5.object({
+  ABSTRACT_RPC_URL: z5.string().optional().describe("Abstract RPC URL override"),
+  ASSEMBLY_INDEXER_URL: z5.string().optional().describe("Optional members snapshot endpoint (default: theaiassembly.org indexer)")
 });
-var timestampOutput4 = z4.union([z4.number(), z4.string()]);
-var memberSnapshotSchema = z4.array(z4.string());
+var timestampOutput4 = z5.union([z5.number(), z5.string()]);
+var memberSnapshotEntrySchema = z5.union([
+  z5.string(),
+  z5.object({
+    address: z5.string(),
+    ens: z5.string().optional(),
+    name: z5.string().optional()
+  })
+]);
+var memberSnapshotSchema = z5.array(memberSnapshotEntrySchema);
 var AssemblyApiValidationError = class extends Error {
   constructor(details) {
     super("Assembly API response validation failed");
@@ -5531,6 +5976,45 @@ var AssemblyIndexerUnavailableError = class extends Error {
     this.name = "AssemblyIndexerUnavailableError";
   }
 };
+function mergeMemberIdentities(entries) {
+  const byAddress = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const key = entry.address.toLowerCase();
+    const existing = byAddress.get(key);
+    if (!existing) {
+      byAddress.set(key, entry);
+      continue;
+    }
+    const merged = { address: existing.address };
+    const ens = existing.ens ?? entry.ens;
+    const name = existing.name ?? entry.name;
+    if (ens !== void 0) merged.ens = ens;
+    if (name !== void 0) merged.name = name;
+    byAddress.set(key, merged);
+  }
+  return [...byAddress.values()];
+}
+function memberSnapshotEntryToIdentity(entry) {
+  if (typeof entry === "string") return { address: entry };
+  const identity = { address: entry.address };
+  if (entry.ens !== void 0) identity.ens = entry.ens;
+  if (entry.name !== void 0) identity.name = entry.name;
+  return identity;
+}
+function matchableAddressInput(query) {
+  return query.startsWith("0x") && query.length === 42;
+}
+function searchMemberIdentities(query, members2) {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) return [];
+  const exactMatches = members2.filter((member) => {
+    return member.address.toLowerCase() === needle || member.ens?.toLowerCase() === needle || member.name?.toLowerCase() === needle;
+  });
+  if (exactMatches.length > 0) return exactMatches;
+  return members2.filter((member) => {
+    return member.address.toLowerCase().includes(needle) || member.ens?.toLowerCase().includes(needle) || member.name?.toLowerCase().includes(needle);
+  });
+}
 async function memberSnapshot(url) {
   let res;
   try {
@@ -5553,7 +6037,7 @@ async function memberSnapshot(url) {
   const json = await res.json();
   const parsed = memberSnapshotSchema.safeParse(json);
   if (parsed.success) {
-    return parsed.data;
+    return mergeMemberIdentities(parsed.data.map(memberSnapshotEntryToIdentity));
   }
   throw new AssemblyApiValidationError({
     code: "INVALID_ASSEMBLY_API_RESPONSE",
@@ -5597,7 +6081,28 @@ async function membersFromRegisteredEvents(client) {
       }
     }
   }
-  return [...addresses];
+  return [...addresses].map((address) => ({ address }));
+}
+async function loadMemberIdentities(client, snapshotUrl) {
+  try {
+    return { members: await memberSnapshot(snapshotUrl) };
+  } catch (error) {
+    if (error instanceof AssemblyApiValidationError) {
+      throw error;
+    }
+    if (!(error instanceof AssemblyIndexerUnavailableError)) {
+      throw error;
+    }
+    const fallbackMembers = await withTimeout(
+      membersFromRegisteredEvents(client),
+      REGISTERED_EVENT_SCAN_TIMEOUT_MS,
+      `Registered event fallback scan timed out after ${REGISTERED_EVENT_SCAN_TIMEOUT_MS}ms`
+    );
+    return {
+      members: mergeMemberIdentities(fallbackMembers),
+      fallbackReason: error.details
+    };
+  }
 }
 function indexerIssue(details) {
   if (typeof details.status === "number") {
@@ -5618,25 +6123,31 @@ function emitIndexerFallbackWarning(details) {
 `
   );
 }
+function describeMember(member) {
+  const parts = [toChecksum(member.address)];
+  if (member.ens) parts.push(`ens=${member.ens}`);
+  if (member.name) parts.push(`name=${member.name}`);
+  return parts.join(" ");
+}
 var members = Cli4.create("members", {
   description: "Inspect Assembly membership and registry fee state."
 });
 members.command("list", {
   description: "List members from an indexer snapshot (or Registered event fallback) plus on-chain active state.",
   env: env4,
-  output: z4.object({
-    members: z4.array(
-      z4.object({
-        address: z4.string(),
-        active: z4.boolean(),
-        registered: z4.boolean(),
+  output: z5.object({
+    members: z5.array(
+      z5.object({
+        address: z5.string(),
+        active: z5.boolean(),
+        registered: z5.boolean(),
         activeUntil: timestampOutput4,
-        activeUntilRelative: z4.string(),
+        activeUntilRelative: z5.string(),
         lastHeartbeatAt: timestampOutput4,
-        lastHeartbeatRelative: z4.string()
+        lastHeartbeatRelative: z5.string()
       })
     ),
-    count: z4.number()
+    count: z5.number()
   }),
   examples: [
     { description: "List members using default indexer snapshot" },
@@ -5645,10 +6156,12 @@ members.command("list", {
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const snapshotUrl = c.env.ASSEMBLY_INDEXER_URL ?? DEFAULT_MEMBER_SNAPSHOT_URL;
-    let addresses;
+    let memberIdentities;
     let fallbackReason;
     try {
-      addresses = await memberSnapshot(snapshotUrl);
+      const loaded = await loadMemberIdentities(client, snapshotUrl);
+      memberIdentities = loaded.members;
+      fallbackReason = loaded.fallbackReason;
     } catch (error) {
       if (error instanceof AssemblyApiValidationError) {
         return c.error({
@@ -5657,27 +6170,19 @@ members.command("list", {
           retryable: false
         });
       }
-      if (!(error instanceof AssemblyIndexerUnavailableError)) {
+      if (!(error instanceof Error)) {
         throw error;
       }
-      fallbackReason = error.details;
-      try {
-        addresses = await withTimeout(
-          membersFromRegisteredEvents(client),
-          REGISTERED_EVENT_SCAN_TIMEOUT_MS,
-          `Registered event fallback scan timed out after ${REGISTERED_EVENT_SCAN_TIMEOUT_MS}ms`
-        );
-      } catch (fallbackError) {
-        return c.error({
-          code: "MEMBER_LIST_SOURCE_UNAVAILABLE",
-          message: `Member indexer unavailable (${indexerIssue(error.details)} at ${error.details.url}) and on-chain Registered event fallback failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`,
-          retryable: true
-        });
-      }
+      return c.error({
+        code: "MEMBER_LIST_SOURCE_UNAVAILABLE",
+        message: `Unable to load member list from indexer (${snapshotUrl}) or on-chain fallback: ${error.message}`,
+        retryable: true
+      });
     }
     if (fallbackReason) {
       emitIndexerFallbackWarning(fallbackReason);
     }
+    const addresses = memberIdentities.map((member) => member.address);
     const calls = addresses.flatMap((address) => [
       {
         abi: registryAbi,
@@ -5713,43 +6218,91 @@ members.command("list", {
   }
 });
 members.command("info", {
-  description: "Get registry record and active status for a member address.",
-  args: z4.object({
-    address: z4.string().describe("Member wallet address")
+  description: "Get member registry record and active status by full address, partial address, ENS, or name.",
+  args: z5.object({
+    address: z5.string().describe("Member lookup query (full/partial address, ENS, or name metadata)")
   }),
   env: env4,
-  output: z4.object({
-    address: z4.string(),
-    active: z4.boolean(),
+  output: z5.object({
+    address: z5.string(),
+    active: z5.boolean(),
     activeUntil: timestampOutput4,
     lastHeartbeatAt: timestampOutput4,
-    activeUntilRelative: z4.string(),
-    lastHeartbeatRelative: z4.string()
+    activeUntilRelative: z5.string(),
+    lastHeartbeatRelative: z5.string()
   }),
   examples: [
     {
       args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
       description: "Inspect one member address"
+    },
+    {
+      args: { address: "a96045" },
+      description: "Lookup a member by partial address"
     }
   ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const snapshotUrl = c.env.ASSEMBLY_INDEXER_URL ?? DEFAULT_MEMBER_SNAPSHOT_URL;
+    let lookupAddress = c.args.address;
+    if (!matchableAddressInput(c.args.address)) {
+      let loadedMembers;
+      let fallbackReason;
+      try {
+        const loaded = await loadMemberIdentities(client, snapshotUrl);
+        loadedMembers = loaded.members;
+        fallbackReason = loaded.fallbackReason;
+      } catch (error) {
+        if (error instanceof AssemblyApiValidationError) {
+          return c.error({
+            code: error.details.code,
+            message: `Member snapshot response failed validation. url=${error.details.url}; issues=${JSON.stringify(error.details.issues)}; response=${JSON.stringify(error.details.response)}`,
+            retryable: false
+          });
+        }
+        return c.error({
+          code: "MEMBER_LOOKUP_SOURCE_UNAVAILABLE",
+          message: error instanceof Error ? `Unable to resolve member query from indexer (${snapshotUrl}) or on-chain fallback: ${error.message}` : `Unable to resolve member query from indexer (${snapshotUrl}) or on-chain fallback.`,
+          retryable: true
+        });
+      }
+      if (fallbackReason) {
+        emitIndexerFallbackWarning(fallbackReason);
+      }
+      const matches = searchMemberIdentities(c.args.address, loadedMembers);
+      if (matches.length === 0) {
+        return c.error({
+          code: "MEMBER_NOT_FOUND",
+          message: `No Assembly member matched "${c.args.address}". Try a longer query or run \`assembly members list\` first.`,
+          retryable: false
+        });
+      }
+      if (matches.length > 1) {
+        const suggestions = matches.slice(0, MAX_MEMBER_LOOKUP_SUGGESTIONS).map(describeMember).join("; ");
+        return c.error({
+          code: "AMBIGUOUS_MEMBER_QUERY",
+          message: `Member query "${c.args.address}" matched ${matches.length} members. Be more specific. Matches: ${suggestions}`,
+          retryable: false
+        });
+      }
+      lookupAddress = matches[0].address;
+    }
     const [member, active] = await Promise.all([
       client.readContract({
         abi: registryAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.registry,
         functionName: "members",
-        args: [c.args.address]
+        args: [lookupAddress]
       }),
       client.readContract({
         abi: registryAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.registry,
         functionName: "isActive",
-        args: [c.args.address]
+        args: [lookupAddress]
       })
     ]);
     return c.ok({
-      address: toChecksum(c.args.address),
+      address: toChecksum(lookupAddress),
       active,
       activeUntil: timeValue(member.activeUntil, c.format),
       lastHeartbeatAt: timeValue(member.lastHeartbeatAt, c.format),
@@ -5761,9 +6314,9 @@ members.command("info", {
 members.command("count", {
   description: "Get active and total-known member counts from Registry.",
   env: env4,
-  output: z4.object({
-    active: z4.number(),
-    total: z4.number()
+  output: z5.object({
+    active: z5.number(),
+    total: z5.number()
   }),
   examples: [{ description: "Count active and known members" }],
   async run(c) {
@@ -5786,12 +6339,12 @@ members.command("count", {
 members.command("fees", {
   description: "Get registration and heartbeat fee settings.",
   env: env4,
-  output: z4.object({
-    registrationFeeWei: z4.string(),
-    registrationFee: z4.string(),
-    heartbeatFeeWei: z4.string(),
-    heartbeatFee: z4.string(),
-    heartbeatGracePeriodSeconds: z4.number()
+  output: z5.object({
+    registrationFeeWei: z5.string(),
+    registrationFee: z5.string(),
+    heartbeatFeeWei: z5.string(),
+    heartbeatFee: z5.string(),
+    heartbeatGracePeriodSeconds: z5.number()
   }),
   examples: [{ description: "Inspect current registry fee configuration" }],
   async run(c) {
@@ -5822,23 +6375,196 @@ members.command("fees", {
     });
   }
 });
+var txOutputSchema = z5.union([
+  z5.object({
+    status: z5.enum(["success", "reverted"]),
+    hash: z5.string(),
+    blockNumber: z5.number(),
+    gasUsed: z5.string(),
+    from: z5.string(),
+    to: z5.string().nullable(),
+    effectiveGasPrice: z5.string().optional(),
+    fee: z5.string(),
+    feeEth: z5.string()
+  }),
+  z5.object({
+    status: z5.literal("dry-run"),
+    estimatedGas: z5.string(),
+    simulationResult: z5.unknown(),
+    fee: z5.string(),
+    feeEth: z5.string()
+  })
+]);
+members.command("register", {
+  description: "Register as a new Assembly member (pays the registration fee).",
+  hint: "Requires PRIVATE_KEY environment variable for signing.",
+  env: writeEnv,
+  options: writeOptions,
+  output: txOutputSchema,
+  examples: [
+    { description: "Register as a member" },
+    { options: { "dry-run": true }, description: "Simulate registration without broadcasting" }
+  ],
+  async run(c) {
+    const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const fee = await client.readContract({
+      abi: registryAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.registry,
+      functionName: "registrationFee"
+    });
+    process.stderr.write(
+      `${JSON.stringify({ level: "info", message: `Registration fee: ${eth(fee)} (${fee} wei)` })}
+`
+    );
+    try {
+      const result = await assemblyWriteTx({
+        env: c.env,
+        options: c.options,
+        address: ABSTRACT_MAINNET_ADDRESSES.registry,
+        abi: registryAbi,
+        functionName: "register",
+        value: fee
+      });
+      return c.ok(
+        { ...result, fee: fee.toString(), feeEth: eth(fee) },
+        result.status === "success" ? {
+          cta: {
+            description: "Check your membership:",
+            commands: [{ command: "members info", args: { address: result.from } }]
+          }
+        } : void 0
+      );
+    } catch (error) {
+      if (error instanceof TxError && error.code === "INSUFFICIENT_FUNDS") {
+        return c.error({
+          code: "INSUFFICIENT_FUNDS",
+          message: `Insufficient funds to register. Required fee: ${eth(fee)} (${fee} wei). ${error.message}`,
+          retryable: false
+        });
+      }
+      throw error;
+    }
+  }
+});
+members.command("heartbeat", {
+  description: "Send a heartbeat to extend active membership (pays the heartbeat fee).",
+  hint: "Requires PRIVATE_KEY environment variable for signing.",
+  env: writeEnv,
+  options: writeOptions,
+  output: txOutputSchema,
+  examples: [
+    { description: "Send a heartbeat" },
+    { options: { "dry-run": true }, description: "Simulate heartbeat without broadcasting" }
+  ],
+  async run(c) {
+    const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const fee = await client.readContract({
+      abi: registryAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.registry,
+      functionName: "heartbeatFee"
+    });
+    process.stderr.write(
+      `${JSON.stringify({ level: "info", message: `Heartbeat fee: ${eth(fee)} (${fee} wei)` })}
+`
+    );
+    try {
+      const result = await assemblyWriteTx({
+        env: c.env,
+        options: c.options,
+        address: ABSTRACT_MAINNET_ADDRESSES.registry,
+        abi: registryAbi,
+        functionName: "heartbeat",
+        value: fee
+      });
+      return c.ok(
+        { ...result, fee: fee.toString(), feeEth: eth(fee) },
+        result.status === "success" ? {
+          cta: {
+            description: "Check your membership:",
+            commands: [{ command: "members info", args: { address: result.from } }]
+          }
+        } : void 0
+      );
+    } catch (error) {
+      if (error instanceof TxError && error.code === "INSUFFICIENT_FUNDS") {
+        return c.error({
+          code: "INSUFFICIENT_FUNDS",
+          message: `Insufficient funds for heartbeat. Required fee: ${eth(fee)} (${fee} wei). ${error.message}`,
+          retryable: false
+        });
+      }
+      throw error;
+    }
+  }
+});
+members.command("renew", {
+  description: "Renew an expired membership (pays the registration fee).",
+  hint: "Requires PRIVATE_KEY environment variable for signing. Calls register() to re-activate expired membership.",
+  env: writeEnv,
+  options: writeOptions,
+  output: txOutputSchema,
+  examples: [
+    { description: "Renew expired membership" },
+    { options: { "dry-run": true }, description: "Simulate renewal without broadcasting" }
+  ],
+  async run(c) {
+    const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const fee = await client.readContract({
+      abi: registryAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.registry,
+      functionName: "registrationFee"
+    });
+    process.stderr.write(
+      `${JSON.stringify({ level: "info", message: `Renewal fee: ${eth(fee)} (${fee} wei)` })}
+`
+    );
+    try {
+      const result = await assemblyWriteTx({
+        env: c.env,
+        options: c.options,
+        address: ABSTRACT_MAINNET_ADDRESSES.registry,
+        abi: registryAbi,
+        functionName: "register",
+        value: fee
+      });
+      return c.ok(
+        { ...result, fee: fee.toString(), feeEth: eth(fee) },
+        result.status === "success" ? {
+          cta: {
+            description: "Check your membership:",
+            commands: [{ command: "members info", args: { address: result.from } }]
+          }
+        } : void 0
+      );
+    } catch (error) {
+      if (error instanceof TxError && error.code === "INSUFFICIENT_FUNDS") {
+        return c.error({
+          code: "INSUFFICIENT_FUNDS",
+          message: `Insufficient funds to renew. Required fee: ${eth(fee)} (${fee} wei). ${error.message}`,
+          retryable: false
+        });
+      }
+      throw error;
+    }
+  }
+});
 
 // src/commands/treasury.ts
-import { Cli as Cli5, z as z5 } from "incur";
-var env5 = z5.object({
-  ABSTRACT_RPC_URL: z5.string().optional().describe("Abstract RPC URL override")
+import { Cli as Cli5, z as z6 } from "incur";
+var env5 = z6.object({
+  ABSTRACT_RPC_URL: z6.string().optional().describe("Abstract RPC URL override")
 });
-var timestampOutput5 = z5.union([z5.number(), z5.string()]);
+var timestampOutput5 = z6.union([z6.number(), z6.string()]);
 var treasury = Cli5.create("treasury", {
   description: "Inspect treasury balances, execution status, and spend controls."
 });
 treasury.command("balance", {
   description: "Get current native token balance for the treasury contract.",
   env: env5,
-  output: z5.object({
-    address: z5.string(),
-    balanceWei: z5.string(),
-    balance: z5.string()
+  output: z6.object({
+    address: z6.string(),
+    balanceWei: z6.string(),
+    balance: z6.string()
   }),
   examples: [{ description: "Check treasury balance" }],
   async run(c) {
@@ -5853,13 +6579,13 @@ treasury.command("balance", {
 });
 treasury.command("whitelist", {
   description: "Check whether an asset address is treasury-whitelisted.",
-  args: z5.object({
-    asset: z5.string().describe("Token/asset contract address")
+  args: z6.object({
+    asset: z6.string().describe("Token/asset contract address")
   }),
   env: env5,
-  output: z5.object({
-    asset: z5.string(),
-    whitelisted: z5.boolean()
+  output: z6.object({
+    asset: z6.string(),
+    whitelisted: z6.boolean()
   }),
   examples: [
     {
@@ -5881,11 +6607,11 @@ treasury.command("whitelist", {
 treasury.command("major-spend-status", {
   description: "Read major-spend cooldown status for the treasury contract.",
   env: env5,
-  output: z5.object({
-    majorSpendCooldownSeconds: z5.number(),
+  output: z6.object({
+    majorSpendCooldownSeconds: z6.number(),
     lastMajorSpendAt: timestampOutput5,
-    lastMajorSpendRelative: z5.string(),
-    isMajorSpendAllowed: z5.boolean()
+    lastMajorSpendRelative: z6.string(),
+    isMajorSpendAllowed: z6.boolean()
   }),
   examples: [{ description: "Inspect treasury major-spend guardrails" }],
   async run(c) {
@@ -5919,13 +6645,13 @@ treasury.command("major-spend-status", {
 });
 treasury.command("executed", {
   description: "Check whether a treasury action for a proposal has executed.",
-  args: z5.object({
-    proposalId: z5.coerce.number().int().positive().describe("Governance proposal id")
+  args: z6.object({
+    proposalId: z6.coerce.number().int().positive().describe("Governance proposal id")
   }),
   env: env5,
-  output: z5.object({
-    proposalId: z5.number(),
-    executed: z5.boolean()
+  output: z6.object({
+    proposalId: z6.number(),
+    executed: z6.boolean()
   }),
   examples: [{ args: { proposalId: 1 }, description: "Check execution status for proposal #1" }],
   async run(c) {
@@ -6091,20 +6817,20 @@ cli.command(council);
 cli.command(forum);
 cli.command(governance);
 cli.command(treasury);
-var rootEnv = z6.object({
-  ABSTRACT_RPC_URL: z6.string().optional().describe("Abstract RPC URL override")
+var rootEnv = z7.object({
+  ABSTRACT_RPC_URL: z7.string().optional().describe("Abstract RPC URL override")
 });
-var timestampOutput6 = z6.union([z6.number(), z6.string()]);
+var timestampOutput6 = z7.union([z7.number(), z7.string()]);
 cli.command("status", {
   description: "Get a cross-contract Assembly snapshot (members, council, governance, treasury).",
   env: rootEnv,
-  output: z6.object({
-    activeMemberCount: z6.number(),
-    seatCount: z6.number(),
-    proposalCount: z6.number(),
-    currentAuctionDay: z6.number(),
-    currentAuctionSlot: z6.number(),
-    treasuryBalance: z6.string()
+  output: z7.object({
+    activeMemberCount: z7.number(),
+    seatCount: z7.number(),
+    proposalCount: z7.number(),
+    currentAuctionDay: z7.number(),
+    currentAuctionSlot: z7.number(),
+    treasuryBalance: z7.string()
   }),
   examples: [{ description: "Fetch the current Assembly system status" }],
   async run(c) {
@@ -6156,18 +6882,18 @@ cli.command("status", {
 });
 cli.command("health", {
   description: "Check cross-contract health for one address (membership, council, refunds, power).",
-  args: z6.object({
-    address: z6.string().describe("Member or wallet address to inspect")
+  args: z7.object({
+    address: z7.string().describe("Member or wallet address to inspect")
   }),
   env: rootEnv,
-  output: z6.object({
-    address: z6.string(),
-    isActive: z6.boolean(),
+  output: z7.object({
+    address: z7.string(),
+    isActive: z7.boolean(),
     activeUntil: timestampOutput6,
-    activeUntilRelative: z6.string(),
-    isCouncilMember: z6.boolean(),
-    pendingReturnsWei: z6.string(),
-    votingPower: z6.number()
+    activeUntilRelative: z7.string(),
+    isCouncilMember: z7.boolean(),
+    pendingReturnsWei: z7.string(),
+    votingPower: z7.number()
   }),
   examples: [
     {