tldr-experts 0.31.0 → 0.32.0

package/dist/hooks/{chunk-3r0hhgcf.js → chunk-whvae1vw.js}

@@ -5,11 +5,13 @@ import {
   DEFAULT_ON_HOST_TOKENS_EXCEED,
   WAVES_FILE,
   asRunBudget,
+  buildProgress,
   nowRfc3339,
   spentBasis,
+  storyDependsOn,
   tallyOf,
   validateRunBudget
-} from "./chunk-me0kzc6k.js";
+} from "./chunk-5at77jx8.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -47,13 +49,16 @@ import {
   FRAMEWORK_ROOT,
   MAX_ITEM_CHARS,
   PLAN_STATUSES,
+  PROJECT_FRAMEWORK_DIR,
   listRunDirs,
+  parseHandoff,
   parseYaml,
-  parseYamlRepairing
+  parseYamlRepairing,
+  withoutSrcToken
 } from "./chunk-9bd6b3xf.js";
 
 // src/core/statusline/runSnapshot.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5 } from "node:fs";
 import { join as join4 } from "node:path";
 
 // src/core/run/RunStore.ts
@@ -653,23 +658,123 @@ var PLAN_SHAPE_RULES = [
   {
     issue: "#319",
     text: "**End-to-end coverage is not the last story.** Either a test-harness story runs in W1 and later stories " + "depend on it and run against it, or each UI or feature story carries the e2e command in its own dod. A " + "final e2e story that depends on everything is the story never reached. The `plan` check names a command " + "some stories of one epic and repo carry and a sibling does not — an advisory: say in that story why not."
+  },
+  {
+    issue: "#365",
+    text: "**A story that adds an invariant over EXISTING data lands in the same story as, or in a wave after, the " + "story that makes existing rows and fixtures satisfy it.** A check constraint, a `NOT NULL`, a required " + "field or a validation rule written ahead of the story that populates what it enforces makes that earlier " + "story's own dod structurally red — every fixture the enforcing story's own tests run against still lacks " + "the value, and two stories in the SAME wave run in separate worktrees that never see each other's writes, " + "so 'later wave' is the only way one story's data can satisfy another's rule. If the invariant must land " + "first, write it NON-ENFORCING — nullable, consistency-only, no constraint — and let the later story " + "tighten it once the data exists. The `plan` check refuses a story whose acceptance or test plan names an " + "enforcement over a field a later story's acceptance or test plan names populating."
   }
 ];
 
 // src/core/run/runOutcome.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
 import { join as join3 } from "node:path";
 
 // src/core/build/handoff.ts
 var LINE_BREAK_MARK = "⏎";
 var LINE_BREAK_NOTE = `\`${LINE_BREAK_MARK}\` marks a line break inside a quoted command; the review log beside this file ` + "keeps the command verbatim.";
 var FINDING_STATUS_RE = new RegExp(`—\\s+(${PLAN_STATUSES.join("|")})\\s+—`);
+function findingStatus(bullet) {
+  const found = FINDING_STATUS_RE.exec(bullet)?.[1];
+  return found === undefined ? null : found;
+}
+var FINDING_ID_RE = /^\s*(?:[-*]\s+)?(\S+)\s+·\s/;
+function findingId(bullet) {
+  return FINDING_ID_RE.exec(bullet)?.[1] ?? null;
+}
 var FINDING_REASON_RE = new RegExp(`—\\s+(?:${PLAN_STATUSES.join("|")})\\s+—\\s+[^:]*:\\s*(\\S.*)$`);
+function findingReason(bullet) {
+  const found = FINDING_REASON_RE.exec(withoutSrcToken(bullet).trimEnd())?.[1];
+  return found === undefined ? null : found.trim();
+}
 
 // src/core/build/dependencyHold.ts
+function dependencyIsPending(status) {
+  return status === "review" || status === "in_progress";
+}
+function decidingHold(holds) {
+  return holds.find((hold) => !dependencyIsPending(hold.status)) ?? holds[0] ?? null;
+}
+function dependencyWaitReason(held) {
+  return `it waits on dependency ${held.id}, which is \`${held.status}\` and is offered again by the next ` + `invocation; ${held.id} \`done\` is what releases it, and no reopen is owed`;
+}
 var NOT_A_HOLD_REASON = "its block is not a dependency hold — a reviewer, a DoD or a developer recorded it, " + "and reopening a dependency does not answer that; `tldrx story reopen <id>` does";
 
 // src/core/run/runOutcome.ts
 var BUILD_HANDOFF = join3(BUILD_PHASE, "handoff.md");
+var FINDINGS = "Findings";
+var REASON_NOT_RECORDED = "no reason recorded — `04-build/handoff.md` carries no `## Findings` bullet for it";
+function storiesView(runDir) {
+  const progress = buildProgress(runDir);
+  if (progress === null)
+    return null;
+  const stories = progress.waves.flatMap((wave) => wave.stories);
+  const counts = {
+    total: stories.length,
+    done: stories.filter((s) => s.status === "done").length,
+    in_progress: stories.filter((s) => s.status === "in_progress").length,
+    review: stories.filter((s) => s.status === "review").length,
+    blocked: stories.filter((s) => s.status === "blocked").length,
+    todo: stories.filter((s) => s.status === "todo").length
+  };
+  const reasons = blockedReasons(runDir);
+  const statusById = new Map(stories.map((story) => [story.id, story.status]));
+  const unfinished = stories.filter((story) => story.status !== "done").map((story) => {
+    const waitingOn = story.status === "todo" && !progress.implicit ? pendingHold(storyDependsOn(runDir, story.id), statusById) : null;
+    return {
+      id: story.id,
+      status: story.status,
+      reason: reasons.get(story.id) ?? REASON_NOT_RECORDED,
+      ...waitingOn === null ? {} : { waitingOn }
+    };
+  });
+  const waiting = unfinished.find((story) => story.waitingOn !== undefined);
+  return {
+    counts,
+    unfinished,
+    firstBlocked: unfinished.find((story) => story.status === "blocked") ?? null,
+    firstWaiting: waiting?.waitingOn === undefined ? null : { id: waiting.id, waitingOn: waiting.waitingOn, reason: dependencyWaitReason(waiting.waitingOn) }
+  };
+}
+function pendingHold(dependsOn, statusById) {
+  const holds = [];
+  for (const id of dependsOn) {
+    const status = statusById.get(id);
+    if (status === undefined || status === "done")
+      continue;
+    holds.push({ id, status });
+  }
+  const deciding = decidingHold(holds);
+  return deciding !== null && dependencyIsPending(deciding.status) ? deciding : null;
+}
+function blockedReasons(runDir) {
+  const out = new Map;
+  const path = join3(runDir, BUILD_HANDOFF);
+  if (!existsSync2(path))
+    return out;
+  let text;
+  try {
+    text = readFileSync3(path, "utf8");
+  } catch {
+    return out;
+  }
+  let bullets;
+  try {
+    bullets = parseHandoff(text).sections.find((section) => section.name === FINDINGS)?.bullets.map((b) => b.text) ?? [];
+  } catch {
+    return out;
+  }
+  for (const bullet of bullets) {
+    if (findingStatus(bullet) === "done")
+      continue;
+    const id = findingId(bullet);
+    const reason = findingReason(bullet);
+    if (id === null || reason === null)
+      continue;
+    if (!out.has(id))
+      out.set(id, reason);
+  }
+  return out;
+}
 var NO_BUILD_PHASE = "this run's workflow has no Build phase, so no story could be delivered";
 function describeRunOutcome(outcome) {
   if (outcome === undefined)
@@ -689,6 +794,7 @@ function statusWithOutcome(status, outcome) {
 
 // src/core/run/autoGate.ts
 var AUTO_GATE_ACTOR = "auto";
+var RATE_LIMIT_RESUME_NOTE_PREFIX = "run auto resumed this stage: its auto gate was held by an unfinished " + "story a rate-limit warning parked, and the provider's own clock has since cleared it.";
 var RETRYABLE_CONDITIONS = new Set(["checks", "claim-sources"]);
 var AUTO_GATE_REFUSED_PREFIX = "auto-gate refused — held by: ";
 var HELD_SEPARATOR = " · ";
@@ -725,7 +831,15 @@ function describeGateSignature(sig) {
 }
 
 // src/core/facilitator/skipIf.ts
-import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync4 } from "node:fs";
+
+// src/core/facilitator/seedSolution.ts
+var WHAT_STAGE_OWN_INPUT_PREFIXES = [
+  `${PROJECT_FRAMEWORK_DIR}/memory/`,
+  `${PROJECT_FRAMEWORK_DIR}/map/`
+];
+
+// src/core/facilitator/skipIf.ts
 function phaseDirs(runDir) {
   try {
     return readdirSync(runDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^0[1-9]-/.test(entry.name)).map((entry) => entry.name).sort();
@@ -734,19 +848,19 @@ function phaseDirs(runDir) {
   }
 }
 function openQuestionIds(path) {
-  if (!existsSync2(path))
+  if (!existsSync3(path))
     return [];
   try {
-    return openBlocks(parseQuestions(readFileSync3(path, "utf8")).blocks).map((block) => block.id);
+    return openBlocks(parseQuestions(readFileSync4(path, "utf8")).blocks).map((block) => block.id);
   } catch {
     return [];
   }
 }
 function blockingQuestionIds(path) {
-  if (!existsSync2(path))
+  if (!existsSync3(path))
     return [];
   try {
-    return openBlocks(parseQuestions(readFileSync3(path, "utf8")).blocks).filter((block) => !isAdvisory(block)).map((block) => block.id);
+    return openBlocks(parseQuestions(readFileSync4(path, "utf8")).blocks).filter((block) => !isAdvisory(block)).map((block) => block.id);
   } catch {
     return [];
   }
@@ -828,10 +942,10 @@ function fromTolerantRead(root) {
 }
 function readBudgetMirror(runDir) {
   const path = join4(runDir, "run.yml");
-  if (!existsSync3(path))
+  if (!existsSync4(path))
     return { ceiling_usd: 0, spent_usd: 0 };
   try {
-    const text = readFileSync4(path, "utf8");
+    const text = readFileSync5(path, "utf8");
     return {
       ceiling_usd: numberAfter(text, "ceiling_usd"),
       spent_usd: numberAfter(text, "spent_usd")
@@ -848,16 +962,306 @@ function numberAfter(text, key) {
 // src/core/run/waiting.ts
 import { basename as basename2, join as join6 } from "node:path";
 
+// src/core/facilitator/agentEvents.ts
+function rateLimitLine(frame) {
+  const parts = [frame.status];
+  if (frame.utilization !== null)
+    parts.push(`${String(Math.round(frame.utilization * 100))}% of`);
+  parts.push(frame.window === null ? "the provider's window" : `the ${frame.window} window`);
+  if (frame.resetsAt !== null)
+    parts.push(`· resets ${new Date(frame.resetsAt * 1000).toISOString()}`);
+  return parts.join(" ");
+}
+var STRUCTURED_OUTPUT_TOOL = "StructuredOutput";
+class AgentStream {
+  openTools = new Map;
+  seenQuestions = new Set;
+  provider;
+  codexStructured = null;
+  questionCount = 0;
+  constructor(provider = "claude") {
+    this.provider = provider;
+  }
+  push(line) {
+    const doc = parseLine(line);
+    if (doc === null)
+      return [];
+    if (this.provider === "codex")
+      return this.codex(doc);
+    switch (doc.type) {
+      case "system":
+        return this.system(doc);
+      case "assistant":
+        return this.assistant(doc);
+      case "user":
+        return this.user(doc);
+      case "result":
+        return this.result(doc);
+      case "rate_limit_event":
+        return this.rateLimit(doc);
+      default:
+        return [];
+    }
+  }
+  codex(doc) {
+    if (doc.type === "thread.started") {
+      return [{ kind: "start", model: null, sessionId: str(doc.thread_id) }];
+    }
+    if (doc.type === "turn.failed") {
+      return [{ kind: "error", message: str(obj(doc.error)?.message) ?? "the Codex turn failed" }];
+    }
+    if (doc.type === "turn.completed") {
+      const usage = obj(doc.usage);
+      const structured = this.codexStructured;
+      return [
+        {
+          kind: "cost",
+          usd: null,
+          inputTokens: num(usage?.input_tokens),
+          outputTokens: num(usage?.output_tokens),
+          cacheCreationTokens: num(usage?.cache_write_input_tokens),
+          cacheReadTokens: num(usage?.cached_input_tokens)
+        },
+        ...this.questions(obj(structured)?.questions_asked),
+        { kind: "done", ok: true, structured, costUsd: 0 }
+      ];
+    }
+    if (doc.type !== "item.started" && doc.type !== "item.completed")
+      return [];
+    const item = obj(doc.item);
+    if (item === null)
+      return [];
+    const id = str(item.id);
+    if (item.type === "agent_message") {
+      const message = str(item.text);
+      if (message === null)
+        return [];
+      const structured = parseLine(message);
+      if (structured !== null)
+        this.codexStructured = structured;
+      return [{ kind: "text", text: message }];
+    }
+    if (item.type !== "command_execution")
+      return [];
+    const command = str(item.command);
+    if (doc.type === "item.started") {
+      return [{ kind: "tool", id, name: "Bash", target: command }];
+    }
+    return [{
+      kind: "tool-done",
+      id,
+      name: "Bash",
+      ok: item.status === "completed" && (item.exit_code === 0 || item.exit_code === null),
+      ms: null,
+      countsAsRead: true
+    }];
+  }
+  system(doc) {
+    if (doc.subtype !== "init")
+      return [];
+    return [{ kind: "start", model: str(doc.model), sessionId: str(doc.session_id) }];
+  }
+  rateLimit(doc) {
+    const info = obj(doc.rate_limit_info);
+    const status = str(info?.status);
+    if (info === null || status === null)
+      return [];
+    const window = str(info.rateLimitType);
+    const named = window === null ? null : obj(obj(info.unifiedWindows)?.[window]);
+    return [{
+      kind: "rate-limit",
+      status,
+      window,
+      utilization: maybeNum(info.utilization) ?? maybeNum(named?.utilization),
+      resetsAt: maybeNum(info.resetsAt) ?? maybeNum(named?.resetsAt)
+    }];
+  }
+  assistant(doc) {
+    const message = obj(doc.message);
+    const blocks = Array.isArray(message?.content) ? message.content : [];
+    const at = millis(doc.timestamp);
+    const events = [];
+    for (const raw of blocks) {
+      const block = obj(raw);
+      if (block === null)
+        continue;
+      if (block.type === "text") {
+        const text = str(block.text);
+        if (text !== null && text.trim() !== "")
+          events.push({ kind: "text", text: text.trim() });
+        continue;
+      }
+      if (block.type !== "tool_use")
+        continue;
+      const name = str(block.name) ?? "tool";
+      const id = str(block.id);
+      if (name === STRUCTURED_OUTPUT_TOOL) {
+        events.push(...this.questions(obj(block.input)?.questions_asked));
+        continue;
+      }
+      if (id !== null)
+        this.openTools.set(id, { name, at });
+      events.push({ kind: "tool", id, name, target: toolTarget(name, obj(block.input)) });
+    }
+    const usage = obj(message?.usage);
+    if (usage !== null) {
+      events.push({
+        kind: "cost",
+        usd: null,
+        inputTokens: num(usage.input_tokens),
+        outputTokens: num(usage.output_tokens),
+        cacheCreationTokens: num(usage.cache_creation_input_tokens),
+        cacheReadTokens: num(usage.cache_read_input_tokens)
+      });
+    }
+    return events;
+  }
+  user(doc) {
+    const message = obj(doc.message);
+    const blocks = Array.isArray(message?.content) ? message.content : [];
+    const at = millis(doc.timestamp);
+    const events = [];
+    for (const raw of blocks) {
+      const block = obj(raw);
+      if (block === null || block.type !== "tool_result")
+        continue;
+      const id = str(block.tool_use_id);
+      const open = id === null ? undefined : this.openTools.get(id);
+      if (id !== null)
+        this.openTools.delete(id);
+      if (open === undefined)
+        continue;
+      events.push({
+        kind: "tool-done",
+        id,
+        name: open.name,
+        ok: block.is_error !== true,
+        ms: at === null || open.at === null ? null : Math.max(0, at - open.at)
+      });
+    }
+    return events;
+  }
+  result(doc) {
+    const events = [];
+    const structured = doc.structured_output ?? null;
+    events.push(...this.questions(obj(structured)?.questions_asked));
+    const cost = typeof doc.total_cost_usd === "number" ? doc.total_cost_usd : 0;
+    const usage = obj(doc.usage);
+    events.push({
+      kind: "cost",
+      usd: cost,
+      inputTokens: num(usage?.input_tokens),
+      outputTokens: num(usage?.output_tokens),
+      cacheCreationTokens: num(usage?.cache_creation_input_tokens),
+      cacheReadTokens: num(usage?.cache_read_input_tokens)
+    });
+    const ok = doc.is_error !== true;
+    if (!ok) {
+      const errors = Array.isArray(doc.errors) ? doc.errors : [];
+      const first = errors.find((entry) => typeof entry === "string");
+      events.push({ kind: "error", message: first ?? str(doc.subtype) ?? "the sub-agent reported an error" });
+    }
+    events.push({ kind: "done", ok, structured, costUsd: cost });
+    return events;
+  }
+  questions(value) {
+    if (!Array.isArray(value))
+      return [];
+    const events = [];
+    for (const entry of value) {
+      if (typeof entry !== "string" || entry.trim() === "")
+        continue;
+      const text = entry.trim();
+      if (this.seenQuestions.has(text))
+        continue;
+      this.seenQuestions.add(text);
+      this.questionCount += 1;
+      events.push({ kind: "question", index: this.questionCount, text });
+    }
+    return events;
+  }
+}
+function toolTarget(name, input) {
+  if (input === null)
+    return null;
+  const named = (() => {
+    switch (name) {
+      case "Read":
+      case "Write":
+      case "NotebookEdit":
+        return input.file_path ?? input.notebook_path;
+      case "Edit":
+      case "MultiEdit":
+        return input.file_path;
+      case "Bash":
+      case "BashOutput":
+        return input.command;
+      case "Grep":
+      case "Glob":
+        return input.pattern;
+      case "WebFetch":
+        return input.url;
+      case "WebSearch":
+        return input.query;
+      case "Task":
+      case "Agent":
+        return input.description;
+      case "TodoWrite":
+        return null;
+      default:
+        return null;
+    }
+  })();
+  if (typeof named === "string" && named !== "")
+    return named;
+  if (named !== null && named !== undefined)
+    return null;
+  for (const value of Object.values(input)) {
+    if (typeof value === "string" && value !== "")
+      return value;
+  }
+  return null;
+}
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === "" || !trimmed.startsWith("{"))
+    return null;
+  try {
+    const doc = JSON.parse(trimmed);
+    return typeof doc === "object" && doc !== null && !Array.isArray(doc) ? doc : null;
+  } catch {
+    return null;
+  }
+}
+function obj(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function str(value) {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+function num(value) {
+  return typeof value === "number" ? value : 0;
+}
+function maybeNum(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function millis(value) {
+  if (typeof value !== "string")
+    return null;
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? at : null;
+}
+
 // src/core/run/prepared.ts
-import { existsSync as existsSync4, readdirSync as readdirSync2, statSync } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync2, statSync } from "node:fs";
 import { join as join5 } from "node:path";
 var PENDING_JSON = "pending.json";
 function preparedBundles(runDir, stageId) {
   const dir = join5(runDir, ".agent", stageId);
-  if (!existsSync4(dir))
+  if (!existsSync5(dir))
     return [];
   const found = [];
-  if (existsSync4(join5(dir, PENDING_JSON)))
+  if (existsSync5(join5(dir, PENDING_JSON)))
     found.push(dir);
   let entries;
   try {
@@ -873,7 +1277,7 @@ function preparedBundles(runDir, stageId) {
     } catch {
       continue;
     }
-    if (existsSync4(join5(child, PENDING_JSON)))
+    if (existsSync5(join5(child, PENDING_JSON)))
       found.push(child);
   }
   return found;
@@ -900,6 +1304,52 @@ function startedHeadless(runDir, stageId) {
   return lastStageStartMode(runDir, stageId) === "headless";
 }
 
+// src/core/run/rateLimitPark.ts
+function currentRateLimitPark(runDir, stageId) {
+  let events;
+  try {
+    events = EventLog.forRun(runDir).readAll().events;
+  } catch {
+    return null;
+  }
+  let stageStartIndex = -1;
+  for (let index = events.length - 1;index >= 0; index -= 1) {
+    const event = events[index];
+    if (event !== undefined && event.stage === stageId && event.type === "stage.started") {
+      stageStartIndex = index;
+      break;
+    }
+  }
+  if (stageStartIndex === -1)
+    return null;
+  let park = null;
+  for (let index = events.length - 1;index >= stageStartIndex; index -= 1) {
+    const event = events[index];
+    if (event === undefined || event.type !== "agent.rate_limited" || event.stage !== stageId)
+      continue;
+    const payload = event.payload;
+    const parked = payload.parked;
+    if (typeof parked !== "string" || parked === "")
+      continue;
+    park = {
+      status: typeof payload.status === "string" ? payload.status : "",
+      window: typeof payload.window === "string" ? payload.window : null,
+      utilization: typeof payload.utilization === "number" ? payload.utilization : null,
+      resetsAt: typeof payload.resets_at === "number" ? payload.resets_at : null,
+      parked
+    };
+    break;
+  }
+  if (park === null)
+    return null;
+  const view = storiesView(runDir);
+  if (view === null || view.unfinished.length === 0)
+    return null;
+  if (view.unfinished.some((story) => story.status !== "todo"))
+    return null;
+  return park;
+}
+
 // src/core/run/waiting.ts
 var MOVABLE_KINDS = [
   "gate",
@@ -949,6 +1399,16 @@ function waitingFor(run, runDir) {
   switch (entry.stage.status) {
     case "awaiting_gate": {
       const held = heldByNote(entry.stage.gate?.note ?? "");
+      if (held.length === 1 && held[0] === "stories") {
+        const park = currentRateLimitPark(runDir, entry.stage.id);
+        if (park !== null) {
+          return {
+            kind: "gate",
+            message: `gate on ${entry.phase.id}/${entry.stage.id} — parked by a rate-limit warning ` + `(${rateLimitLine(park)})` + (park.resetsAt === null ? " — it stated no reset instant, so nothing here knows when it resumes" : `, resumes automatically at ${new Date(park.resetsAt * 1000).toISOString()}`),
+            questions: open
+          };
+        }
+      }
       return {
         kind: "gate",
         message: `gate on ${entry.phase.id}/${entry.stage.id}` + (held.length === 0 ? "" : ` — held by ${held.join(", ")}`) + ` — \`tldrx approve\` or \`tldrx reject --note "…"\``,

package/dist/hooks/session-start.js

@@ -20,7 +20,7 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-3r0hhgcf.js";
+} from "./chunk-whvae1vw.js";
 import"./chunk-ae6bkfs5.js";
 import {
   expertsDir,
@@ -28,7 +28,7 @@ import {
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-me0kzc6k.js";
+} from "./chunk-5at77jx8.js";
 import {
   isFinished
 } from "./chunk-akemhezh.js";

package/dist/hooks/statusline.js

@@ -2,9 +2,9 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-3r0hhgcf.js";
+} from "./chunk-whvae1vw.js";
 import"./chunk-ae6bkfs5.js";
-import"./chunk-me0kzc6k.js";
+import"./chunk-5at77jx8.js";
 import"./chunk-akemhezh.js";
 import"./chunk-8ds2ret8.js";
 import"./chunk-yyhwf3bp.js";