omniagent 0.1.7 → 0.1.9

package/dist/cli.js

@@ -234,8 +234,9 @@ function buildValidationError(resolution, status, message) {
     errorMessage: message
   };
 }
-async function validateAgentsDir(repoRoot, agentsDir) {
+async function validateAgentsDir(repoRoot, agentsDir, options = {}) {
   const resolution = resolveAgentsDir(repoRoot, agentsDir);
+  const requireWrite = options.requireWrite ?? true;
   const buildNotDirectoryError = () => buildValidationError(
     resolution,
     "notDirectory",
@@ -269,14 +270,16 @@ async function validateAgentsDir(repoRoot, agentsDir) {
     return buildNotDirectoryError();
   }
   try {
-    await access(resolution.resolvedPath, constants.R_OK | constants.W_OK | constants.X_OK);
+    const requiredAccess = constants.R_OK | constants.X_OK | (requireWrite ? constants.W_OK : 0);
+    await access(resolution.resolvedPath, requiredAccess);
   } catch (error) {
     const code = error.code;
     if (code === "EACCES" || code === "EPERM") {
+      const requirement = requireWrite ? "readable, writable, or searchable" : "readable or searchable";
       return buildValidationError(
         resolution,
         "permissionDenied",
-        `Agents directory is not readable, writable, or searchable: ${resolution.resolvedPath}. Check permissions or choose another directory.`
+        `Agents directory is not ${requirement}: ${resolution.resolvedPath}. Check permissions or choose another directory.`
       );
     }
     throw error;
@@ -1308,6 +1311,20 @@ const claudeTarget = {
     instructions: {
       filename: "CLAUDE.md"
     }
+  },
+  usage: {
+    windows: ["hourly", "weekly"],
+    launch: {
+      command: "claude",
+      // Haiku keeps the interactive usage probe on Claude's lowest-cost model family.
+      args: ["--model", "haiku"],
+      cheapModel: "haiku",
+      timeoutMs: 6e4
+    },
+    extract: async (context) => {
+      const { extractClaudeUsage } = await import("./claude-Dmv_YFKX.js");
+      return extractClaudeUsage(context);
+    }
   }
 };
 const codexTarget = {
@@ -1367,6 +1384,27 @@ const codexTarget = {
       filename: "AGENTS.md",
       group: "agents"
     }
+  },
+  usage: {
+    windows: ["hourly", "weekly"],
+    launch: {
+      command: "codex",
+      // Usage probing does not need plugins/apps; disabling them avoids MCP startup work.
+      args: [
+        "--no-alt-screen",
+        "--disable",
+        "apps",
+        "--disable",
+        "computer_use",
+        "--disable",
+        "plugins"
+      ],
+      timeoutMs: 6e4
+    },
+    extract: async (context) => {
+      const { extractCodexUsage } = await import("./codex-D1RuzsY6.js");
+      return extractCodexUsage(context);
+    }
   }
 };
 const FRONTMATTER_MARKER$1 = "---";
@@ -1558,6 +1596,19 @@ const geminiTarget = {
     instructions: {
       filename: "GEMINI.md"
     }
+  },
+  usage: {
+    windows: ["model"],
+    launch: {
+      command: "gemini",
+      // /model inspection does not need a model override; Gemini requires session-scoped trust.
+      args: ["--skip-trust"],
+      timeoutMs: 7e4
+    },
+    extract: async (context) => {
+      const { extractGeminiUsage } = await import("./gemini-CskI3Qjp.js");
+      return extractGeminiUsage(context);
+    }
   }
 };
 const BUILTIN_TARGETS = [
@@ -2513,6 +2564,39 @@ function validateCliDefinition(cli, label, errors) {
     errors.push(`${label}.translate must be a function when provided.`);
   }
 }
+function validateUsageDefinition(usage, label, errors) {
+  if (usage === void 0) {
+    return;
+  }
+  if (!isPlainObject(usage)) {
+    errors.push(`${label} must be an object.`);
+    return;
+  }
+  validateStringArray(usage.windows, `${label}.windows`, errors);
+  if (usage.launch !== void 0) {
+    if (!isPlainObject(usage.launch)) {
+      errors.push(`${label}.launch must be an object.`);
+    } else {
+      if (usage.launch.command !== void 0 && normalizeString(usage.launch.command) === null) {
+        errors.push(`${label}.launch.command must be a non-empty string when provided.`);
+      }
+      if (usage.launch.args !== void 0) {
+        validateStringArray(usage.launch.args, `${label}.launch.args`, errors, {
+          allowEmpty: true
+        });
+      }
+      if (usage.launch.timeoutMs !== void 0 && (typeof usage.launch.timeoutMs !== "number" || !Number.isFinite(usage.launch.timeoutMs) || usage.launch.timeoutMs <= 0)) {
+        errors.push(`${label}.launch.timeoutMs must be a positive number when provided.`);
+      }
+      if (usage.launch.cheapModel !== void 0 && normalizeString(usage.launch.cheapModel) === null) {
+        errors.push(`${label}.launch.cheapModel must be a non-empty string when provided.`);
+      }
+    }
+  }
+  if (typeof usage.extract !== "function") {
+    errors.push(`${label}.extract must be a function.`);
+  }
+}
 function validateTemplate(value, label, allowed, errors) {
   if (typeof value === "function") {
     return;
@@ -2745,6 +2829,7 @@ function validateTargetConfig(options) {
         }
         validateOutputs(entry2.outputs, `${label}.outputs`, errors);
         validateCliDefinition(entry2.cli, `${label}.cli`, errors);
+        validateUsageDefinition(entry2.usage, `${label}.usage`, errors);
       }
     }
   }
@@ -2771,6 +2856,19 @@ function cloneOutputs(outputs) {
 function cloneCli(cli) {
   return cli ? { ...cli } : void 0;
 }
+function cloneUsage(usage) {
+  if (!usage) {
+    return void 0;
+  }
+  return {
+    ...usage,
+    windows: [...usage.windows],
+    launch: usage.launch ? {
+      ...usage.launch,
+      args: usage.launch.args ? [...usage.launch.args] : void 0
+    } : void 0
+  };
+}
 function mergeOutputs(base, override) {
   const merged = { ...cloneOutputs(base) };
   if (!override) {
@@ -2826,6 +2924,7 @@ function resolveTargets(options) {
         aliases: builtIn.aliases ?? [],
         outputs: cloneOutputs(builtIn.outputs),
         cli: cloneCli(builtIn.cli),
+        usage: cloneUsage(builtIn.usage),
         hooks: builtIn.hooks,
         isBuiltIn: true,
         isCustomized: false
@@ -2841,7 +2940,8 @@ function resolveTargets(options) {
         displayName: customTarget.displayName ?? inherited?.displayName ?? customTarget.id,
         aliases: customTarget.aliases ?? inherited?.aliases ?? [],
         outputs: mergedOutputs,
-        cli: customTarget.cli ?? inherited?.cli,
+        cli: cloneCli(customTarget.cli ?? inherited?.cli),
+        usage: cloneUsage(customTarget.usage ?? inherited?.usage),
         hooks: customTarget.hooks ?? inherited?.hooks,
         isBuiltIn: true,
         isCustomized: true
@@ -2854,6 +2954,7 @@ function resolveTargets(options) {
         aliases: customTarget.aliases ?? [],
         outputs: cloneOutputs(customTarget.outputs),
         cli: cloneCli(customTarget.cli),
+        usage: cloneUsage(customTarget.usage),
         hooks: customTarget.hooks,
         isBuiltIn: true,
         isCustomized: true
@@ -2873,7 +2974,8 @@ function resolveTargets(options) {
       displayName: target.displayName ?? inherited?.displayName ?? target.id,
       aliases: target.aliases ?? inherited?.aliases ?? [],
       outputs: mergedOutputs,
-      cli: target.cli ?? inherited?.cli,
+      cli: cloneCli(target.cli ?? inherited?.cli),
+      usage: cloneUsage(target.usage ?? inherited?.usage),
       hooks: target.hooks ?? inherited?.hooks,
       isBuiltIn: false,
       isCustomized: true
@@ -8274,7 +8376,7 @@ function getTargetCliCommands(target) {
   add(target.cli?.modes?.oneShot?.command);
   return commands;
 }
-async function checkCliOnPath(command) {
+async function checkCliOnPath(command, options = {}) {
   const normalized = normalizeCommand(command);
   if (!normalized) {
     return { command: command ?? "", result: "unavailable" };
@@ -8285,7 +8387,7 @@ async function checkCliOnPath(command) {
   if (hasPathSeparator(normalized)) {
     for (const candidate of candidates) {
       const check = await checkExecutable(candidate);
-      if (check.status === "available") {
+      if (check.status === "available" && await isValidCandidate(check.resolvedPath, options.validateCandidate)) {
         return { command: normalized, result: "available", resolvedPath: check.resolvedPath };
       }
       if (check.status === "inconclusive") {
@@ -8313,7 +8415,7 @@ async function checkCliOnPath(command) {
     for (const candidate of candidates) {
       const fullPath = path.join(entry2, candidate);
       const check = await checkExecutable(fullPath);
-      if (check.status === "available") {
+      if (check.status === "available" && await isValidCandidate(check.resolvedPath, options.validateCandidate)) {
         return { command: normalized, result: "available", resolvedPath: check.resolvedPath };
       }
       if (check.status === "inconclusive") {
@@ -8330,6 +8432,16 @@ async function checkCliOnPath(command) {
   }
   return { command: normalized, result: "unavailable" };
 }
+async function isValidCandidate(resolvedPath, validateCandidate) {
+  if (!validateCandidate) {
+    return true;
+  }
+  try {
+    return await validateCandidate(resolvedPath);
+  } catch {
+    return false;
+  }
+}
 async function checkTargetAvailability(target) {
   const commands = getTargetCliCommands(target);
   if (commands.length === 0) {
@@ -8366,7 +8478,7 @@ const DEFAULT_SUPPORTED_TARGETS = BUILTIN_TARGETS.map((target) => target.id).joi
 const LOCAL_CATEGORIES = ["skills", "commands", "agents", "instructions"];
 const LOCAL_CATEGORY_SET = new Set(LOCAL_CATEGORIES);
 const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
-function parseList(value) {
+function parseList$1(value) {
   if (!value) {
     return [];
   }
@@ -8435,7 +8547,7 @@ function parseExcludeLocal(value) {
   if (value === true) {
     return { excludeAll: true, categories: new Set(LOCAL_CATEGORIES), invalid: [] };
   }
-  const list = parseList(value);
+  const list = parseList$1(value);
   if (list.length === 0) {
     return { excludeAll: true, categories: new Set(LOCAL_CATEGORIES), invalid: [] };
   }
@@ -9453,8 +9565,8 @@ Config: auto-discovered as omniagent.config.(ts|mts|cts|js|mjs|cjs) in the agent
   ),
   handler: async (argv) => {
     try {
-      const skipList = parseList(argv.skip);
-      const onlyList = parseList(argv.only);
+      const skipList = parseList$1(argv.skip);
+      const onlyList = parseList$1(argv.only);
       const excludeLocalSelection = parseExcludeLocal(argv.excludeLocal);
       if (excludeLocalSelection.invalid.length > 0) {
         const invalidList = excludeLocalSelection.invalid.join(", ");
@@ -10209,6 +10321,1272 @@ Config: auto-discovered as omniagent.config.(ts|mts|cts|js|mjs|cjs) in the agent
     }
   }
 };
+const MONTHS = /* @__PURE__ */ new Map([
+  ["jan", 0],
+  ["january", 0],
+  ["feb", 1],
+  ["february", 1],
+  ["mar", 2],
+  ["march", 2],
+  ["apr", 3],
+  ["april", 3],
+  ["may", 4],
+  ["jun", 5],
+  ["june", 5],
+  ["jul", 6],
+  ["july", 6],
+  ["aug", 7],
+  ["august", 7],
+  ["sep", 8],
+  ["sept", 8],
+  ["september", 8],
+  ["oct", 9],
+  ["october", 9],
+  ["nov", 10],
+  ["november", 10],
+  ["dec", 11],
+  ["december", 11]
+]);
+const ESCAPE_CHARACTER = String.fromCharCode(27);
+const BELL_CHARACTER = String.fromCharCode(7);
+const OSC_SEQUENCE_PATTERN = new RegExp(
+  `${escapeRegExp(ESCAPE_CHARACTER)}\\][\\s\\S]*?(?:${escapeRegExp(BELL_CHARACTER)}|${escapeRegExp(ESCAPE_CHARACTER)}\\\\)`,
+  "g"
+);
+const CSI_SEQUENCE_PATTERN = new RegExp(
+  `${escapeRegExp(ESCAPE_CHARACTER)}\\[[0-?]*[ -/]*[@-~]`,
+  "g"
+);
+const CHARSET_SEQUENCE_PATTERN = new RegExp(
+  `${escapeRegExp(ESCAPE_CHARACTER)}[()][A-Za-z0-9]`,
+  "g"
+);
+const MODE_SEQUENCE_PATTERN = new RegExp(`${escapeRegExp(ESCAPE_CHARACTER)}[=>]`, "g");
+function makeUsageLimit(options) {
+  const agent = options.agent ?? options.targetId;
+  const resetText = emptyToNull(options.resetText);
+  const window = normalizeUsageWindow(options.window);
+  return {
+    id: [options.targetId, options.scope, window, options.modelId].filter(Boolean).join("."),
+    targetId: options.targetId,
+    agent,
+    scope: options.scope,
+    window,
+    label: options.label,
+    modelId: options.modelId,
+    modelLabel: options.modelLabel,
+    percentUsed: options.percentUsed,
+    percentRemaining: options.percentRemaining,
+    resetAt: parseResetAt(resetText, {
+      now: options.now,
+      sourceTimeZone: options.resetSourceTimeZone ?? "local"
+    }),
+    resetText,
+    raw: options.raw ?? ""
+  };
+}
+function parsePercentUsed(value) {
+  return parsePercent(value, /(\d+(?:\.\d+)?)\s*%\s*used/i);
+}
+function parsePercentRemaining(value) {
+  return parsePercent(value, /(\d+(?:\.\d+)?)\s*%\s*(?:left|remaining)/i);
+}
+function parsePercent(value, pattern = /(\d+(?:\.\d+)?)\s*%/) {
+  const match = pattern.exec(value ?? "");
+  if (match == null) {
+    return null;
+  }
+  return Number(match[1]);
+}
+function parseResetText(value) {
+  const match = /\((resets[^)]*)\)/i.exec(value ?? "");
+  return match == null ? null : match[1].trim();
+}
+function normalizeUsageWindow(window) {
+  const normalized = window.trim().toLowerCase();
+  if (normalized === "5h" || normalized === "five_hour" || normalized === "five-hour" || normalized === "session" || normalized === "hourly") {
+    return "hourly";
+  }
+  if (normalized === "week" || normalized === "current_week" || normalized === "weekly") {
+    return "weekly";
+  }
+  if (normalized === "model") {
+    return "model";
+  }
+  return normalized;
+}
+function cleanControlOutput(raw) {
+  return raw.replace(OSC_SEQUENCE_PATTERN, "").replace(CSI_SEQUENCE_PATTERN, "").replace(CHARSET_SEQUENCE_PATTERN, "").replace(MODE_SEQUENCE_PATTERN, "").replace(/\r/g, "\n").split("\n").map((line) => line.replace(/[ \t]+$/g, "")).join("\n");
+}
+function compactLines(text) {
+  return text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function parseResetAt(resetText, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const sourceTimeZone = options.sourceTimeZone ?? "local";
+  const text = normalizeResetText(resetText);
+  if (!text) {
+    return null;
+  }
+  return parseHourMinuteOnDayMonth(text, now, sourceTimeZone) ?? parseMonthDayAtTime(text, now, sourceTimeZone) ?? parseDayMonthAtTime(text, now, sourceTimeZone) ?? parseTimeOnly(text, now, sourceTimeZone);
+}
+function parseHourMinuteOnDayMonth(text, now, sourceTimeZone) {
+  const match = /^(\d{1,2}):(\d{2})\s+on\s+(\d{1,2})\s+([A-Za-z]+)$/i.exec(text);
+  if (match == null) {
+    return null;
+  }
+  const [, hour, minute, day, monthName] = match;
+  const month = parseMonth(monthName);
+  if (month == null) {
+    return null;
+  }
+  return buildFutureDate(now, sourceTimeZone, {
+    month,
+    day: Number(day),
+    hour: Number(hour),
+    minute: Number(minute)
+  });
+}
+function parseMonthDayAtTime(text, now, sourceTimeZone) {
+  const match = /^([A-Za-z]+)\s+(\d{1,2})(?:\s+at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?)?$/i.exec(
+    text
+  );
+  if (match == null) {
+    return null;
+  }
+  const [, monthName, day, hour = "0", minute = "0", meridiem] = match;
+  const month = parseMonth(monthName);
+  if (month == null) {
+    return null;
+  }
+  return buildFutureDate(now, sourceTimeZone, {
+    month,
+    day: Number(day),
+    hour: parseHour(hour, meridiem),
+    minute: Number(minute)
+  });
+}
+function parseDayMonthAtTime(text, now, sourceTimeZone) {
+  const match = /^(\d{1,2})\s+([A-Za-z]+)(?:\s+at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?)?$/i.exec(
+    text
+  );
+  if (match == null) {
+    return null;
+  }
+  const [, day, monthName, hour = "0", minute = "0", meridiem] = match;
+  const month = parseMonth(monthName);
+  if (month == null) {
+    return null;
+  }
+  return buildFutureDate(now, sourceTimeZone, {
+    month,
+    day: Number(day),
+    hour: parseHour(hour, meridiem),
+    minute: Number(minute)
+  });
+}
+function parseTimeOnly(text, now, sourceTimeZone) {
+  const match = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i.exec(text);
+  if (match == null) {
+    return null;
+  }
+  const [, hour, minute = "0", meridiem] = match;
+  const date = sourceTimeZone === "utc" ? new Date(
+    Date.UTC(
+      now.getUTCFullYear(),
+      now.getUTCMonth(),
+      now.getUTCDate(),
+      parseHour(hour, meridiem),
+      Number(minute)
+    )
+  ) : new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate(),
+    parseHour(hour, meridiem),
+    Number(minute)
+  );
+  if (date <= now) {
+    if (sourceTimeZone === "utc") {
+      date.setUTCDate(date.getUTCDate() + 1);
+    } else {
+      date.setDate(date.getDate() + 1);
+    }
+  }
+  return date.toISOString();
+}
+function buildFutureDate(now, sourceTimeZone, values) {
+  const date = sourceTimeZone === "utc" ? new Date(
+    Date.UTC(now.getUTCFullYear(), values.month, values.day, values.hour, values.minute)
+  ) : new Date(now.getFullYear(), values.month, values.day, values.hour, values.minute);
+  if (date <= now) {
+    if (sourceTimeZone === "utc") {
+      date.setUTCFullYear(date.getUTCFullYear() + 1);
+    } else {
+      date.setFullYear(date.getFullYear() + 1);
+    }
+  }
+  return date.toISOString();
+}
+function normalizeResetText(resetText) {
+  return (resetText ?? "").replace(/^resets\s+/i, "").replace(/\([^)]*\)/g, "").replace(/\s+/g, " ").trim();
+}
+function parseMonth(monthName) {
+  return MONTHS.get(monthName.toLowerCase()) ?? null;
+}
+function parseHour(hourValue, meridiem) {
+  const hour = Number(hourValue);
+  if (meridiem == null) {
+    return hour;
+  }
+  const lower = meridiem.toLowerCase();
+  if (lower === "am") {
+    return hour === 12 ? 0 : hour;
+  }
+  if (lower === "pm") {
+    return hour === 12 ? 12 : hour + 12;
+  }
+  return hour;
+}
+function emptyToNull(value) {
+  return value == null || value === "" ? null : value;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const USAGE_BAR_WIDTH = 12;
+const ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  orange: "\x1B[38;5;208m",
+  red: "\x1B[31m",
+  gray: "\x1B[90m"
+};
+const DEFAULT_USAGE_TIMEOUT_MS = 3e4;
+const MS_PER_MINUTE = 6e4;
+const MS_PER_HOUR = 36e5;
+const MS_PER_DAY = 864e5;
+const DETAILED_RESET_THRESHOLD_MINUTES = 180;
+const RELATIVE_RESET_WIDTH = 6;
+const RESET_WEEKDAY_TIME_FORMATTER = new Intl.DateTimeFormat("en-US", {
+  weekday: "short",
+  hour: "numeric",
+  minute: "2-digit"
+});
+const RESET_DATE_TIME_FORMATTER = new Intl.DateTimeFormat("en-US", {
+  month: "short",
+  day: "numeric",
+  hour: "numeric",
+  minute: "2-digit"
+});
+class UsageExtractionTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`Usage extraction timed out after ${formatDuration(timeoutMs)}.`);
+    this.timeoutMs = timeoutMs;
+  }
+}
+function normalizeOptionalWindow(value) {
+  if (value == null) {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? normalizeUsageWindow(trimmed) : "";
+}
+function normalizeOptionalSort(value) {
+  if (value == null) {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    return "";
+  }
+  return normalized === "reset" || normalized === "left" ? normalized : "";
+}
+function parseTimeoutMs(value) {
+  if (value == null) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m)?$/i.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const amount = Number(match[1]);
+  const unit = match[2]?.toLowerCase() ?? "s";
+  const multiplier = unit === "ms" ? 1 : unit === "m" ? 6e4 : 1e3;
+  const timeoutMs = amount * multiplier;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return null;
+  }
+  return Math.ceil(timeoutMs);
+}
+function resolveTargetTimeoutMs(target, cliTimeoutMs) {
+  return cliTimeoutMs ?? target.usage?.launch?.timeoutMs ?? DEFAULT_USAGE_TIMEOUT_MS;
+}
+function parseList(value) {
+  if (!value) {
+    return [];
+  }
+  const rawValues = Array.isArray(value) ? value : [value];
+  return rawValues.flatMap((entry2) => entry2.split(",")).map((entry2) => entry2.trim().toLowerCase()).filter(Boolean);
+}
+function formatDuration(timeoutMs) {
+  if (timeoutMs % 6e4 === 0) {
+    return `${timeoutMs / 6e4}m`;
+  }
+  if (timeoutMs % 1e3 === 0) {
+    return `${timeoutMs / 1e3}s`;
+  }
+  return `${timeoutMs}ms`;
+}
+function uniqueNormalizedWindows(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const value of values) {
+    const normalized = normalizeUsageWindow(value);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+function formatUsageTargetLabel(targets) {
+  return buildSupportedTargetLabel(targets);
+}
+function formatSupportedUsageTargetsMessage(targets) {
+  const supportedUsageTargets = formatUsageTargetLabel(targets);
+  return supportedUsageTargets ? `Supported usage targets: ${supportedUsageTargets}.` : "No active usage-capable targets are enabled by the current target configuration.";
+}
+function getUsageCommand(target) {
+  return target.usage?.launch?.command;
+}
+async function checkUsageCommandAvailability(target) {
+  const command = getUsageCommand(target)?.trim();
+  if (!command) {
+    return {
+      status: "available",
+      warnings: []
+    };
+  }
+  const check = await checkCliOnPath(command, {
+    validateCandidate: target.id === "codex" && command === "codex" ? validateCodexCommand : void 0
+  });
+  if (check.result === "available") {
+    return {
+      status: "available",
+      warnings: [],
+      command,
+      resolvedPath: check.resolvedPath ?? command
+    };
+  }
+  if (check.result === "inconclusive") {
+    return {
+      status: "unavailable",
+      reason: "Usage CLI availability could not be confirmed.",
+      warnings: check.warning ? [check.warning] : []
+    };
+  }
+  return {
+    status: "unavailable",
+    reason: `Usage CLI not found on PATH: ${command}.`,
+    warnings: []
+  };
+}
+function validateCodexCommand(candidate) {
+  return new Promise((resolve) => {
+    const child = spawn(candidate, ["--version"], {
+      stdio: "ignore"
+    });
+    let settled = false;
+    let timeout;
+    const finish = (valid) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve(valid);
+    };
+    timeout = setTimeout(() => {
+      child.kill();
+      finish(false);
+    }, 2e3);
+    child.on("error", () => finish(false));
+    child.on("exit", (code) => finish(code === 0));
+  });
+}
+function buildContext(options) {
+  const windows = uniqueNormalizedWindows(options.target.usage?.windows ?? []);
+  const launch = {
+    ...options.target.usage?.launch ?? {},
+    timeoutMs: options.timeoutMs
+  };
+  return {
+    targetId: options.target.id,
+    displayName: options.target.displayName,
+    command: options.command ?? getUsageCommand(options.target),
+    window: options.selectedWindow ?? windows[0] ?? "",
+    windows,
+    now: options.now,
+    repoRoot: options.repoRoot,
+    agentsDir: options.agentsDir,
+    homeDir: options.homeDir,
+    launch,
+    signal: options.signal,
+    debug: {
+      enabled: options.debug,
+      includeRawOutput: options.debug,
+      includeScreenSnapshots: options.debug
+    }
+  };
+}
+function filterTargetResult(target, result, selectedWindow) {
+  const normalizedLimits = result.limits.map((limit) => ({
+    ...limit,
+    window: normalizeUsageWindow(limit.window)
+  }));
+  const filteredLimits = selectedWindow == null ? normalizedLimits : normalizedLimits.filter((limit) => limit.window === selectedWindow);
+  const notes = selectedWindow != null && filteredLimits.length === 0 ? [`${target.displayName} reported no usage rows for window "${selectedWindow}".`] : [];
+  return {
+    result: {
+      targetId: result.targetId,
+      displayName: result.displayName,
+      command: result.command,
+      limits: filteredLimits
+    },
+    notes,
+    debug: result.debug ?? []
+  };
+}
+function buildError(target, code, message) {
+  return {
+    targetId: target.id,
+    displayName: target.displayName,
+    code,
+    message
+  };
+}
+async function extractUsageForTarget(options) {
+  try {
+    const extractor = options.target.usage?.extract;
+    if (!extractor) {
+      return {
+        status: "error",
+        target: options.target,
+        error: buildError(
+          options.target,
+          "usage_extractor_missing",
+          `${options.target.displayName} does not have a usage extractor.`
+        ),
+        debug: []
+      };
+    }
+    const result = await withUsageTimeout((signal) => {
+      const context = buildContext({ ...options, signal });
+      return extractor(context);
+    }, options.timeoutMs);
+    const filtered = filterTargetResult(options.target, result, options.selectedWindow);
+    return {
+      status: "success",
+      target: options.target,
+      result: filtered.result,
+      errors: result.errors ?? [],
+      notes: filtered.notes,
+      debug: filtered.debug
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = isUsageTimeoutError(error) ? "usage_extraction_timeout" : "usage_extraction_failed";
+    return {
+      status: "error",
+      target: options.target,
+      error: buildError(options.target, code, message),
+      debug: options.debug ? getErrorDebugArtifacts(error) : []
+    };
+  }
+}
+function isUsageTimeoutError(error) {
+  if (error instanceof UsageExtractionTimeoutError) {
+    return true;
+  }
+  return Boolean(error && typeof error === "object" && error.timedOut);
+}
+function getErrorDebugArtifacts(error) {
+  if (!error || typeof error !== "object") {
+    return [];
+  }
+  const debug = error.debug;
+  if (!Array.isArray(debug)) {
+    return [];
+  }
+  return debug.filter(isDebugArtifact);
+}
+function isDebugArtifact(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const artifact = value;
+  return (artifact.type === "raw-output" || artifact.type === "screen-snapshot") && typeof artifact.label === "string";
+}
+function withUsageTimeout(run, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let settled = false;
+    let timeoutFired = false;
+    let timeout;
+    const settleResolve = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve(value);
+    };
+    const settleReject = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      reject(error);
+    };
+    timeout = setTimeout(() => {
+      timeoutFired = true;
+      const error = new UsageExtractionTimeoutError(timeoutMs);
+      controller.abort(error);
+      setImmediate(() => {
+        settleReject(error);
+      });
+    }, timeoutMs);
+    let promise;
+    try {
+      promise = run(controller.signal);
+    } catch (error) {
+      settleReject(error);
+      return;
+    }
+    promise.then(
+      (value) => {
+        if (timeoutFired) {
+          return;
+        }
+        settleResolve(value);
+      },
+      (error) => {
+        if (timeoutFired && !isUsageTimeoutError(error)) {
+          return;
+        }
+        settleReject(error);
+      }
+    );
+  });
+}
+function buildEnvelope(options) {
+  const envelope = {
+    schemaVersion: 1,
+    generatedAt: options.generatedAt,
+    targets: options.targets,
+    errors: options.errors,
+    notes: options.notes
+  };
+  if (options.debug && options.debugArtifacts.length > 0) {
+    envelope.debug = options.debugArtifacts;
+  }
+  return envelope;
+}
+function buildCommandError(code, message) {
+  return {
+    targetId: "usage",
+    displayName: "Usage command",
+    code,
+    message
+  };
+}
+function printError(options) {
+  if (options.json) {
+    const error = options.target ? buildError(options.target, options.code, options.message) : buildCommandError(options.code, options.message);
+    console.log(
+      JSON.stringify(
+        buildEnvelope({
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          targets: [],
+          errors: [error],
+          notes: [],
+          debug: false,
+          debugArtifacts: []
+        }),
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`Error: ${options.message}`);
+  }
+  process.exit(options.exitCode);
+}
+function percentText(value) {
+  return value == null ? "unknown" : `${Math.round(value)}%`;
+}
+function usageBar(percentUsed) {
+  if (percentUsed == null) {
+    return `[${"?".repeat(USAGE_BAR_WIDTH)}]`;
+  }
+  const clamped = Math.max(0, Math.min(100, percentUsed));
+  const filled = clamped === 0 ? 0 : Math.max(1, Math.round(clamped / 100 * USAGE_BAR_WIDTH));
+  return `[${"#".repeat(filled)}${"-".repeat(USAGE_BAR_WIDTH - filled)}]`;
+}
+function formatResetValue(limit, now) {
+  const resetAt = parseDate(limit.resetAt);
+  if (resetAt != null) {
+    return formatLocalResetAt(resetAt, now);
+  }
+  const value = limit.resetText ?? "-";
+  return value === "-" ? value : value.replace(/^resets\s+/i, "");
+}
+function parseDate(value) {
+  if (!value) {
+    return null;
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+function formatLocalResetAt(resetAt, now) {
+  const relative = formatResetDuration(resetAt.getTime() - now.getTime()).padEnd(
+    RELATIVE_RESET_WIDTH
+  );
+  return `${relative} (${formatResetExact(resetAt, now)})`;
+}
+function formatResetDuration(milliseconds) {
+  if (milliseconds <= 0) {
+    return "now";
+  }
+  const totalMinutes = Math.max(1, Math.ceil(milliseconds / MS_PER_MINUTE));
+  if (totalMinutes < 60) {
+    return `${totalMinutes}m`;
+  }
+  if (totalMinutes < DETAILED_RESET_THRESHOLD_MINUTES) {
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return minutes === 0 ? `${hours}h` : `${hours}h${minutes}m`;
+  }
+  if (milliseconds >= MS_PER_DAY) {
+    return `${Math.ceil(milliseconds / MS_PER_DAY)}d`;
+  }
+  return `${Math.round(milliseconds / MS_PER_HOUR)}h`;
+}
+function formatResetExact(resetAt, now) {
+  const dayDifference = localDayIndex(resetAt) - localDayIndex(now);
+  if (dayDifference >= 0 && dayDifference <= 7) {
+    return RESET_WEEKDAY_TIME_FORMATTER.format(resetAt);
+  }
+  return RESET_DATE_TIME_FORMATTER.format(resetAt);
+}
+function localDayIndex(date) {
+  return Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()) / MS_PER_DAY;
+}
+function formatLimitLabel(limit) {
+  return limit.label ?? limit.modelLabel ?? limit.modelId ?? formatWindowLabel(limit.window);
+}
+function formatLimitLabels(limits) {
+  const baseLabels = limits.map(formatLimitLabel);
+  const duplicateLabels = new Set(
+    baseLabels.filter((label, index) => baseLabels.indexOf(label) !== index)
+  );
+  return limits.map((limit, index) => {
+    const baseLabel = baseLabels[index] ?? formatLimitLabel(limit);
+    if (!duplicateLabels.has(baseLabel) || !limit.scope) {
+      return baseLabel;
+    }
+    if (limit.scope === "main") {
+      return baseLabel;
+    }
+    return `${formatScopeLabel(limit.scope)} ${baseLabel}`;
+  });
+}
+function formatScopeLabel(scope) {
+  return scope.replace(/[_-]+/g, " ").split(/\s+/).filter(Boolean).map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join(" ");
+}
+function formatWindowLabel(window) {
+  if (window === "hourly") {
+    return "5h";
+  }
+  if (window === "weekly") {
+    return "Weekly";
+  }
+  return window;
+}
+function formatUsageAgentName(targetId, displayName) {
+  return targetId === "codex" && displayName === "OpenAI Codex" ? "Codex CLI" : displayName;
+}
+function formatUsageTable(envelope, sortKey) {
+  const useColor = shouldUseColor();
+  const generatedAt = parseDate(envelope.generatedAt) ?? /* @__PURE__ */ new Date();
+  const rows = [];
+  for (const target of envelope.targets) {
+    const limitLabels = formatLimitLabels(target.limits);
+    const agentName = formatUsageAgentName(target.targetId, target.displayName);
+    target.limits.forEach((limit, index) => {
+      rows.push({
+        status: "ok",
+        agent: sortKey == null && index > 0 ? "" : agentName,
+        limitLabel: limitLabels[index] ?? formatLimitLabel(limit),
+        reset: formatResetValue(limit, generatedAt),
+        limit
+      });
+    });
+  }
+  for (const error of envelope.errors) {
+    rows.push({
+      status: "error",
+      agent: formatUsageAgentName(error.targetId, error.displayName),
+      limitLabel: "error",
+      message: error.message
+    });
+  }
+  const rendered = [renderUsageTable(sortUsageRows(rows, sortKey), useColor)];
+  if (envelope.notes.length > 0) {
+    rendered.push("", ...envelope.notes.map((note) => color(`Note: ${note}`, "dim", useColor)));
+  }
+  return rendered.join("\n");
+}
+function sortUsageRows(rows, sortKey) {
+  if (sortKey == null) {
+    return rows;
+  }
+  return rows.map((row, index) => ({ row, index })).sort((left, right) => {
+    const leftValue = usageSortValue(left.row, sortKey);
+    const rightValue = usageSortValue(right.row, sortKey);
+    if (leftValue == null && rightValue == null) {
+      return left.index - right.index;
+    }
+    if (leftValue == null) {
+      return 1;
+    }
+    if (rightValue == null) {
+      return -1;
+    }
+    if (leftValue !== rightValue) {
+      return leftValue - rightValue;
+    }
+    return left.index - right.index;
+  }).map(({ row }) => row);
+}
+function usageSortValue(row, sortKey) {
+  if (row.status === "error") {
+    return null;
+  }
+  if (sortKey === "left") {
+    return row.limit.percentRemaining;
+  }
+  const resetAt = parseDate(row.limit.resetAt);
+  return resetAt?.getTime() ?? null;
+}
+function renderUsageTable(rows, useColor) {
+  const widths = {
+    agent: maxWidth(
+      "Agent",
+      rows.map((row) => row.agent)
+    ),
+    limit: maxWidth(
+      "Limit",
+      rows.map((row) => row.limitLabel)
+    ),
+    usage: maxWidth("Usage", rows.map(usageCellText)),
+    left: maxWidth("Left", rows.map(leftCellText)),
+    reset: maxWidth("Reset", rows.map(resetCellText))
+  };
+  const headerLine = [
+    pad("Agent", widths.agent),
+    pad("Limit", widths.limit),
+    pad("Left", widths.left),
+    pad("Usage", widths.usage),
+    pad("Reset", widths.reset)
+  ].join("  ").trimEnd();
+  const separatorLine = [
+    "-".repeat(widths.agent),
+    "-".repeat(widths.limit),
+    "-".repeat(widths.left),
+    "-".repeat(widths.usage),
+    "-".repeat(widths.reset)
+  ].join("  ").trimEnd();
+  return [
+    color(headerLine, "bold", useColor),
+    color(separatorLine, "dim", useColor),
+    ...rows.map((row) => renderUsageRow(row, widths, useColor))
+  ].join("\n");
+}
+function renderUsageRow(row, widths, useColor) {
+  return [
+    pad(row.agent, widths.agent),
+    pad(row.limitLabel, widths.limit),
+    renderLeftCell(row, widths.left, useColor),
+    renderUsageCell(row, widths.usage, useColor),
+    renderResetCell(row, widths.reset, useColor)
+  ].join("  ").trimEnd();
+}
+function usageCellText(row) {
+  if (row.status === "error") {
+    return "failed";
+  }
+  return `${usageBar(row.limit.percentUsed)} ${percentText(row.limit.percentUsed).padStart(4)} used`;
+}
+function leftCellText(row) {
+  if (row.status === "error") {
+    return "-";
+  }
+  return percentText(row.limit.percentRemaining);
+}
+function resetCellText(row) {
+  if (row.status === "error") {
+    return `Error: ${row.message}`;
+  }
+  return row.reset;
+}
+function renderUsageCell(row, width, useColor) {
+  const text = usageCellText(row);
+  const padding = " ".repeat(Math.max(0, width - text.length));
+  if (row.status === "error") {
+    return `${color(text, "red", useColor)}${padding}`;
+  }
+  const severity = usageSeverity(row.limit.percentUsed);
+  const used = percentText(row.limit.percentUsed).padStart(4);
+  return `${color(usageBar(row.limit.percentUsed), severity, useColor)} ${color(
+    used,
+    severity,
+    useColor
+  )} used${padding}`;
+}
+function renderLeftCell(row, width, useColor) {
+  const text = leftCellText(row);
+  const padding = " ".repeat(Math.max(0, width - text.length));
+  if (row.status === "error") {
+    return `${color(text, "gray", useColor)}${padding}`;
+  }
+  return `${color(text, remainingSeverity(row.limit.percentRemaining), useColor)}${padding}`;
+}
+function renderResetCell(row, width, useColor) {
+  const text = resetCellText(row);
+  const padding = " ".repeat(Math.max(0, width - text.length));
+  const style = row.status === "error" ? "red" : "gray";
+  return `${color(text, style, useColor)}${padding}`;
+}
+function usageSeverity(percentUsed) {
+  if (percentUsed == null) {
+    return "gray";
+  }
+  if (percentUsed >= 95) {
+    return "red";
+  }
+  if (percentUsed >= 80) {
+    return "orange";
+  }
+  if (percentUsed >= 60) {
+    return "yellow";
+  }
+  return "green";
+}
+function remainingSeverity(percentRemaining) {
+  if (percentRemaining == null) {
+    return "gray";
+  }
+  if (percentRemaining <= 5) {
+    return "red";
+  }
+  if (percentRemaining <= 20) {
+    return "orange";
+  }
+  if (percentRemaining <= 40) {
+    return "yellow";
+  }
+  return "green";
+}
+function maxWidth(header, values) {
+  return Math.max(header.length, ...values.map((value) => value.length));
+}
+function pad(value, width) {
+  return value.padEnd(width);
+}
+function color(value, style, useColor) {
+  if (!useColor) {
+    return value;
+  }
+  return `${ANSI[style]}${value}${ANSI.reset}`;
+}
+function shouldUseColor() {
+  if (process.env.FORCE_COLOR != null && process.env.FORCE_COLOR !== "0") {
+    return true;
+  }
+  if (process.env.NO_COLOR != null) {
+    return false;
+  }
+  return Boolean(process.stdout.isTTY);
+}
+async function runUsageCommand(argv) {
+  const positionalTargets = argv.targets ?? [];
+  const onlyTargets = parseList(argv.only);
+  const jsonOutput = Boolean(argv.json || argv.debug);
+  const debugOutput = Boolean(argv.debug);
+  const selectedWindow = normalizeOptionalWindow(argv.window);
+  const sortKey = normalizeOptionalSort(argv.sort);
+  const cliTimeoutMs = parseTimeoutMs(argv.timeout);
+  if (selectedWindow === "") {
+    printError({
+      json: jsonOutput,
+      code: "invalid_window",
+      message: "--window must be a non-empty value.",
+      exitCode: 2
+    });
+    return null;
+  }
+  if (sortKey === "") {
+    printError({
+      json: jsonOutput,
+      code: "invalid_sort",
+      message: "--sort must be one of: reset, left.",
+      exitCode: 2
+    });
+    return null;
+  }
+  if (sortKey != null && jsonOutput) {
+    printError({
+      json: jsonOutput,
+      code: "sort_json_unsupported",
+      message: "--sort is only supported for the human table output.",
+      exitCode: 2
+    });
+    return null;
+  }
+  if (cliTimeoutMs === null) {
+    printError({
+      json: jsonOutput,
+      code: "invalid_timeout",
+      message: "--timeout must be a positive duration. Use seconds by default, or units like 500ms, 5s, or 1m.",
+      exitCode: 2
+    });
+    return null;
+  }
+  if (argv.only != null && onlyTargets.length === 0) {
+    printError({
+      json: jsonOutput,
+      code: "invalid_only",
+      message: "--only must include at least one target.",
+      exitCode: 2
+    });
+    return null;
+  }
+  if (positionalTargets.length > 1) {
+    printError({
+      json: jsonOutput,
+      code: "too_many_targets",
+      message: "omniagent usage accepts at most one target.",
+      exitCode: 2
+    });
+    return null;
+  }
+  if (positionalTargets.length > 0 && onlyTargets.length > 0) {
+    printError({
+      json: jsonOutput,
+      code: "conflicting_target_selection",
+      message: "Use either a positional target or --only, not both.",
+      exitCode: 2
+    });
+    return null;
+  }
+  const startDir = process.cwd();
+  const repoRoot = await findRepoRoot(startDir) ?? startDir;
+  const agentsDirResolution = resolveAgentsDir(repoRoot, argv.agentsDir);
+  if (agentsDirResolution.source === "override") {
+    const validation2 = await validateAgentsDir(repoRoot, argv.agentsDir, { requireWrite: false });
+    if (validation2.validationStatus !== "valid") {
+      printError({
+        json: jsonOutput,
+        code: "invalid_agents_dir",
+        message: validation2.errorMessage,
+        exitCode: 1
+      });
+      return null;
+    }
+  }
+  const agentsDir = agentsDirResolution.resolvedPath;
+  const homeDir = os.homedir();
+  const { config } = await loadTargetConfig({ repoRoot, agentsDir });
+  const validation = validateTargetConfig({ config, builtIns: BUILTIN_TARGETS });
+  if (!validation.valid) {
+    printError({
+      json: jsonOutput,
+      code: "invalid_target_config",
+      message: `Invalid target configuration:
+- ${validation.errors.join("\n- ")}`,
+      exitCode: 1
+    });
+    return null;
+  }
+  const resolved = resolveTargets({ config: validation.config, builtIns: BUILTIN_TARGETS });
+  const targetResolver = createTargetNameResolver(resolved.targets);
+  const usageCapableTargets = resolved.targets.filter((target) => target.usage);
+  const supportedUsageTargetsMessage = formatSupportedUsageTargetsMessage(usageCapableTargets);
+  const usingOnlySelection = onlyTargets.length > 0;
+  const explicitTargetNames = positionalTargets[0] ? [positionalTargets[0]] : onlyTargets;
+  let selectedTargets;
+  const resolvedUsageCommands = /* @__PURE__ */ new Map();
+  if (explicitTargetNames.length > 0) {
+    const selectedIds = [];
+    const unknownTargetNames = [];
+    for (const targetName of explicitTargetNames) {
+      const resolvedName = targetResolver.resolveTargetName(targetName);
+      if (!resolvedName) {
+        unknownTargetNames.push(targetName);
+        continue;
+      }
+      if (!selectedIds.includes(resolvedName)) {
+        selectedIds.push(resolvedName);
+      }
+    }
+    if (unknownTargetNames.length > 0) {
+      const unknownLabel = unknownTargetNames.join(", ");
+      const message = usingOnlySelection ? `Unknown target name(s): ${unknownLabel}. ${supportedUsageTargetsMessage}` : `Unknown target: ${unknownLabel}. ${supportedUsageTargetsMessage}`;
+      printError({
+        json: jsonOutput,
+        code: "unknown_target",
+        message,
+        exitCode: 2
+      });
+      return null;
+    }
+    const requestedTargets = selectedIds.flatMap((targetId) => {
+      const target = resolved.byId.get(targetId.toLowerCase());
+      return target ? [target] : [];
+    });
+    const unsupportedTargets = requestedTargets.filter((target) => !target.usage);
+    if (unsupportedTargets.length > 0) {
+      const unsupportedLabel = unsupportedTargets.map((target) => target.displayName).join(", ");
+      printError({
+        json: jsonOutput,
+        code: "usage_unsupported",
+        message: `${unsupportedLabel} does not support usage extraction. ${supportedUsageTargetsMessage}`,
+        exitCode: 2,
+        target: unsupportedTargets.length === 1 ? unsupportedTargets[0] : void 0
+      });
+      return null;
+    }
+    const requestedUsageIds = new Set(selectedIds);
+    selectedTargets = usageCapableTargets.filter((target) => requestedUsageIds.has(target.id));
+    const availabilityResults = await Promise.all(
+      selectedTargets.map(async (target) => ({
+        target,
+        availability: await checkUsageCommandAvailability(target)
+      }))
+    );
+    const unavailableResults = availabilityResults.filter(
+      ({ availability }) => availability.status !== "available"
+    );
+    if (unavailableResults.length > 0) {
+      if (jsonOutput) {
+        const now2 = /* @__PURE__ */ new Date();
+        const envelope2 = buildEnvelope({
+          generatedAt: now2.toISOString(),
+          targets: [],
+          errors: unavailableResults.map(
+            ({ target, availability }) => buildError(target, "cli_unavailable", availability.reason ?? "CLI not found on PATH.")
+          ),
+          notes: [],
+          debug: debugOutput,
+          debugArtifacts: []
+        });
+        console.log(JSON.stringify(envelope2, null, 2));
+      } else if (unavailableResults.length === 1) {
+        const unavailableResult = unavailableResults[0];
+        if (unavailableResult) {
+          const { target, availability } = unavailableResult;
+          const message = availability.reason ?? "CLI not found on PATH.";
+          console.error(
+            `Error: ${target.displayName} usage extraction requires its CLI. ${message}`
+          );
+        }
+      } else {
+        console.error(
+          [
+            "Error: Some requested usage CLIs are unavailable:",
+            ...unavailableResults.map(({ target, availability }) => {
+              const message = availability.reason ?? "CLI not found on PATH.";
+              return `- ${target.displayName}: ${message}`;
+            })
+          ].join("\n")
+        );
+      }
+      process.exit(1);
+      return null;
+    }
+    for (const { target, availability } of availabilityResults) {
+      const resolvedCommand = availability.resolvedPath ?? availability.command;
+      if (resolvedCommand) {
+        resolvedUsageCommands.set(target.id, resolvedCommand);
+      }
+    }
+  } else {
+    const availabilityResults = await Promise.all(
+      usageCapableTargets.map(async (target) => ({
+        target,
+        availability: await checkUsageCommandAvailability(target)
+      }))
+    );
+    selectedTargets = [];
+    for (const { target, availability } of availabilityResults) {
+      if (availability.status !== "available") {
+        continue;
+      }
+      selectedTargets.push(target);
+      const resolvedCommand = availability.resolvedPath ?? availability.command;
+      if (resolvedCommand) {
+        resolvedUsageCommands.set(target.id, resolvedCommand);
+      }
+    }
+    if (selectedTargets.length === 0) {
+      const supportedUsageTargets = formatUsageTargetLabel(usageCapableTargets);
+      const message = supportedUsageTargets ? `No installed active usage-capable agents were found. Install one of: ${supportedUsageTargets}.` : "No active usage-capable targets are enabled by the current target configuration.";
+      if (jsonOutput) {
+        const now2 = /* @__PURE__ */ new Date();
+        const envelope2 = buildEnvelope({
+          generatedAt: now2.toISOString(),
+          targets: [],
+          errors: [],
+          notes: [message],
+          debug: debugOutput,
+          debugArtifacts: []
+        });
+        console.log(JSON.stringify(envelope2, null, 2));
+      } else {
+        console.log(message);
+      }
+      return {
+        envelope: buildEnvelope({
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          targets: [],
+          errors: [],
+          notes: [message],
+          debug: debugOutput,
+          debugArtifacts: []
+        }),
+        exitCode: 0,
+        selectedTargets
+      };
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  const outcomes = await Promise.all(
+    selectedTargets.map(
+      (target) => extractUsageForTarget({
+        target,
+        repoRoot,
+        agentsDir,
+        homeDir,
+        selectedWindow,
+        timeoutMs: resolveTargetTimeoutMs(target, cliTimeoutMs),
+        debug: debugOutput,
+        now,
+        command: resolvedUsageCommands.get(target.id)
+      })
+    )
+  );
+  const targets = [];
+  const errors = [];
+  const notes = [];
+  const debugArtifacts = [];
+  for (const outcome of outcomes) {
+    if (outcome.status === "success") {
+      targets.push(outcome.result);
+      errors.push(...outcome.errors);
+      notes.push(...outcome.notes);
+      debugArtifacts.push(
+        ...outcome.debug.map((artifact) => ({
+          ...artifact,
+          targetId: outcome.target.id,
+          displayName: outcome.target.displayName
+        }))
+      );
+    } else {
+      errors.push(outcome.error);
+      debugArtifacts.push(
+        ...outcome.debug.map((artifact) => ({
+          ...artifact,
+          targetId: outcome.target.id,
+          displayName: outcome.target.displayName
+        }))
+      );
+    }
+  }
+  const envelope = buildEnvelope({
+    generatedAt: now.toISOString(),
+    targets,
+    errors,
+    notes,
+    debug: debugOutput,
+    debugArtifacts
+  });
+  const exitCode = errors.length > 0 ? 1 : 0;
+  if (jsonOutput) {
+    console.log(JSON.stringify(envelope, null, 2));
+  } else {
+    console.log(formatUsageTable(envelope, sortKey));
+  }
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+  return { envelope, exitCode, selectedTargets };
+}
+const usageCommand = {
+  command: "usage [targets..]",
+  describe: "Report usage limits for installed agent CLIs",
+  builder: (yargsInstance) => yargsInstance.usage(
+    "omniagent usage [target] [--only <targets>] [--sort <key>] [--window <window>] [--timeout <seconds>] [--agentsDir <path>] [--json] [--debug]"
+  ).positional("targets", {
+    type: "string",
+    array: true,
+    describe: "Optional target id or alias."
+  }).option("window", {
+    type: "string",
+    describe: "Filter usage rows by window (hourly, weekly, 5h, or a custom window)."
+  }).option("only", {
+    type: "string",
+    describe: "Comma-separated target ids or aliases to report usage for."
+  }).option("sort", {
+    type: "string",
+    describe: "Globally sort table rows by reset or left."
+  }).option("timeout", {
+    type: "string",
+    describe: "Per-agent extraction timeout. Bare numbers are seconds; units include ms, s, and m."
+  }).option("agentsDir", {
+    type: "string",
+    describe: "Override the agents directory (relative paths resolve from the project root, or the current directory outside a repo)",
+    defaultDescription: DEFAULT_AGENTS_DIR,
+    coerce: (value) => {
+      if (typeof value !== "string") {
+        return value;
+      }
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : void 0;
+    }
+  }).option("json", {
+    type: "boolean",
+    describe: "Print a stable JSON envelope."
+  }).option("debug", {
+    type: "boolean",
+    describe: "Print JSON and include extractor debug artifacts when available."
+  }).epilog(
+    "Usage extraction may launch agent TUIs and may incur cost if an agent reads repo context on startup. omniagent uses cheap/minimal launch settings where possible."
+  ),
+  handler: async (argv) => {
+    await runUsageCommand(argv);
+  }
+};
 const EXIT_CODES = {
   success: 0,
   "execution-error": 1,
@@ -10879,7 +12257,7 @@ function resolveVersion() {
   return "0.0.0";
 }
 const VERSION = resolveVersion();
-const KNOWN_COMMANDS = /* @__PURE__ */ new Set(["hello", "greet", "echo", "sync", "dev", "profiles"]);
+const KNOWN_COMMANDS = /* @__PURE__ */ new Set(["hello", "greet", "echo", "sync", "dev", "profiles", "usage"]);
 const SHIM_CAPABILITIES = [
   "Capabilities by agent:",
   "  codex: approval, sandbox, output, model, web",
@@ -10929,7 +12307,7 @@ function runCli(argv = process.argv, options = {}) {
     console.error(formatError(message, args));
     const exitCode = isCommandInvocation(args) ? 1 : 2;
     process.exit(exitCode);
-  }).command(helloCommand).command(greetCommand).command(echoCommand).command(syncCommand).command(devCommand).command(profilesCommand).command(
+  }).command(helloCommand).command(greetCommand).command(echoCommand).command(syncCommand).command(devCommand).command(profilesCommand).command(usageCommand).command(
     "$0",
     "omniagent CLI",
     (yargsInstance) => yargsInstance.usage("omniagent [flags] --agent <target-id> [-- <agent flags>]").example("omniagent --agent codex", "Start an interactive session (default mode).").example('omniagent -p "Summarize the repo" --agent codex', "Run a one-shot prompt.").example("omniagent --agent codex -- --some-flag", "Pass through agent-specific flags.").option("prompt", {
@@ -10989,5 +12367,11 @@ if (!entry) {
   }
 }
 export {
+  compactLines as a,
+  parsePercentRemaining as b,
+  cleanControlOutput as c,
+  parseResetText as d,
+  makeUsageLimit as m,
+  parsePercentUsed as p,
   runCli
 };