taximeter 0.2.2 → 0.3.0

package/dist/cli/index.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import {
   Ledger,
+  amountSchema,
+  assetMetadata,
   budgetSchema,
   closeProxy,
+  configPatchSchema,
   countsAsSpend,
   createProxy,
   diagnosticSchema,
@@ -10,71 +13,388 @@ import {
   formatAmount,
   httpUrlSchema,
   integerStringSchema,
+  knownAssets,
   labelSchema,
   loadConfig,
+  loadConfigDetails,
   matchesAsset,
+  parseConfig,
   paymentEventSchema,
   portInputSchema,
-  spentForBudget,
   toCsv,
   toInvoice,
   toJson,
   totalSchema,
   totals,
+  totalsForBudget,
   version
-} from "../chunk-DJPLFDD7.js";
+} from "../chunk-Q2M76JNT.js";
 
 // src/cli/index.ts
 import { CommanderError } from "commander";
 
 // src/cli/program.ts
-import { existsSync as existsSync3, renameSync, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync4, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "fs";
 import { resolve as resolve2 } from "path";
 import { Command } from "commander";
-import { z as z4 } from "zod";
+import { z as z8 } from "zod";
+
+// src/config/amount-input.ts
+import { z } from "zod";
+function metadataForSelector(selector, network) {
+  const registry = knownAssets();
+  const bySymbol = registry.find((entry) => entry.assetSymbol === selector);
+  if (bySymbol) return bySymbol;
+  if (network) return assetMetadata(network, selector);
+  const entries = registry.filter((entry) => entry.asset.toLowerCase() === selector.toLowerCase());
+  const first = entries[0];
+  if (first && entries.every(
+    (entry) => entry.decimals === first.decimals && entry.assetSymbol === first.assetSymbol
+  ))
+    return first;
+  return { decimals: 0, decimalsKnown: false, assetSymbol: void 0 };
+}
+function knownAmountSymbols() {
+  return [
+    ...new Set(knownAssets().flatMap((entry) => entry.assetSymbol ? [entry.assetSymbol] : []))
+  ].sort();
+}
+function parseAmountInput(input, selector = "USDC", network) {
+  const text = z.string().min(1).parse(input).trim();
+  if (/^[0-9]+$/.test(text)) return amountSchema.parse(text);
+  const match = /^(0|[1-9][0-9]*)(?:\.([0-9]+))?\s*([a-zA-Z][a-zA-Z0-9]*)$/.exec(text);
+  if (!match)
+    throw new Error("Use an exact atomic integer or an amount with a known symbol, such as 5USDC.");
+  const symbol = match[3]?.toUpperCase();
+  const metadata = knownAssets().find((entry) => entry.assetSymbol === symbol);
+  if (!metadata) {
+    throw new Error(
+      `Unknown asset symbol ${symbol}. Known symbols: ${knownAmountSymbols().join(", ")}. An exact atomic integer is always accepted.`
+    );
+  }
+  const selected = metadataForSelector(selector, network);
+  if (!selected.decimalsKnown || selected.assetSymbol !== symbol) {
+    throw new Error(
+      `Amount unit ${symbol} does not match configured asset ${selector}. Change the asset explicitly or use an exact atomic integer.`
+    );
+  }
+  const fraction = match[2] ?? "";
+  if (fraction.length > metadata.decimals)
+    throw new Error(
+      `${symbol} supports at most ${metadata.decimals} decimal places; no rounding is performed.`
+    );
+  const scale = 10n ** BigInt(metadata.decimals);
+  const units = BigInt(match[1] ?? "0") * scale + BigInt(fraction.padEnd(metadata.decimals, "0") || "0");
+  return amountSchema.parse(units.toString());
+}
+function formatAmount2(amount2, selector, network) {
+  const atomic = amountSchema.parse(amount2);
+  const metadata = metadataForSelector(selector, network);
+  if (!metadata.decimalsKnown || !metadata.assetSymbol) return `${atomic} atomic units`;
+  const digits = atomic.padStart(metadata.decimals + 1, "0");
+  const whole = metadata.decimals ? digits.slice(0, -metadata.decimals) : digits;
+  const fraction = metadata.decimals ? digits.slice(-metadata.decimals).replace(/0+$/, "") : "";
+  return `${whole}${fraction ? `.${fraction}` : ""} ${metadata.assetSymbol}`;
+}
+
+// src/config/display.ts
+function layerStatus(layer) {
+  if (!layer.supplied)
+    return layer.path ? "[not found]" : layer.name === "explicit" ? "(not supplied)" : "(none)";
+  const state = layer.contributed ? "in use" : layer.keys.length ? "overridden" : "empty";
+  const partial = layer.contributed && layer.overriddenKeys.length ? `; overridden keys: ${layer.overriddenKeys.join(", ")}` : "";
+  return `[${layer.path ? layer.exists ? "exists, " : "candidate, " : ""}${state}${partial}]`;
+}
+function formatLayers(details) {
+  return [
+    "Layers (highest priority first):",
+    ...details.layers.map((layer) => {
+      const value = layer.path ?? (layer.name === "defaults" ? "built in" : layer.name === "environment" ? layer.environmentVariables?.join(", ") ?? "" : layer.keys.join(", "));
+      return `  ${layer.label.padEnd(13)}${value}${value ? "  " : ""}${layerStatus(layer)}`;
+    })
+  ].join("\n");
+}
+function formatEffectiveConfig(config) {
+  const policy = config.policy;
+  const amountDescription = (amount2, asset, network) => {
+    const formatted = formatAmount2(amount2, asset, network);
+    return formatted === `${amount2} atomic units` ? formatted : `${amount2}  (${formatted})`;
+  };
+  const list = (items, meaning = "") => items.length ? items.join(", ") : `(empty${meaning ? ` \u2014 ${meaning}` : ""})`;
+  return [
+    "Effective policy:",
+    `  maxSinglePayment   ${policy.maxSinglePayment === null ? "disabled" : amountDescription(policy.maxSinglePayment, policy.maxSingleAsset)}`,
+    `  maxSingleAsset     ${policy.maxSingleAsset}`,
+    `  unknownAsset       ${policy.unknownAsset}`,
+    `  allowHosts         ${list(policy.allowHosts, "all hosts allowed")}`,
+    `  denyHosts          ${list(policy.denyHosts)}`,
+    `  allowPayTo         ${list(policy.allowPayTo, "all recipients allowed")}`,
+    "",
+    "Effective budgets:",
+    ...["perTask", "perAgent", "global"].map((scope) => {
+      const budget = config.budgets[scope];
+      if (!budget) return `  ${scope.padEnd(11)}disabled`;
+      const amount2 = budget.amount === void 0 ? "(no amount limit)" : amountDescription(budget.amount, budget.asset, budget.network);
+      const count2 = budget.maxPayments === void 0 ? "(no payment-count limit)" : `max ${budget.maxPayments} payments`;
+      return `  ${scope.padEnd(11)}${amount2}  ${budget.window ? `${budget.window}  ` : ""}${count2}  asset ${budget.asset}${budget.network ? `  network ${budget.network}` : ""}`;
+    })
+  ].join("\n");
+}
+
+// src/config/edit.ts
+import { randomUUID } from "crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname } from "path";
+import { z as z2 } from "zod";
+function unwrapped(schema) {
+  if (schema instanceof z2.ZodOptional || schema instanceof z2.ZodNullable || schema instanceof z2.ZodDefault || schema instanceof z2.ZodPrefault) {
+    const inner = schema.unwrap();
+    if (!(inner instanceof z2.ZodType)) throw new Error("Unsupported configuration schema");
+    return unwrapped(inner);
+  }
+  return schema;
+}
+function schemaPaths(schema, prefix = "") {
+  const paths = /* @__PURE__ */ new Map();
+  const value = unwrapped(schema);
+  if (prefix) paths.set(prefix, schema);
+  if (value instanceof z2.ZodObject) {
+    for (const [key, child] of Object.entries(value.shape)) {
+      if (!(child instanceof z2.ZodType)) throw new Error("Unsupported configuration schema");
+      for (const entry of schemaPaths(child, prefix ? `${prefix}.${key}` : key))
+        paths.set(...entry);
+    }
+  }
+  return paths;
+}
+function distance(left, right) {
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let row = 1; row <= left.length; row += 1) {
+    const current = [row];
+    for (let column = 1; column <= right.length; column += 1) {
+      current[column] = Math.min(
+        (current[column - 1] ?? 0) + 1,
+        (previous[column] ?? 0) + 1,
+        (previous[column - 1] ?? 0) + (left[row - 1] === right[column - 1] ? 0 : 1)
+      );
+    }
+    previous = current;
+  }
+  return previous[right.length] ?? left.length;
+}
+function schemaForKey(input) {
+  const key = z2.string().parse(input);
+  const paths = schemaPaths(configPatchSchema);
+  const schema = paths.get(key);
+  if (schema) return schema;
+  const nearest = [...paths.keys()].sort(
+    (left, right) => distance(key, left) - distance(key, right) || left.localeCompare(right)
+  )[0];
+  throw new Error(`Unknown configuration key "${key}". Did you mean "${nearest}"?`);
+}
+function configValue(config, key) {
+  schemaForKey(key);
+  let value = config;
+  for (const part of key.split(".")) {
+    if (value === null || typeof value !== "object" || !Object.hasOwn(value, part))
+      return void 0;
+    value = Reflect.get(value, part);
+  }
+  return value;
+}
+function amountContext(config, key) {
+  if (key === "policy.maxSinglePayment") return { asset: config.policy.maxSingleAsset };
+  const match = /^budgets\.(perTask|perAgent|global)\.amount$/.exec(key);
+  if (!match) return void 0;
+  const scope = z2.enum(["perTask", "perAgent", "global"]).parse(match[1]);
+  return config.budgets[scope] ?? { asset: "USDC" };
+}
+function parsedInput(key, input, config) {
+  const schema = schemaForKey(key);
+  const value = z2.string().parse(input);
+  if (value === "null") return null;
+  const context = amountContext(config, key);
+  if (context) return parseAmountInput(value, context.asset, context.network);
+  const type = unwrapped(schema);
+  if (type instanceof z2.ZodArray) {
+    if (value.trim().startsWith("[")) return JSON.parse(value);
+    return value === "" ? [] : value.split(",").map((entry) => entry.trim());
+  }
+  if (type instanceof z2.ZodObject) return JSON.parse(value);
+  if (type instanceof z2.ZodNumber)
+    return z2.string().regex(/^(0|[1-9][0-9]*)$/, "Use a plain integer without units").transform(Number).parse(value);
+  return value;
+}
+function parseConfigInput(key, input, config) {
+  try {
+    return parsedInput(key, input, config);
+  } catch (error) {
+    if (error instanceof z2.ZodError)
+      throw new z2.ZodError(
+        error.issues.map((issue) => ({ ...issue, path: [...key.split("."), ...issue.path] }))
+      );
+    if (error instanceof SyntaxError) throw new Error(`${key}: expected valid JSON`);
+    throw error;
+  }
+}
+function configError(error) {
+  if (error instanceof z2.ZodError)
+    return new Error(
+      error.issues.map((issue) => `${issue.path.join(".") || "configuration"}: ${issue.message}`).join("; ")
+    );
+  return error instanceof Error ? error : new Error("Invalid configuration");
+}
+function changePath(layer, key, value, unset) {
+  const parts = key.split(".");
+  const final = parts.pop();
+  if (!final) throw new Error("Expected a configuration key");
+  let parent = layer;
+  const ancestors = [];
+  for (const part of parts) {
+    const next = parent[part];
+    if (next === null || typeof next !== "object" || Array.isArray(next)) {
+      if (unset) return;
+      parent[part] = {};
+    }
+    ancestors.push({ value: parent, key: part });
+    parent = z2.record(z2.string(), z2.unknown()).parse(parent[part]);
+    const ancestor = ancestors.at(-1);
+    if (ancestor) ancestor.value[part] = parent;
+  }
+  if (unset) {
+    delete parent[final];
+    for (const ancestor of ancestors.reverse()) {
+      const child = ancestor.value[ancestor.key];
+      if (child && typeof child === "object" && Object.keys(child).length === 0)
+        delete ancestor.value[ancestor.key];
+      else break;
+    }
+  } else parent[final] = value;
+}
+function atomicWrite(path, content) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let created = false;
+  try {
+    const descriptor = openSync(temporary, "wx", 384);
+    created = true;
+    try {
+      writeFileSync(descriptor, content, "utf8");
+      fsyncSync(descriptor);
+    } finally {
+      closeSync(descriptor);
+    }
+    renameSync(temporary, path);
+    created = false;
+  } finally {
+    if (created) unlinkSync(temporary);
+  }
+}
+function editConfig(input) {
+  try {
+    schemaForKey(input.key);
+    const options3 = input.options ?? {};
+    const before = loadConfigDetails(input.flags, options3);
+    const path = expandPath(input.file ?? before.defaultWritePath, options3.home, options3.cwd);
+    if (path === ":memory:") throw new Error("Choose a configuration file path, not :memory:");
+    const original = existsSync(path) ? readFileSync(path, "utf8") : void 0;
+    const layer = configPatchSchema.parse(original === void 0 ? {} : JSON.parse(original));
+    const targetIndex = before.layers.map((entry) => entry.path).lastIndexOf(path);
+    const participates = targetIndex >= 0;
+    const amountConfig = input.unset || !amountContext(before.config, input.key) ? before.config : participates ? loadConfigDetails(
+      {},
+      {
+        ...options3,
+        env: {},
+        layerOverrides: {
+          ...options3.layerOverrides,
+          ...Object.fromEntries(
+            before.layers.slice(0, targetIndex).filter((entry) => entry.path && entry.path !== path).map((entry) => [entry.path, {}])
+          )
+        }
+      }
+    ).config : parseConfig(layer);
+    const value = input.unset ? void 0 : parseConfigInput(input.key, z2.string().parse(input.value), amountConfig);
+    changePath(layer, input.key, value, input.unset ?? false);
+    const candidate = configPatchSchema.parse(layer);
+    if (!participates) parseConfig(candidate);
+    const after = loadConfigDetails(input.flags, {
+      ...options3,
+      layerOverrides: { ...options3.layerOverrides, [path]: candidate }
+    });
+    const unchanged = input.unset && original === void 0;
+    if (!unchanged) atomicWrite(path, `${JSON.stringify(candidate, null, 2)}
+`);
+    return {
+      path,
+      key: input.key,
+      before: before.config,
+      after: after.config,
+      writtenValue: configValue(candidate, input.key),
+      writtenAmountContext: amountContext(amountConfig, input.key),
+      participates,
+      changed: !unchanged
+    };
+  } catch (error) {
+    throw configError(error);
+  }
+}
 
 // src/server/lifecycle.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "fs";
-import { z as z3 } from "zod";
+import { existsSync as existsSync3, readFileSync as readFileSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
+import { z as z5 } from "zod";
 
 // src/server/index.ts
-import { existsSync, readFileSync, statSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "fs";
 import { createServer } from "http";
-import { dirname, extname, resolve, sep } from "path";
+import { dirname as dirname2, extname, resolve, sep } from "path";
 import { fileURLToPath } from "url";
-import { z as z2 } from "zod";
+import { z as z4 } from "zod";
 
 // src/server/schema.ts
-import { z } from "zod";
+import { z as z3 } from "zod";
 var dashboardEventSchema = paymentEventSchema.omit({ raw: true });
-var groupSchema = totalSchema.extend({ key: z.string().nullable() });
-var dashboardStateSchema = z.object({
-  version: z.literal(version),
-  generatedAt: z.iso.datetime(),
-  totalEvents: z.number().int(),
-  blockedEvents: z.number().int(),
-  unknownEvents: z.number().int(),
-  totals: z.array(totalSchema),
-  events: z.array(dashboardEventSchema),
-  diagnostics: z.array(diagnosticSchema),
-  groups: z.object({
-    task: z.array(groupSchema),
-    agent: z.array(groupSchema),
-    host: z.array(groupSchema)
+var groupSchema = totalSchema.extend({ key: z3.string().nullable() });
+var dashboardStateSchema = z3.object({
+  version: z3.literal(version),
+  generatedAt: z3.iso.datetime(),
+  totalEvents: z3.number().int(),
+  blockedEvents: z3.number().int(),
+  unknownEvents: z3.number().int(),
+  totals: z3.array(totalSchema),
+  events: z3.array(dashboardEventSchema),
+  diagnostics: z3.array(diagnosticSchema),
+  groups: z3.object({
+    task: z3.array(groupSchema),
+    agent: z3.array(groupSchema),
+    host: z3.array(groupSchema)
   }),
-  hours: z.array(z.object({ ts: z.iso.datetime(), totals: z.array(totalSchema) })),
+  hours: z3.array(z3.object({ ts: z3.iso.datetime(), totals: z3.array(totalSchema) })),
   globalBudget: budgetSchema.nullable(),
-  budgets: z.array(
-    z.object({
-      network: z.string(),
-      asset: z.string(),
-      limit: integerStringSchema,
+  budgets: z3.array(
+    z3.object({
+      network: z3.string(),
+      asset: z3.string(),
+      limit: integerStringSchema.nullable(),
       spent: integerStringSchema,
-      remaining: integerStringSchema,
-      window: z.string().nullable()
+      remaining: integerStringSchema.nullable(),
+      count: integerStringSchema,
+      countLimit: integerStringSchema.nullable(),
+      countRemaining: integerStringSchema.nullable(),
+      window: z3.string().nullable()
     })
   ),
-  proxy: z.object({ port: z.number().int(), upstream: z.string().optional() })
+  proxy: z3.object({ port: z3.number().int(), upstream: z3.string().optional() })
 });
 
 // src/server/state.ts
@@ -100,14 +420,18 @@ function dashboardState(ledger, config, now = Date.now()) {
     const representative = events.find(
       (event) => event.network === total2.network && event.asset.toLowerCase() === total2.asset
     );
-    const spent = representative ? spentForBudget(representative, events, budget, "global", now) : "0";
-    const remaining = BigInt(budget.amount) - BigInt(spent);
+    const { amount: spent, count: count2 } = representative ? totalsForBudget(representative, events, budget, "global", now) : { amount: "0", count: "0" };
+    const remaining = budget.amount === void 0 ? null : BigInt(budget.amount) - BigInt(spent);
+    const countRemaining = budget.maxPayments === void 0 ? null : BigInt(budget.maxPayments) - BigInt(count2);
     return {
       network: total2.network,
       asset: total2.asset,
-      limit: budget.amount,
+      limit: budget.amount ?? null,
       spent,
-      remaining: (remaining < 0n ? 0n : remaining).toString(),
+      remaining: remaining === null ? null : (remaining < 0n ? 0n : remaining).toString(),
+      count: count2,
+      countLimit: budget.maxPayments?.toString() ?? null,
+      countRemaining: countRemaining === null ? null : (countRemaining < 0n ? 0n : countRemaining).toString(),
       window: budget.window ?? null
     };
   }) : [];
@@ -145,7 +469,7 @@ function dashboardState(ledger, config, now = Date.now()) {
 }
 
 // src/server/index.ts
-var querySchema = z2.strictObject({ format: z2.enum(["csv", "json", "invoice"]).optional() });
+var querySchema = z4.strictObject({ format: z4.enum(["csv", "json", "invoice"]).optional() });
 var types = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -154,17 +478,17 @@ var types = {
   ".woff2": "font/woff2"
 };
 function uiDirectory() {
-  const here = dirname(fileURLToPath(import.meta.url));
+  const here = dirname2(fileURLToPath(import.meta.url));
   return [resolve(here, "ui"), resolve(here, "../ui"), resolve(here, "../../dist/ui")].find(
-    (path) => existsSync(resolve(path, "index.html"))
+    (path) => existsSync2(resolve(path, "index.html"))
   ) ?? resolve(here, "ui");
 }
 function json(response, status, value) {
   response.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
   response.end(JSON.stringify(value));
 }
-function createDashboard(options2) {
-  const root = resolve(options2.uiRoot ?? uiDirectory());
+function createDashboard(options3) {
+  const root = resolve(options3.uiRoot ?? uiDirectory());
   return createServer((request, response) => {
     response.setHeader(
       "Content-Security-Policy",
@@ -173,13 +497,13 @@ function createDashboard(options2) {
     response.setHeader("X-Content-Type-Options", "nosniff");
     response.setHeader("Referrer-Policy", "no-referrer");
     try {
-      const input = z2.object({
-        method: z2.string(),
-        url: z2.string(),
-        headers: z2.object({
-          host: z2.string(),
-          origin: z2.string().optional(),
-          "sec-fetch-site": z2.string().optional()
+      const input = z4.object({
+        method: z4.string(),
+        url: z4.string(),
+        headers: z4.object({
+          host: z4.string(),
+          origin: z4.string().optional(),
+          "sec-fetch-site": z4.string().optional()
         })
       }).parse(request);
       const localPort = request.socket.localPort;
@@ -205,12 +529,12 @@ function createDashboard(options2) {
       }
       const query = querySchema.parse(Object.fromEntries(entries));
       if (url.pathname === "/api/summary") {
-        json(response, 200, dashboardState(options2.ledger, options2.config));
+        json(response, 200, dashboardState(options3.ledger, options3.config));
         return;
       }
       if (url.pathname === "/api/export") {
         const format = query.format ?? "json";
-        const events = options2.ledger.view();
+        const events = options3.ledger.view();
         const body = format === "csv" ? toCsv(events) : format === "invoice" ? toInvoice(events) : toJson(events);
         response.writeHead(200, {
           "Content-Type": format === "csv" ? "text/csv; charset=utf-8" : format === "invoice" ? "text/html; charset=utf-8" : "application/json",
@@ -226,8 +550,8 @@ function createDashboard(options2) {
         json(response, 403, { error: "forbidden" });
         return;
       }
-      if (!existsSync(path) || !statSync(path).isFile() || !types[extname(path)]) {
-        if (url.pathname === "/" && !existsSync(resolve(root, "index.html"))) {
+      if (!existsSync2(path) || !statSync(path).isFile() || !types[extname(path)]) {
+        if (url.pathname === "/" && !existsSync2(resolve(root, "index.html"))) {
           response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
           response.end(
             "<!doctype html><title>Taximeter</title><h1>Taximeter</h1><p>The local ledger is ready. Contributors: run npm run build to build the dashboard.</p>"
@@ -241,7 +565,7 @@ function createDashboard(options2) {
         "Content-Type": types[extname(path)],
         "Cache-Control": path.endsWith("index.html") ? "no-cache" : "public, max-age=31536000, immutable"
       });
-      response.end(readFileSync(path));
+      response.end(readFileSync2(path));
     } catch {
       json(response, 400, { error: "invalid_request" });
     }
@@ -257,18 +581,18 @@ async function listenLocal(server, port2) {
       resolve3();
     });
   });
-  return z3.object({ port: z3.number() }).parse(server.address()).port;
+  return z5.object({ port: z5.number() }).parse(server.address()).port;
 }
 function assertStopped(db) {
   if (db === ":memory:") return;
   const path = `${db}.lock`;
-  if (!existsSync2(path)) return;
-  const lock = z3.object({ pid: z3.number().int().positive() }).parse(JSON.parse(readFileSync2(path, "utf8")));
+  if (!existsSync3(path)) return;
+  const lock = z5.object({ pid: z5.number().int().positive() }).parse(JSON.parse(readFileSync3(path, "utf8")));
   try {
     process.kill(lock.pid, 0);
   } catch (error) {
-    if (z3.object({ code: z3.literal("ESRCH") }).safeParse(error).success) {
-      unlinkSync(path);
+    if (z5.object({ code: z5.literal("ESRCH") }).safeParse(error).success) {
+      unlinkSync2(path);
       return;
     }
     throw new Error("Cannot determine whether the ledger is in use.");
@@ -280,8 +604,8 @@ function acquireLock(db) {
   };
   assertStopped(db);
   const lock = `${db}.lock`;
-  writeFileSync(lock, JSON.stringify({ pid: process.pid }), { flag: "wx", mode: 384 });
-  return () => unlinkSync(lock);
+  writeFileSync2(lock, JSON.stringify({ pid: process.pid }), { flag: "wx", mode: 384 });
+  return () => unlinkSync2(lock);
 }
 async function startServices(input) {
   const config = { ...input, ports: { ...input.ports }, db: expandPath(input.db) };
@@ -328,43 +652,208 @@ async function startServices(input) {
   }
 }
 
+// src/cli/config-command.ts
+import { z as z6 } from "zod";
+var common = z6.strictObject({ db: z6.string().optional(), config: z6.string().optional() });
+var showFlags = common.extend({ json: z6.boolean().optional() });
+var editFlags = common.extend({ file: z6.string().min(1).optional() });
+function options(command) {
+  return command.option("--db <path>", "SQLite ledger path").option("--config <path>", "Explicit config file");
+}
+function valueText(value) {
+  return value === void 0 ? "(not set)" : typeof value === "string" ? value : JSON.stringify(value);
+}
+function addConfigCommands(program, output, sources) {
+  const group = options(
+    program.command("config").description("Inspect or edit local configuration")
+  );
+  const details = (flags) => loadConfigDetails(flags.db ? { db: flags.db } : {}, {
+    ...sources,
+    configFile: flags.config ?? sources.configFile
+  });
+  options(
+    group.command("path").description("Show configuration layers and the default write target")
+  ).action((_raw, command) => {
+    const resolved = details(common.parse(command.optsWithGlobals()));
+    output(
+      `${formatLayers(resolved)}
+Default write target: ${resolved.defaultWritePath}
+Use --file to write a different layer; --config selects a read layer.
+`
+    );
+  });
+  options(group.command("show").description("Show the merged effective configuration")).option("--json", "Print the effective configuration as JSON").action((_raw, command) => {
+    const flags = showFlags.parse(command.optsWithGlobals());
+    const resolved = details(flags);
+    output(
+      flags.json ? `${JSON.stringify(resolved.config, null, 2)}
+` : `${formatLayers(resolved)}
+
+${formatEffectiveConfig(resolved.config)}
+
+Ledger: ${resolved.config.db}
+Proxy port: ${resolved.config.ports.proxy}
+Dashboard port: ${resolved.config.ports.dashboard}
+Upstream: ${resolved.config.upstream ?? "(not set)"}
+`
+    );
+  });
+  options(group.command("get <key>").description("Read one effective value by dot path")).action(
+    (key, _raw, command) => {
+      schemaForKey(key);
+      output(
+        `${valueText(configValue(details(common.parse(command.optsWithGlobals())).config, key))}
+`
+      );
+    }
+  );
+  const edit = (key, value, command, unset) => {
+    const flags = editFlags.parse(command.optsWithGlobals());
+    const result = editConfig({
+      key,
+      value,
+      unset,
+      file: flags.file,
+      flags: flags.db ? { db: flags.db } : {},
+      options: { ...sources, configFile: flags.config ?? sources.configFile }
+    });
+    const before = configValue(result.before, key);
+    const after = configValue(result.after, key);
+    const next = unset ? after : result.writtenValue;
+    const beforeContext = amountContext(result.before, key);
+    const afterContext = unset ? amountContext(result.after, key) : result.writtenAmountContext;
+    const human = typeof before === "string" && typeof next === "string" && beforeContext && afterContext && beforeContext.asset === afterContext.asset && beforeContext.network === afterContext.network ? `  (${formatAmount2(before, beforeContext.asset, beforeContext.network)} \u2192 ${formatAmount2(next, afterContext.asset, afterContext.network)})` : "";
+    output(
+      `${key}: ${valueText(before)} \u2192 ${unset ? `(unset in file; effective: ${valueText(after)})` : valueText(next)}${human}
+`
+    );
+    output(result.changed ? `Written to ${result.path}
+` : `No file to change: ${result.path}
+`);
+    if (!result.participates)
+      output(
+        "This file is not an active layer. Select it with --config when starting taximeter.\n"
+      );
+    else if (!unset && JSON.stringify(after) !== JSON.stringify(next))
+      output(
+        `The written value is overridden. Effective ${key}: ${valueText(after)}. Run taximeter config path to inspect the layers.
+`
+      );
+    output("Restart taximeter for this to take effect.\n");
+  };
+  options(
+    group.command("set <key> <value>").description("Validate and atomically write one configuration value")
+  ).option("--file <path>", "Layer to write (default: existing cwd config, otherwise home config)").action(
+    (key, value, _raw, command) => edit(key, value, command, false)
+  );
+  options(group.command("unset <key>").description("Remove a value from a configuration layer")).option("--file <path>", "Layer to write (default: existing cwd config, otherwise home config)").action((key, _raw, command) => edit(key, void 0, command, true));
+}
+
+// src/cli/start-overrides.ts
+import { z as z7 } from "zod";
+var amount = z7.string().min(1).optional();
+var count = z7.string().regex(/^[1-9][0-9]*$/, "Use a positive payment count without units").transform(Number).pipe(z7.number().int().positive().max(Number.MAX_SAFE_INTEGER)).optional();
+var overridesSchema = z7.strictObject({
+  budgetGlobal: amount,
+  budgetTask: amount,
+  budgetAgent: amount,
+  maxPaymentsGlobal: count,
+  maxPaymentsTask: count,
+  maxPaymentsAgent: count,
+  maxSingle: amount,
+  allowHost: z7.array(z7.string().min(1).max(256)).optional(),
+  denyHost: z7.array(z7.string().min(1).max(256)).optional()
+});
+function startOverrides(flags, config) {
+  const budgets = {};
+  const policy = {};
+  const active = [];
+  for (const [scope, amount2, count2] of [
+    ["global", flags.budgetGlobal, flags.maxPaymentsGlobal],
+    ["perTask", flags.budgetTask, flags.maxPaymentsTask],
+    ["perAgent", flags.budgetAgent, flags.maxPaymentsAgent]
+  ]) {
+    if (amount2 === void 0 && count2 === void 0) continue;
+    const budget = config.budgets[scope];
+    const patch = budget ? {} : { asset: "USDC" };
+    if (amount2 !== void 0) {
+      patch.amount = parseAmountInput(amount2, budget?.asset ?? "USDC", budget?.network);
+      active.push({ key: `budgets.${scope}.amount`, value: patch.amount });
+    }
+    if (count2 !== void 0) {
+      patch.maxPayments = count2;
+      active.push({ key: `budgets.${scope}.maxPayments`, value: count2 });
+    }
+    budgets[scope] = patch;
+  }
+  if (flags.maxSingle !== void 0) {
+    policy.maxSinglePayment = parseAmountInput(flags.maxSingle, config.policy.maxSingleAsset);
+    active.push({ key: "policy.maxSinglePayment", value: policy.maxSinglePayment });
+  }
+  if (flags.allowHost !== void 0) {
+    policy.allowHosts = flags.allowHost;
+    active.push({ key: "policy.allowHosts", value: flags.allowHost });
+  }
+  if (flags.denyHost !== void 0) {
+    policy.denyHosts = flags.denyHost;
+    active.push({ key: "policy.denyHosts", value: flags.denyHost });
+  }
+  return { patch: configPatchSchema.parse({ budgets, policy }), active };
+}
+
 // src/cli/program.ts
-var common = z4.strictObject({ db: z4.string().optional(), config: z4.string().optional() });
+var common2 = z8.strictObject({ db: z8.string().optional(), config: z8.string().optional() });
 var port = portInputSchema.optional();
-var startFlags = common.extend({
+var startFlags = common2.extend({
+  ...overridesSchema.shape,
   proxyPort: port,
   dashboardPort: port,
   upstream: httpUrlSchema.optional()
 });
-var reportFlags = common.extend({
-  json: z4.boolean().optional(),
+var reportFlags = common2.extend({
+  json: z8.boolean().optional(),
   task: labelSchema.optional(),
   agent: labelSchema.optional(),
   host: labelSchema.optional()
 });
-var exportFlags = common.extend({
-  json: z4.string().min(1).optional(),
-  csv: z4.string().min(1).optional(),
-  invoice: z4.string().min(1).optional()
+var exportFlags = common2.extend({
+  json: z8.string().min(1).optional(),
+  csv: z8.string().min(1).optional(),
+  invoice: z8.string().min(1).optional()
 }).refine(
   (flags) => [flags.json, flags.csv, flags.invoice].filter(Boolean).length <= 1,
   "Choose one export format"
 );
-var resetFlags = common.extend({ yes: z4.boolean().default(false) });
-function options(command) {
+var resetFlags = common2.extend({ yes: z8.boolean().default(false) });
+function options2(command) {
   return command.option("--db <path>", "SQLite ledger path").option("--config <path>", "Explicit config file");
 }
-function configFrom(flags) {
-  return loadConfig(flags.db ? { db: flags.db } : {}, { configFile: flags.config });
-}
-async function runCli(input, output = (text) => process.stdout.write(text)) {
-  const argv = z4.array(z4.string()).parse(input);
+async function runCli(input, output = (text) => process.stdout.write(text), sources = {}) {
+  const sourceOptions = (flags) => ({
+    ...sources,
+    configFile: flags.config ?? sources.configFile
+  });
+  const configFrom = (flags) => loadConfig(flags.db ? { db: flags.db } : {}, sourceOptions(flags));
+  const argv = z8.array(z8.string()).parse(input);
   const program = new Command().name("taximeter").description("A taximeter for your AI agents.").version(version).exitOverride();
   program.configureOutput({ writeOut: output, writeErr: (text) => process.stderr.write(text) });
-  options(program.command("start").description("Start the local proxy and dashboard")).option("--proxy-port <port>", "Proxy port (0 selects an available port)").option("--dashboard-port <port>", "Dashboard port").option("--upstream <url>", "Forward origin-form requests to this HTTP(S) upstream").action(async (raw) => {
+  options2(program.command("start").description("Start the local proxy and dashboard")).option("--proxy-port <port>", "Proxy port (0 selects an available port)").option("--dashboard-port <port>", "Dashboard port").option("--upstream <url>", "Forward origin-form requests to this HTTP(S) upstream").option(
+    "--budget-global <amount>",
+    "Override the global amount budget (atomic units or e.g. 5USDC)"
+  ).option("--budget-task <amount>", "Override the per-task amount budget").option("--budget-agent <amount>", "Override the per-agent amount budget").option("--max-payments-global <n>", "Override the global payment-count limit").option("--max-payments-task <n>", "Override the per-task payment-count limit").option("--max-payments-agent <n>", "Override the per-agent payment-count limit").option("--max-single <amount>", "Override the single-payment limit").option(
+    "--allow-host <host>",
+    "Allow a host (repeatable; replaces the file's allow-list)",
+    (value, previous = []) => [...previous, value]
+  ).option(
+    "--deny-host <host>",
+    "Deny a host (repeatable; replaces the file's deny-list)",
+    (value, previous = []) => [...previous, value]
+  ).action(async (raw) => {
     const flags = startFlags.parse(raw);
+    const overrides = startOverrides(flags, configFrom(flags));
     const config = loadConfig(
       {
+        ...overrides.patch,
         ...flags.db ? { db: flags.db } : {},
         ...flags.upstream ? { upstream: flags.upstream } : {},
         ports: {
@@ -372,7 +861,7 @@ async function runCli(input, output = (text) => process.stdout.write(text)) {
           ...flags.dashboardPort !== void 0 ? { dashboard: flags.dashboardPort } : {}
         }
       },
-      { configFile: flags.config }
+      sourceOptions(flags)
     );
     const running = await startServices(config);
     output(
@@ -383,6 +872,16 @@ Point an HTTP-proxy-aware agent at http://127.0.0.1:${running.proxyPort}.
 HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
 `
     );
+    const activeOverrides = [
+      ...overrides.active,
+      ...flags.db !== void 0 ? [{ key: "db", value: config.db }] : [],
+      ...flags.upstream !== void 0 ? [{ key: "upstream", value: config.upstream }] : [],
+      ...flags.proxyPort !== void 0 ? [{ key: "ports.proxy", value: flags.proxyPort }] : [],
+      ...flags.dashboardPort !== void 0 ? [{ key: "ports.dashboard", value: flags.dashboardPort }] : []
+    ];
+    for (const active of activeOverrides)
+      output(`Override: ${active.key} = ${valueText(active.value)} (flags; not saved)
+`);
     const shutdown = () => {
       process.off("SIGINT", shutdown);
       process.off("SIGTERM", shutdown);
@@ -393,12 +892,12 @@ HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
     process.once("SIGINT", shutdown);
     process.once("SIGTERM", shutdown);
   });
-  options(
+  options2(
     program.command("report").description("Print exact totals, separately per network and asset")
   ).option("--json", "Machine-readable integer-string totals").option("--task <id>", "Filter by task").option("--agent <id>", "Filter by agent").option("--host <host>", "Filter by host").action((raw) => {
     const flags = reportFlags.parse(raw);
     const db = configFrom(flags).db;
-    const ledger = new Ledger(existsSync3(db) ? db : ":memory:");
+    const ledger = new Ledger(existsSync4(db) ? db : ":memory:");
     try {
       const events = ledger.view().filter(
         (event) => (!flags.task || event.taskId === flags.task) && (!flags.agent || event.agentId === flags.agent) && (!flags.host || event.host === flags.host)
@@ -415,16 +914,16 @@ HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
       ledger.close();
     }
   });
-  options(program.command("export").description("Export the local ledger")).option("--json <file>", "Write JSON to a new file (default: stdout)").option("--csv <file>", "Write CSV with exact counted and authorized amounts").option("--invoice <file>", "Write a printable HTML payment statement").action((raw) => {
+  options2(program.command("export").description("Export the local ledger")).option("--json <file>", "Write JSON to a new file (default: stdout)").option("--csv <file>", "Write CSV with exact counted and authorized amounts").option("--invoice <file>", "Write a printable HTML payment statement").action((raw) => {
     const flags = exportFlags.parse(raw);
     const db = configFrom(flags).db;
-    const ledger = new Ledger(existsSync3(db) ? db : ":memory:");
+    const ledger = new Ledger(existsSync4(db) ? db : ":memory:");
     try {
       const events = ledger.view();
       const data = flags.csv ? toCsv(events) : flags.invoice ? toInvoice(events) : toJson(events);
       const file = flags.csv ?? flags.invoice ?? flags.json;
       if (file) {
-        writeFileSync2(resolve2(file), data, { flag: "wx", mode: 384 });
+        writeFileSync3(resolve2(file), data, { flag: "wx", mode: 384 });
         output(`Exported ${resolve2(file)}
 `);
       } else output(data);
@@ -432,7 +931,7 @@ HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
       ledger.close();
     }
   });
-  options(
+  options2(
     program.command("reset").description("Archive the current ledger after all writers have stopped")
   ).option("--yes", "Confirm archiving the current ledger").action((raw) => {
     const flags = resetFlags.parse(raw);
@@ -442,7 +941,7 @@ HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
       );
     const { db } = configFrom(flags);
     assertStopped(db);
-    if (!existsSync3(db)) {
+    if (!existsSync4(db)) {
       output("No ledger to archive.\n");
       return;
     }
@@ -451,25 +950,33 @@ HTTPS CONNECT is unmetered; use --upstream or withMeter for HTTPS payments.
       const ledger = new Ledger(db);
       ledger.close();
       const archive = `${db.endsWith(".db") ? db.slice(0, -3) : db}.archive-${Date.now()}.db`;
-      if (existsSync3(archive)) throw new Error("Archive path already exists; retry later.");
-      renameSync(db, archive);
+      if (existsSync4(archive)) throw new Error("Archive path already exists; retry later.");
+      renameSync2(db, archive);
       for (const suffix of ["-wal", "-shm"])
-        if (existsSync3(`${db}${suffix}`)) renameSync(`${db}${suffix}`, `${archive}${suffix}`);
+        if (existsSync4(`${db}${suffix}`)) renameSync2(`${db}${suffix}`, `${archive}${suffix}`);
       output(`Archived ${archive}
 `);
     } finally {
       release();
     }
   });
-  options(
+  options2(
     program.command("doctor").description("Check local config and SQLite without network requests")
-  ).action((raw) => {
-    const config = configFrom(common.parse(raw));
-    const ledger = new Ledger(existsSync3(config.db) ? config.db : ":memory:");
+  ).option("--json", "Machine-readable configuration, sources, and local checks").action((raw) => {
+    const flags = common2.extend({ json: z8.boolean().optional() }).parse(raw);
+    const details = loadConfigDetails(flags.db ? { db: flags.db } : {}, sourceOptions(flags));
+    const config = details.config;
+    const ledger = new Ledger(existsSync4(config.db) ? config.db : ":memory:");
     try {
+      const events = ledger.eventCount();
       output(
-        `Configuration: valid
-SQLite: ready (${ledger.events().length} events)
+        flags.json ? `${JSON.stringify({ configuration: "valid", ...details, sqlite: { status: "ready", events }, ledger: config.db, listenerBinding: "127.0.0.1", httpsConnect: "unmetered", networkChecks: "none" }, null, 2)}
+` : `Configuration: valid
+${formatLayers(details)}
+
+${formatEffectiveConfig(config)}
+
+SQLite: ready (${events} events)
 Ledger: ${config.db}
 Listener binding: 127.0.0.1
 HTTPS CONNECT: unmetered
@@ -480,7 +987,12 @@ Network checks: none
       ledger.close();
     }
   });
-  await program.parseAsync(argv, { from: "user" });
+  addConfigCommands(program, output, sources);
+  try {
+    await program.parseAsync(argv, { from: "user" });
+  } catch (error) {
+    throw configError(error);
+  }
 }
 
 // src/cli/index.ts