devflow-kit 3.5.0 → 3.7.0

package/dist/core/migrations.js

@@ -14,6 +14,55 @@ import { writeFileAtomicExclusive } from './fs-atomic.js';
 import { getMemoryDir } from './project-paths.js';
 import { LEGACY_AGENT_KEYS, canonicaliseAgentKeys, parseAgentMappingEnvelope } from './agent-models.js';
 import { migrateLegacyTrackerConventions } from './tracker.js';
+/**
+ * The body of every canonicalise-agent-keys-vN migration: read agent-models.json raw,
+ * apply LEGACY_AGENT_KEYS once, and write the result back atomically when a key changed.
+ * Each migration id passes its own id so that its warnings name it. Idempotent, and a
+ * file with no legacy key is left untouched.
+ */
+function canonicaliseAgentKeysRun(migrationId) {
+    return async (ctx) => {
+        const infos = [];
+        const warnings = [];
+        // Fast path: no legacy keys defined — skip without touching the file.
+        if (Object.keys(LEGACY_AGENT_KEYS).length === 0)
+            return { infos, warnings };
+        const filePath = path.join(ctx.devflowDir, 'agent-models.json');
+        // parseAgentMappingEnvelope handles IO, BOM-strip, JSON parse, and shape validation.
+        // Raw read intentionally avoids readAgentMapping (which would drop unknown fields).
+        const envelope = await parseAgentMappingEnvelope(filePath);
+        if (envelope.kind === 'skip')
+            return { infos, warnings };
+        if (envelope.kind === 'warn') {
+            warnings.push(`${migrationId}: ${envelope.message}`);
+            return { infos, warnings };
+        }
+        const onWarning = (msg) => warnings.push(msg);
+        const { agents: migrated, didMutate, renamed, dropped, guardDropped } = canonicaliseAgentKeys(envelope.rawAgents, onWarning);
+        if (!didMutate)
+            return { infos, warnings };
+        // Write back with the canonical keys, preserving the rest of the envelope.
+        // Idempotent under concurrent execution (no lock needed; see D31 comment above).
+        const updated = { ...envelope.envelope, agents: migrated };
+        try {
+            await writeFileAtomicExclusive(filePath, JSON.stringify(updated, null, 2) + '\n');
+        }
+        catch (err) {
+            warnings.push(`${migrationId}: failed to write ${filePath}: ${err.message}`);
+            return { infos, warnings };
+        }
+        if (renamed.length > 0) {
+            infos.push(`Migrated agent-models.json: renamed ${renamed.map(k => `'${k}' → '${LEGACY_AGENT_KEYS[k]}'`).join(', ')}`);
+        }
+        if (dropped.length > 0) {
+            warnings.push(`${migrationId}: dropped legacy key(s) ${dropped.map(k => `'${k}'`).join(', ')} — the replacement key already holds a value, existing value kept`);
+        }
+        if (guardDropped.length > 0) {
+            warnings.push(`${migrationId}: dropped legacy key(s) ${guardDropped.map(k => `'${k}'`).join(', ')} — skipped due to prototype-pollution guard`);
+        }
+        return { infos, warnings };
+    };
+}
 /**
  * D31: Registry pattern over scattered `if (!applied.includes(...))` conditionals.
  *
@@ -33,9 +82,9 @@ import { migrateLegacyTrackerConventions } from './tracker.js';
  * This was acceptable with an empty MIGRATIONS registry (D37: the vacuous-truth
  * case); this registry's first real entry is added below. Fix deferred.
  *
- * Note how that interacts with `canonicalise-agent-keys-v1`: runGlobalMigration
- * marks a migration applied for ANY non-throwing return, and that entry never
- * throws — it catches every I/O and parse failure and returns it as a *warning*.
+ * Note how that interacts with the `canonicalise-agent-keys-vN` entries: runGlobalMigration
+ * marks a migration applied for ANY non-throwing return, and those entries never
+ * throw — it catches every I/O and parse failure and returns it as a *warning*.
  * So it does NOT hit the unbounded-retry path. It hits the opposite one: a
  * transient EACCES or a failed write records the migration as applied and it
  * never runs again, leaving legacy keys on disk permanently.
@@ -52,47 +101,17 @@ export const MIGRATIONS = [
         id: 'canonicalise-agent-keys-v1',
         description: 'Rename legacy agent keys in ~/.devflow/agent-models.json to their canonical names',
         scope: 'global',
-        async run(ctx) {
-            const infos = [];
-            const warnings = [];
-            // Fast path: no legacy keys defined — skip without touching the file.
-            if (Object.keys(LEGACY_AGENT_KEYS).length === 0)
-                return { infos, warnings };
-            const filePath = path.join(ctx.devflowDir, 'agent-models.json');
-            // parseAgentMappingEnvelope handles IO, BOM-strip, JSON parse, and shape validation.
-            // Raw read intentionally avoids readAgentMapping (which would drop unknown fields).
-            const envelope = await parseAgentMappingEnvelope(filePath);
-            if (envelope.kind === 'skip')
-                return { infos, warnings };
-            if (envelope.kind === 'warn') {
-                warnings.push(`canonicalise-agent-keys-v1: ${envelope.message}`);
-                return { infos, warnings };
-            }
-            const onWarning = (msg) => warnings.push(msg);
-            const { agents: migrated, didMutate, renamed, dropped, guardDropped } = canonicaliseAgentKeys(envelope.rawAgents, onWarning);
-            if (!didMutate)
-                return { infos, warnings };
-            // Write back with the canonical keys, preserving the rest of the envelope.
-            // Idempotent under concurrent execution (no lock needed; see D31 comment above).
-            const updated = { ...envelope.envelope, agents: migrated };
-            try {
-                await writeFileAtomicExclusive(filePath, JSON.stringify(updated, null, 2) + '\n');
-            }
-            catch (err) {
-                warnings.push(`canonicalise-agent-keys-v1: failed to write ${filePath}: ${err.message}`);
-                return { infos, warnings };
-            }
-            if (renamed.length > 0) {
-                infos.push(`Migrated agent-models.json: renamed ${renamed.map(k => `'${k}' → '${LEGACY_AGENT_KEYS[k]}'`).join(', ')}`);
-            }
-            if (dropped.length > 0) {
-                warnings.push(`canonicalise-agent-keys-v1: dropped legacy key(s) ${dropped.map(k => `'${k}'`).join(', ')} — canonical key already present, existing value kept`);
-            }
-            if (guardDropped.length > 0) {
-                warnings.push(`canonicalise-agent-keys-v1: dropped legacy key(s) ${guardDropped.map(k => `'${k}'`).join(', ')} — skipped due to prototype-pollution guard`);
-            }
-            return { infos, warnings };
-        },
+        run: canonicaliseAgentKeysRun('canonicalise-agent-keys-v1'),
+    },
+    {
+        // v1 is already recorded as applied on every machine that upgraded through 2.x, so the
+        // six-agent rename needs an id of its own. Both ids run the same body. On a 1.x machine
+        // v1 runs first and, with the single-hop LEGACY_AGENT_KEYS, already lands every key on its
+        // final slug, so v2 finds nothing to rewrite and makes no write.
+        id: 'canonicalise-agent-keys-v2',
+        description: 'Rename the keys of the six renamed agents in ~/.devflow/agent-models.json to their new names',
+        scope: 'global',
+        run: canonicaliseAgentKeysRun('canonicalise-agent-keys-v2'),
     },
     {
         id: 'tracker-conventions-per-provider-v1',

package/dist/core/model-discovery.js

@@ -61,9 +61,15 @@ const STDOUT_CAP = 262_144;
  * within this window receives SIGTERM followed by a SIGKILL escalation after
  * SIGKILL_GRACE_MS. Zero retries — the stale cache is the retry.
  *
+ * The window must outlast a cold start on a loaded machine: the first exec of
+ * node with the routing runtime took 1.0-5.4 s in measurement while the OS vetted
+ * the new process. A shorter window reports an installed runtime as unknown. The
+ * test harness bounds (tests/model-discovery.test.ts) use a wider margin than this
+ * measured range.
+ *
  * Exported so tests can derive timing bounds without mirroring the literal.
  */
-export const SPAWN_TIMEOUT_MS = 2_000;
+export const SPAWN_TIMEOUT_MS = 6_000;
 /**
  * Grace period (ms) between SIGTERM and SIGKILL escalation. Unreffed so the
  * timer never prevents the Node.js event loop from exiting on its own.

package/dist/core/plugins.js

@@ -34,7 +34,7 @@ export const DEVFLOW_PLUGINS = [
          *
          * Guard 5 reverse (registry-integrity.test.ts, "declared agents are spawned")
          * skips a plugin whose commands spawn nothing — `if (spawned.size === 0)
-         * continue` — and this plugin ships no commands at all. So `learning` and
+         * continue` — and this plugin ships no commands at all. So `curate` and
          * `tracker`, which are spawned by a SessionStart directive rather than by any
          * command, satisfy the reverse check STRUCTURALLY.
          *
@@ -48,11 +48,13 @@ export const DEVFLOW_PLUGINS = [
          * set-equal, both directions, against the `agentType` values present in
          * dist/commands/, and a hook-spawned agent appears in none of them.
          */
-        agents: ['learning', 'tracker'],
+        agents: ['curate', 'tracker'],
         /**
          * D-AGENT-REFS: `agent-references` is a reference-only skill. It holds the Synthesize mode
-         * templates and the Learning maintain step, which those two agents read by explicit path, so
-         * it sits here (core-skills is always installed) and no other plugin lists or requires it.
+         * templates and the Curate maintain step, which those two agents read by explicit path, and
+         * the command branches that D-CMD-REF-HAND moves out of a command (`references/commands/`),
+         * which a command reads by explicit path, so it sits here (core-skills is always installed)
+         * and no other plugin lists or requires it.
          * It is never preloaded: tests/guards/agent-references.test.ts holds that, and the one
          * exception to the repo-wide ban on `disable-model-invocation` names this skill alone.
          */
@@ -102,7 +104,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-implement',
         description: 'Complete task implementation workflow - accepts plan documents, issues, or task descriptions',
         commands: ['/implement'],
-        agents: ['git', 'code', 'code-fix', 'simplify', 'scrutinize', 'evaluate', 'test', 'validate', 'knowledge'],
+        agents: ['git', 'code', 'fix', 'polish', 'harden', 'evaluate', 'test', 'validate', 'knowledge'],
         skills: ['patterns', 'qa', 'quality-gates', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
         requires: [
             'apply-decisions',
@@ -141,7 +143,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-resolve',
         description: 'Process and fix code review issues with blast-radius triage, Code agent fixes, and Validate agent verification',
         commands: ['/resolve'],
-        agents: ['git', 'triage', 'code', 'code-fix', 'simplify', 'validate', 'test', 'knowledge'],
+        agents: ['git', 'triage', 'code', 'fix', 'polish', 'validate', 'test', 'knowledge'],
         skills: ['patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge', 'apply-decisions'],
         requires: [
             'architecture',
@@ -167,7 +169,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-debug',
         description: 'Debugging workflows with competing hypothesis investigation via parallel subagents',
         commands: ['/debug'],
-        agents: ['git', 'synthesize', 'simplify', 'knowledge', 'explore', 'code'],
+        agents: ['git', 'synthesize', 'polish', 'knowledge', 'explore', 'code'],
         skills: ['git', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
         // D-DEBUG-FIX-VIA-CODE: the fix is a Code spawn. Code loads no skill by language or mode
         // (D-NO-RUNTIME-SKILLS), so `requires:` lists only the skills this command, its agents and the
@@ -232,9 +234,9 @@ export const DEVFLOW_PLUGINS = [
     },
     {
         name: 'devflow-self-review',
-        description: 'Self-review workflow: Simplify agent + Scrutinize agent for code quality',
+        description: 'Self-review workflow: Polish agent + Harden agent for code quality',
         commands: ['/self-review'],
-        agents: ['simplify', 'scrutinize', 'validate', 'knowledge'],
+        agents: ['polish', 'harden', 'validate', 'knowledge'],
         skills: ['quality-gates', 'software-design', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
         // D-PRELOAD-TRIM: no agent, command or skill in this plugin's corpus names
         // `testing` (Validate preloads only `worktree-support`), so it is not required here.
@@ -245,7 +247,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-bug-analysis',
         description: 'Proactive bug finding with static and semantic analysis',
         commands: ['/bug-analysis'],
-        agents: ['git', 'diagnose', 'synthesize'],
+        agents: ['git', 'debug', 'synthesize'],
         skills: [
             'apply-decisions',
             'apply-feature-knowledge',
@@ -272,7 +274,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-ambient',
         description: 'Orchestrator ambient mode — session charter, per-prompt reminder, plan handoff',
         commands: [],
-        agents: ['code', 'code-edit', 'validate', 'simplify', 'scrutinize', 'evaluate', 'test', 'skim', 'review', 'git', 'synthesize', 'triage', 'design', 'knowledge', 'research', 'learning', 'explore'],
+        agents: ['code', 'refactor', 'validate', 'polish', 'harden', 'evaluate', 'test', 'skim', 'review', 'git', 'synthesize', 'triage', 'design', 'knowledge', 'research', 'curate', 'explore'],
         skills: [
             'review-methodology',
             'security',
@@ -313,7 +315,7 @@ export const DEVFLOW_PLUGINS = [
         description: 'Dynamic workflow recipes - dependency-aware tickets→plan→build delivery pipeline',
         // Commands compiled from commands/*.mds at build time (build:mds).
         commands: ['/dynamic-tickets', '/dynamic-plan', '/dynamic-build', '/dynamic-profile'],
-        agents: ['code', 'code-fix', 'validate', 'simplify', 'scrutinize', 'evaluate', 'test', 'review', 'git', 'synthesize', 'knowledge', 'design'],
+        agents: ['code', 'fix', 'validate', 'polish', 'harden', 'evaluate', 'test', 'review', 'git', 'synthesize', 'knowledge', 'design'],
         skills: ['apply-decisions', 'apply-feature-knowledge', 'worktree-support', 'docs-framework'],
         requires: [
             'architecture',

package/dist/core/project-paths.js

@@ -46,7 +46,7 @@ export function getFeatureConfigPath(projectRoot) {
 export function getLearningPendingTurnsPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.jsonl');
 }
-/** .devflow/learning/.pending-turns.processing — the claimed batch a Learning run holds while it processes it */
+/** .devflow/learning/.pending-turns.processing — the claimed batch a Curate run holds while it processes it */
 export function getLearningPendingTurnsProcessingPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.processing');
 }
@@ -65,8 +65,8 @@ export function getDecisionsFilePath(projectRoot) {
 export function getPitfallsFilePath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', 'pitfalls.md');
 }
-/** .devflow/learning/learning.json — project-level learning agent tuning config */
-export function getLearningTuningConfigPath(projectRoot) {
+/** .devflow/learning/learning.json — project-level curate agent tuning config */
+export function getCurateTuningConfigPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'learning', 'learning.json');
 }
 /** .devflow/learning/decisions-ledger.jsonl — anchored ledger rows (single source of truth for rendering) */

package/dist/core/tracker.js

@@ -28,6 +28,7 @@
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
+import { describeEchoedValue as describeTrackerValue } from './echo-value.js';
 /**
  * Canonical issue-tracker provider registry.
  *
@@ -193,8 +194,6 @@ export const TRACKER_ATTEMPTS_MAX = 5;
 // ---------------------------------------------------------------------------
 const REGISTRY_SET = new Set(TRACKER_PROVIDER_IDS);
 const VALID_IDS_LIST = TRACKER_PROVIDER_IDS.join(', ');
-/** Longest rejected value echoed back to the terminal, in CODE POINTS. */
-const MAX_ECHOED_VALUE = 40;
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -217,38 +216,11 @@ export function isTrackerProvider(value) {
     return typeof value === 'string' && REGISTRY_SET.has(value);
 }
 /**
- * Render an untrusted provider token for a terminal message.
- *
- * Rejected values are echoed so the user can see what they typed, so they are
- * third-party input at a display sink: control characters (terminal escapes,
- * BEL, newlines) are replaced and the value is truncated. Used by
- * `parseTrackerId`'s error text and by `devflow tracker --status`.
- *
- * Takes `unknown`, and a non-string renders as its TYPE: the module's
- * never-throws contract has to hold for what reaches this sink, not
- * only for what the signature says does — `devflow tracker --status` reads
- * a conventions file's hand-editable frontmatter, and a caller-side guard is one edit
- * from being gone. Naming the type also keeps the render total, where `String()`
- * would hand control to a caller-supplied `toString` — itself both a throw path
- * and an echo path this function exists to close.
+ * Render an untrusted provider token for a terminal message. Used by
+ * `parseTrackerId`'s error text and by `devflow tracker --status`. The sanitizer
+ * itself lives in `echo-value.ts`; this is its tracker-facing name.
  */
-export function describeTrackerValue(raw) {
-    if (typeof raw !== 'string')
-        return `<${raw === null ? 'null' : typeof raw}>`;
-    // The class is written with ESCAPES, never literal control bytes. A raw NUL
-    // makes grep classify this whole file as binary — it prints "Binary file
-    // matches" and skips the lines — so every grep-based sweep over src/core/
-    // silently stops covering tracker.ts while still exiting 0. Pinned by
-    // tests/guards/no-control-bytes.test.ts.
-    // eslint-disable-next-line no-control-regex
-    const stripped = raw.replace(/[\x00-\x1f\x7f]/g, '?');
-    // Cut by CODE POINT. `slice` cuts UTF-16 code units, so a cut landing inside an
-    // astral character (emoji, CJK ext-B) emits the lone surrogate half of it.
-    const points = [...stripped];
-    return points.length > MAX_ECHOED_VALUE
-        ? `${points.slice(0, MAX_ECHOED_VALUE).join('')}…`
-        : stripped;
-}
+export { describeTrackerValue };
 /**
  * Strict boundary parser for a provider token (`--tracker <id>`,
  * `devflow tracker --set <id>`).

package/dist/hud/codex-usage.js

@@ -0,0 +1,247 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readCache, writeCache, hudCacheDir } from '../core/cache.js';
+const CODEX_CACHE_KEY = 'codex-quota';
+const CODEX_CACHE_TTL_MS = 30_000;
+/** Rollouts last modified longer ago than this are not read. */
+export const CODEX_MAX_AGE_MS = 8 * 24 * 60 * 60 * 1000;
+/** The first read of a rollout, and the one larger read when it holds no record. */
+export const CODEX_TAIL_BYTES = 1024 * 1024;
+export const CODEX_TAIL_RETRY_BYTES = 4 * 1024 * 1024;
+const MAX_YEAR_DIRS = 3;
+const MAX_DAY_DIRS = 14;
+const MAX_ROLLOUTS_PER_DAY = 200;
+const MAX_ROLLOUTS_READ = 3;
+const YEAR_DIR = /^\d{4}$/;
+const MONTH_DIR = /^(0[1-9]|1[0-2])$/;
+const DAY_DIR = /^(0[1-9]|[12]\d|3[01])$/;
+const ROLLOUT_FILE = /^rollout-.*\.jsonl$/;
+/**
+ * D-CODEX-LOCAL-LOGS-ONLY: Codex usage comes from the rate-limit records the
+ * Codex CLI already writes to its own session logs under ~/.codex/sessions. The
+ * statusline reads those logs and nothing else: it opens no credential file
+ * (auth.json) and makes no network call, so it cannot leak a token or stall on a
+ * request. Reason: the HUD runs on every prompt under a 2 s budget, and Codex
+ * publishes the account's limits in every model response it logs.
+ *
+ * The directory is always <home>/.codex, as the proxy's Codex credential check
+ * resolves it; a CODEX_HOME override is not honoured.
+ */
+export function codexSessionsDir(home) {
+    return path.join(home, '.codex', 'sessions');
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function makeWindow(minutes, usedPercent, resetsAt) {
+    if (!isFiniteNumber(minutes) || minutes <= 0 || !isFiniteNumber(usedPercent) || !isFiniteNumber(resetsAt)) {
+        return null;
+    }
+    return { minutes, usedPercent: Math.max(0, Math.min(100, usedPercent)), resetsAt };
+}
+function makeUsage(windows, limitReached) {
+    if (windows.length === 0)
+        return null;
+    return {
+        windows: [...windows].sort((a, b) => a.minutes - b.minutes),
+        limitReached: typeof limitReached === 'string' && limitReached !== '' ? limitReached : null,
+    };
+}
+/**
+ * D-CODEX-WINDOW-BY-MINUTES: a window is identified by its window_minutes, never
+ * by the primary/secondary slot it arrives in. Reason: the slots carry different
+ * windows per plan (a prolite plan has the weekly window as primary and no
+ * secondary, a team plan a 5h primary and a weekly secondary), so a slot-keyed
+ * reader would label one plan's weekly window as the other's 5h one.
+ *
+ * Parses one rollout line into usage. Accepts only a token_count event whose
+ * rate_limits are the codex limit with at least one complete window; premium
+ * records, null windows, `rate_limits: null` and malformed lines are skipped.
+ */
+function parseUsageLine(line) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const payload = asRecord(asRecord(record)?.payload);
+    if (payload === null || payload.type !== 'token_count')
+        return null;
+    const limits = asRecord(payload.rate_limits);
+    if (limits === null || limits.limit_id !== 'codex')
+        return null;
+    const windows = [];
+    for (const slot of [limits.primary, limits.secondary]) {
+        const raw = asRecord(slot);
+        const parsed = raw && makeWindow(raw.window_minutes, raw.used_percent, raw.resets_at);
+        if (parsed)
+            windows.push(parsed);
+    }
+    return makeUsage(windows, limits.rate_limit_reached_type);
+}
+/** The last line in `text` that holds a valid record, scanning backwards. */
+function lastUsageIn(text) {
+    const lines = text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        // Cheap prefilter: most lines are not token_count events and are never parsed.
+        if (!lines[i].includes('"token_count"'))
+            continue;
+        const usage = parseUsageLine(lines[i]);
+        if (usage)
+            return usage;
+    }
+    return null;
+}
+/** Read the last `bytes` bytes of `file`. `whole` is true when that covered the entire file. */
+function readTail(file, bytes) {
+    let fd;
+    try {
+        fd = fs.openSync(file, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, bytes);
+        const buf = Buffer.alloc(length);
+        let total = 0;
+        while (total < length) {
+            const read = fs.readSync(fd, buf, total, length - total, size - length + total);
+            if (read === 0)
+                break;
+            total += read;
+        }
+        return { text: buf.toString('utf-8', 0, total), whole: length === size };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * The newest valid record in `file`, from its tail only. The first read takes
+ * CODEX_TAIL_BYTES; if that holds no record and the file is longer, one retry takes
+ * CODEX_TAIL_RETRY_BYTES. Rollouts reach tens of MB, and a tail holds the newest
+ * records.
+ */
+function latestUsageInFile(file) {
+    for (const bytes of [CODEX_TAIL_BYTES, CODEX_TAIL_RETRY_BYTES]) {
+        const tail = readTail(file, bytes);
+        if (tail === null)
+            return null;
+        const usage = lastUsageIn(tail.text);
+        if (usage !== null || tail.whole)
+            return usage;
+    }
+    return null;
+}
+/** Names of the entries of `dir` of one kind matching `pattern`, newest (greatest) first. */
+function listNames(dir, kind, pattern) {
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => (kind === 'dir' ? e.isDirectory() : e.isFile()) && pattern.test(e.name))
+            .map((e) => e.name)
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/** The newest MAX_DAY_DIRS day directories, by name: sessions/YYYY/MM/DD. */
+function recentDayDirs(sessionsDir) {
+    const days = [];
+    for (const year of listNames(sessionsDir, 'dir', YEAR_DIR).slice(0, MAX_YEAR_DIRS)) {
+        for (const month of listNames(path.join(sessionsDir, year), 'dir', MONTH_DIR)) {
+            for (const day of listNames(path.join(sessionsDir, year, month), 'dir', DAY_DIR)) {
+                if (days.length >= MAX_DAY_DIRS)
+                    return days;
+                days.push(path.join(sessionsDir, year, month, day));
+            }
+        }
+    }
+    return days;
+}
+/**
+ * D-CODEX-NEWEST-MTIME: the newest data is in the most recently modified rollout,
+ * not the newest-named one. Reason: a day directory is named for the day its
+ * session started, and Codex keeps appending to a session for days, so a rollout in
+ * an older directory can hold today's records. Only the newest MAX_DAY_DIRS day
+ * directories are searched and rollouts untouched for CODEX_MAX_AGE_MS are
+ * ignored, which bounds the work on a long-lived ~/.codex.
+ */
+function recentRollouts(sessionsDir, now) {
+    const rollouts = [];
+    for (const dayDir of recentDayDirs(sessionsDir)) {
+        for (const name of listNames(dayDir, 'file', ROLLOUT_FILE).slice(0, MAX_ROLLOUTS_PER_DAY)) {
+            const file = path.join(dayDir, name);
+            try {
+                const mtimeMs = fs.statSync(file).mtimeMs;
+                if (now - mtimeMs <= CODEX_MAX_AGE_MS)
+                    rollouts.push({ file, mtimeMs });
+            }
+            catch {
+                // Rollout vanished between listing and stat.
+            }
+        }
+    }
+    return rollouts.sort((a, b) => b.mtimeMs - a.mtimeMs).map((r) => r.file);
+}
+/**
+ * Codex's latest rate-limit record, or null when there is none to show: no sessions
+ * directory, no rollout modified within CODEX_MAX_AGE_MS, or no valid record in the
+ * newest MAX_ROLLOUTS_READ of them (a session that has not yet had a model response
+ * holds no record, so the next-newest rollout is tried).
+ *
+ * @param sessionsDir  Codex's sessions directory (see codexSessionsDir).
+ * @param now          Epoch milliseconds, for the rollout age bound.
+ */
+export function readCodexUsage(sessionsDir, now) {
+    for (const file of recentRollouts(sessionsDir, now).slice(0, MAX_ROLLOUTS_READ)) {
+        const usage = latestUsageInFile(file);
+        if (usage !== null)
+            return usage;
+    }
+    return null;
+}
+function validateCodexUsage(data) {
+    const obj = asRecord(data);
+    if (obj === null || !Array.isArray(obj.windows))
+        return null;
+    const windows = [];
+    for (const entry of obj.windows) {
+        const raw = asRecord(entry);
+        const parsed = raw && makeWindow(raw.minutes, raw.usedPercent, raw.resetsAt);
+        if (!parsed)
+            return null;
+        windows.push(parsed);
+    }
+    return makeUsage(windows, obj.limitReached);
+}
+/**
+ * Codex usage for the statusline: the cached read while it is under 30 s old, else
+ * a fresh read of the logs, cached when it found a record. A run that finds none
+ * caches nothing and rescans, which is a handful of directory reads.
+ */
+export async function gatherCodexUsage(devflowDir, sessionsDir, now = Date.now()) {
+    const cacheDir = hudCacheDir(devflowDir);
+    const cached = readCache(cacheDir, CODEX_CACHE_KEY, validateCodexUsage);
+    if (cached !== null)
+        return cached;
+    const usage = readCodexUsage(sessionsDir, now);
+    if (usage !== null)
+        await writeCache(cacheDir, CODEX_CACHE_KEY, usage, CODEX_CACHE_TTL_MS);
+    return usage;
+}
+//# sourceMappingURL=codex-usage.js.map

package/dist/hud/components/codex-quota.js

@@ -0,0 +1,37 @@
+import { dim, red } from '../colors.js';
+import { renderQuotaWindow } from './usage-quota.js';
+/** "5h" for 300 minutes, "7d" for 10080; any other length reads as whole days, whole hours, else minutes. */
+function windowLabel(minutes) {
+    if (minutes % 1440 === 0)
+        return `${minutes / 1440}d`;
+    if (minutes % 60 === 0)
+        return `${minutes / 60}h`;
+    return `${minutes}m`;
+}
+/**
+ * Codex usage limits, in usage-quota's style: "Codex 5h ███░░░░░ 40% (1h 2m) · 7d ...".
+ *
+ * A window whose resets_at has passed has reset since Codex last logged it, so it
+ * renders as 0% with no countdown rather than as the stale figure. The red
+ * "limited" marker shows while Codex reports a reached limit and at least one
+ * window is still counting down; once every window has reset the limit is lifted
+ * and the stale marker is dropped.
+ */
+export default async function codexQuota(ctx) {
+    const usage = ctx.codexUsage;
+    if (!usage || usage.windows.length === 0)
+        return null;
+    const nowMs = Date.now();
+    const hasReset = (resetsAt) => resetsAt * 1000 <= nowMs;
+    const parts = usage.windows.map((w) => hasReset(w.resetsAt)
+        ? renderQuotaWindow(windowLabel(w.minutes), 0, null)
+        : renderQuotaWindow(windowLabel(w.minutes), w.usedPercent, w.resetsAt));
+    const limited = usage.limitReached !== null && usage.windows.some((w) => !hasReset(w.resetsAt));
+    return {
+        text: dim('Codex ') +
+            parts.map((p) => p.text).join(dim(' · ')) +
+            (limited ? ' ' + red('limited') : ''),
+        raw: 'Codex ' + parts.map((p) => p.raw).join(' · ') + (limited ? ' limited' : ''),
+    };
+}
+//# sourceMappingURL=codex-quota.js.map

package/dist/hud/components/usage-quota.js

@@ -48,7 +48,7 @@ export function formatCountdown(resetsAtEpoch) {
     return `${totalMinutes}m`;
 }
 /** Render a single quota window: "5h ████░░░░ 45% (2h 15m)" */
-function renderQuotaWindow(label, percent, resetsAt) {
+export function renderQuotaWindow(label, percent, resetsAt) {
     const bar = renderBar(Math.round(percent));
     const countdown = resetsAt != null ? formatCountdown(resetsAt) : '';
     const countdownText = countdown ? dim(` (${countdown})`) : '';

package/dist/hud/config.js

@@ -18,6 +18,7 @@ export const HUD_COMPONENTS = [
     'versionBadge',
     'sessionCost',
     'usageQuota',
+    'codexQuota',
     'todoProgress',
     'configCounts',
     'learningCounts',