@opsee/cli 0.11.12 → 0.11.18

package/src/foreman/core/triage.ts

@@ -10,9 +10,9 @@
  * drains the turn; run.ts records the outcome, since the Run Record write is the commit (ADR-0009).
  */
 import type { Account } from "../account.js";
+import { driveShortTurn, type DrainedTurn } from "./short-turn.js";
 import type { TrackerTask } from "../tracker-adapter.js";
-import type { AdapterEvent, WorkerAdapter } from "../worker-adapter.js";
-import { tail } from "./install.js";
+import type { WorkerAdapter } from "../worker-adapter.js";
 import type { WorkContract } from "./work-contract.js";
 
 /** Reading a few files and writing one section needs a handful of agentic turns, not a Worker's
@@ -81,58 +81,21 @@ export interface TriageTurnRequest {
   now: () => number;
 }
 
-export interface DrainedTurn {
-  terminal: Extract<AdapterEvent, { type: "completed" | "failed" }>;
-  durationMs: number;
-  outputTail: string;
-  /** The vendor's rate-limit report, when one came (story 30). A Triage turn is a turn on the
-   * Account like any other, so a limit it hit Pauses the Account; the terminal event alone does not
-   * carry the reset the vendor named, which is what decides how long. */
-  rateLimit?: { resetAt?: string; message: string };
-}
+export type { DrainedTurn };
 
-/** Runs one Triage turn to its terminal event, logging progress the way the dispatch loop does. */
+/** Runs one Triage turn to its terminal event. */
 export async function driveTriageTurn(req: TriageTurnRequest): Promise<DrainedTurn> {
   const maxTurns = Math.min(TRIAGE_MAX_TURNS, req.maxTurns ?? TRIAGE_MAX_TURNS);
-  const started = req.now();
-  const handle = req.worker.launch({
+  req.log(`triage: ${req.account.vendor} turn on ${req.task.identifier} in ${req.workspace.path} (at most ${maxTurns} turns)`);
+  return driveShortTurn({
+    worker: req.worker,
     account: req.account,
     cwd: req.workspace.path,
     prompt: triagePrompt(req.task, req.contract, req.workspace),
+    label: "triage",
     maxTurns,
     stallTimeoutMs: req.stallTimeoutMs,
+    log: req.log,
+    now: req.now,
   });
-  req.log(`triage: ${req.account.vendor} turn on ${req.task.identifier} in ${req.workspace.path} (at most ${maxTurns} turns)`);
-  const output: string[] = [];
-  let terminal: DrainedTurn["terminal"] | undefined;
-  let rateLimit: DrainedTurn["rateLimit"];
-  for await (const event of handle.events) {
-    switch (event.type) {
-      case "started":
-        req.log(`triage: session ${event.sessionId}`);
-        break;
-      case "output":
-        for (const line of event.text.split("\n")) {
-          output.push(line);
-          req.log(`  | ${line}`);
-        }
-        break;
-      case "tool":
-        req.log(`  tool ${event.name}`);
-        break;
-      case "rate_limited":
-        rateLimit = { resetAt: event.resetAt, message: event.message };
-        req.log(`triage: rate limited: ${event.message}${event.resetAt ? ` (resets ${event.resetAt})` : ""}`);
-        break;
-      case "stalled":
-        req.log(`triage: stalled, no output for ${event.silentMs}ms`);
-        break;
-      case "completed":
-      case "failed":
-        terminal = event;
-        break;
-    }
-  }
-  if (!terminal) throw new Error("Worker Adapter contract violated: the event stream ended without a terminal event");
-  return { terminal, durationMs: req.now() - started, outputTail: tail(output.join("\n")), rateLimit };
 }

package/src/foreman/core/verifier.ts

@@ -46,7 +46,8 @@ import { RunEventInputSchema, type RunEvent, type RunEventInput, type RunVerific
 import { parseOpseeJson, readYamlBlock, type OpseeConfigFiles } from "../../opsee-config.js";
 import type { Account } from "../account.js";
 import { foremanLocalDir } from "../local-dir.js";
-import { RECIPE_KEY, recipeFromConfig, startApp, waitForReady, type RunRecipe, type VerifyMode } from "../run-recipe.js";
+import { RECIPE_KEY, recipeFromConfig, startable, startApp, waitForReady, type RunRecipe, type StartableRecipe, type VerifyMode } from "../run-recipe.js";
+import { discoverStart, type StartAnswer } from "./start-discovery.js";
 import type { TrackerTask } from "../tracker-adapter.js";
 import { parseVerdict, VERDICT_CONTRACT, type Defect, type Verdict } from "../verdict.js";
 import type { AdapterEvent, McpServerSpec, WorkerAdapter } from "../worker-adapter.js";
@@ -423,6 +424,10 @@ export interface VerifierOptions {
    * default). */
   mcpFor?: (outputDir: string, allowedOrigins: readonly string[]) => McpServerSpec;
   ports?: PortLease;
+  /** How the Foreman works out a start command the Run Recipe does not carry (core/
+   * start-discovery.ts). A Start turn by default; a test hands in an answer instead. Set it to a
+   * function that answers with a reason to turn discovery off. */
+  discoverStart?: (input: { task: Pick<TrackerTask, "identifier" | "title">; verification: string; workspace: { path: string }; portEnv: string }) => Promise<StartAnswer>;
   log?: (line: string) => void;
   now?: () => number;
 }
@@ -461,15 +466,57 @@ export function verifierWith(options: VerifierOptions): VerifierFn {
       log(`verify: ${task.identifier} skipped: ${decision.reason}; the Gates are the whole verification`);
       return { kind: "skipped", reason: decision.reason };
     }
-    log(`verify: ${task.identifier} browser verification: ${decision.reason} (Run Recipe read from ${source})`);
+    // The round is wanted; whether it can happen is a second question. A block with Gates and no
+    // start is the ordinary shape of a repository that never asked for a browser -- `opsee init`
+    // stopped asking, because at setup time nobody knows which of a repository's programs a Task
+    // will exercise. Now there is a Task, a Verification section and a Workspace, so the Foreman
+    // asks a Start turn rather than giving up.
+    let servable = startable(recipe);
+    let discovered: string | undefined;
+    if (!servable) {
+      const ask =
+        options.discoverStart ??
+        ((input) =>
+          discoverStart({
+            worker: options.worker,
+            account: options.account,
+            task: input.task,
+            verification: input.verification,
+            workspace: input.workspace,
+            portEnv: input.portEnv,
+            maxTurns: options.maxTurns,
+            stallTimeoutMs: options.stallTimeoutMs,
+            log,
+            now,
+          }));
+      const answer = await ask({ task, verification: input.verification, workspace, portEnv: recipe.portEnv });
+      if (answer.recipe) {
+        servable = { ...recipe, ...answer.recipe } satisfies StartableRecipe;
+        discovered = answer.recipe.start;
+      } else {
+        log(`verify: ${task.identifier} could not work out how to serve the app: ${answer.reason}`);
+      }
+    }
+    if (!servable) {
+      const missing = `the Run Recipe has no start command, so the app cannot be served (read from ${source})`;
+      if (recipe.verify === "browser") {
+        log(`verify: ${task.identifier} the Run Recipe says verify: browser but ${missing}; the round failed`);
+        return { kind: "failed", reason: `the Run Recipe says verify: browser but ${missing}`, durationMs: 0 };
+      }
+      log(`verify: ${task.identifier} skipped: ${missing}; the Gates are the whole verification`);
+      return { kind: "skipped", reason: missing };
+    }
+    log(
+      `verify: ${task.identifier} browser verification: ${decision.reason} (Run Recipe read from ${source}${discovered ? ", start command from a Start turn" : ""})`,
+    );
 
     const started = now();
     const port = await ports.acquire(task.id);
     const output: string[] = [];
-    const app = startApp(recipe, { port, cwd: workspace.path, env: gateEnv(options.account), onOutput: (line) => output.push(line) });
+    const app = startApp(servable, { port, cwd: workspace.path, env: gateEnv(options.account), onOutput: (line) => output.push(line) });
     input.onPid?.("app", app.pid);
     const appAt = now();
-    log(`verify: ${task.identifier} starting the app on port ${port}: ${app.command} (${recipe.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
+    log(`verify: ${task.identifier} starting the app on port ${port}: ${app.command} (${servable.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
     const appRun = (ready: boolean, error?: string): AppRun => ({
       command: app.command,
       cwd: workspace.path,

package/src/foreman/credential-store.ts

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { VENDOR_CREDENTIAL_FILE, type Vendor } from "./vendor.js";
+
+/**
+ * Where a vendor keeps the credential for one config directory, per platform.
+ *
+ * This exists because of a wrong assumption that reached a release: that a subscription's
+ * credential is a file inside its config directory. **On macOS Claude Code writes no such file.**
+ * It derives a Keychain item per `CLAUDE_CONFIG_DIR` and stores the credential there, so a file
+ * check finds nothing however well the login went — which is exactly what refused three Accounts
+ * that had been logged into correctly.
+ *
+ * Two callers, wanting different things, and the difference is deliberate:
+ *
+ * - `account add --login` wants to know whether a login *happened* (`credentialPresence`). It never
+ *   needs the secret, and never asks for one.
+ * - The usage poller wants the token itself (`readCredentialText`), which ADR-0013's amendment
+ *   permits for the single purpose of asking that vendor about the user's own quota.
+ *
+ * Nothing else in the package may call `readCredentialText`.
+ */
+
+/** The service name Claude Code uses for the default profile — no `CLAUDE_CONFIG_DIR` set. */
+export const CLAUDE_DEFAULT_KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+/** The directory Claude Code uses when `CLAUDE_CONFIG_DIR` is not set. */
+export const CLAUDE_DEFAULT_CONFIG_DIR = ".claude";
+
+/**
+ * Apple's own binary, by absolute path.
+ *
+ * Never resolved through `PATH`: this reads a credential, so a `security` planted earlier on the
+ * path would be handed one. `/usr/bin/security` is present on every macOS.
+ */
+const SECURITY = "/usr/bin/security";
+
+/** A wedged Keychain — a locked login keychain on a headless or SSH host, prompting for an unlock
+ * nobody will give — must not hang a command. A healthy one answers in well under 100ms. */
+const SECURITY_TIMEOUT_MS = 5_000;
+
+/** `errSecItemNotFound`, as `security` surfaces it: the one non-zero status that means "no such
+ * item" rather than "I could not tell you". */
+const NOT_FOUND_STATUS = 44;
+
+/** What a credential lookup found. `unknown` is the important one: it means the question could not
+ * be answered, and **no caller may refuse anything on it**. */
+export type CredentialPresence = "present" | "absent" | "unknown";
+
+/** What `security` reported: its exit status, whatever it printed, and whether it ran at all. */
+export interface SecurityResult {
+  /** Null when the command could not be run or did not finish. */
+  status: number | null;
+  stdout: string;
+  /** Set when the command was killed at `SECURITY_TIMEOUT_MS`, which a caller reports differently
+   * from a binary that is missing: one is a Keychain nobody can reach, the other is not macOS. */
+  timedOut?: boolean;
+}
+
+export interface CredentialDeps {
+  platform: NodeJS.Platform;
+  env: Readonly<Record<string, string | undefined>>;
+  /** The user's home, for recognising the default profile. Injected so the rule is testable. */
+  home: string;
+  /** The OS account name, used when the environment carries none (`osUsername`). */
+  osUsername: () => string;
+  fileExists: (path: string) => boolean;
+  readFile: (path: string) => string;
+  security: (args: readonly string[]) => Promise<SecurityResult>;
+}
+
+/**
+ * The real seams. Deliberately **not** a default parameter: `ConfigDirFs` and `HostProbeDeps` are
+ * both required arguments in this package, and a default is how a call site silently keeps the
+ * production implementation in a test — which is how the file-only assumption survived review.
+ */
+export const realCredentialDeps: CredentialDeps = {
+  platform: process.platform,
+  env: process.env,
+  home: homedir(),
+  osUsername: () => userInfo().username,
+  fileExists: (path) => existsSync(path),
+  readFile: (path) => readFileSync(path, "utf-8"),
+  security: (args) =>
+    new Promise((resolve) => {
+      // `execFile`, not `spawnSync`: this runs inside the daemon, which is streaming live Workers.
+      // A wedged Keychain would otherwise block the event loop for the whole timeout, per Account
+      // — trading the thing that matters for the thing that helps, which the poll tick's own
+      // comment warns against.
+      execFile(SECURITY, [...args], { timeout: SECURITY_TIMEOUT_MS, encoding: "utf-8" }, (error, stdout) => {
+        const killed = (error as { killed?: boolean } | null)?.killed === true;
+        const status = (error as { code?: number } | null)?.code;
+        resolve({
+          status: error ? (typeof status === "number" ? status : null) : 0,
+          stdout: stdout ?? "",
+          ...(killed ? { timedOut: true } : {}),
+        });
+      });
+    }),
+};
+
+/**
+ * The Keychain service name Claude Code derives for a config directory.
+ *
+ * The vendor's own scheme: the first 8 hex characters of the SHA-256 of the **exact string exported
+ * as `CLAUDE_CONFIG_DIR`**, NFC-normalised, after a fixed prefix. Hash what is exported and nothing
+ * else — `/a/b` and `/a/b/` are different strings and so are different items, and resolving or
+ * tidying the path here would look up an item the vendor never wrote.
+ *
+ * The Foreman always exports the absolute path it stored at registration (`validateConfigDir`
+ * resolves it once, through the same `expandHome` the login path uses), so the string hashed here
+ * is the string the login used.
+ */
+export function keychainServiceName(configDir: string): string {
+  const digest = createHash("sha256").update(configDir.normalize("NFC"), "utf8").digest("hex").slice(0, 8);
+  return `${CLAUDE_DEFAULT_KEYCHAIN_SERVICE}-${digest}`;
+}
+
+/**
+ * The Keychain account name, mirroring the vendor's `getUsername()`: `$USER`, then the OS account
+ * name, then a fixed string.
+ *
+ * The middle step is the one that matters, and it is not `$LOGNAME`. Under launchd — which is how
+ * `foreman service install` runs the daemon — neither `USER` nor `LOGNAME` is set, so an
+ * environment-only lookup would fall through to the fixed string, key a different item than the one
+ * the login wrote, and fail every poll on the machine. That is the original bug wearing a different
+ * hat, so the OS is asked rather than the environment.
+ */
+export function keychainAccountName(deps: Pick<CredentialDeps, "env" | "osUsername">): string {
+  if (deps.env.USER) return deps.env.USER;
+  try {
+    const name = deps.osUsername();
+    if (name) return name;
+  } catch {
+    /* a container with no passwd entry; the fixed name below is the vendor's own last resort */
+  }
+  return "claude-code-user";
+}
+
+/**
+ * Whether a credential exists for this config directory.
+ *
+ * Three answers, and the third is the point: `unknown` means the question could not be answered —
+ * a locked Keychain, a denied prompt, a `security` that would not run. **A caller must not refuse
+ * anything on `unknown`.** Treating "I could not tell" as "there is nothing there" is precisely the
+ * bug this module was written to fix.
+ *
+ * Presence never asks for the value: on macOS the lookup omits `-w`, and off it the file is only
+ * stat-ed. Answering "is there one" by reading one would be a credential read with no permission
+ * behind it.
+ */
+export async function credentialPresence(vendor: Vendor, configDir: string, deps: CredentialDeps): Promise<CredentialPresence> {
+  if (!usesKeychain(vendor, deps.platform)) {
+    return deps.fileExists(credentialPath(vendor, configDir)) ? "present" : "absent";
+  }
+  for (const service of keychainServices(configDir, deps)) {
+    const found = await lookUp(deps, service, { wantValue: false });
+    if (found.kind === "found") return "present";
+    if (found.kind === "unusable") return "unknown";
+  }
+  return "absent";
+}
+
+/**
+ * The credential as the vendor stored it, or a one-line reason.
+ *
+ * **The only credential read in this package**, and permitted by ADR-0013's amendment for one
+ * purpose: asking that same vendor about the user's own quota. Every failure reason is built here
+ * and quotes nothing that was read — a poller failure is written to the usage store, printed by
+ * `account usage` and logged, so a reason carrying the file or the item would leak into all three.
+ */
+export async function readCredentialText(
+  vendor: Vendor,
+  configDir: string,
+  deps: CredentialDeps,
+): Promise<{ ok: true; text: string } | { ok: false; reason: string }> {
+  if (!usesKeychain(vendor, deps.platform)) {
+    try {
+      return { ok: true, text: deps.readFile(credentialPath(vendor, configDir)) };
+    } catch {
+      return { ok: false, reason: `no readable ${VENDOR_CREDENTIAL_FILE[vendor]} in ${configDir}` };
+    }
+  }
+  for (const service of keychainServices(configDir, deps)) {
+    const found = await lookUp(deps, service, { wantValue: true });
+    if (found.kind === "found") return { ok: true, text: found.value };
+    if (found.kind === "unusable") return { ok: false, reason: found.reason };
+  }
+  return { ok: false, reason: "no Keychain item holds a credential for this config directory; the vendor has not been logged in there" };
+}
+
+type LookUp = { kind: "found"; value: string } | { kind: "missing" } | { kind: "unusable"; reason: string };
+
+/**
+ * One Keychain lookup. The only difference between asking whether an item exists and asking what is
+ * in it is `-w`, so both callers come through here rather than each keeping its own copy of the
+ * argument list and the three-way reading of the exit status.
+ */
+async function lookUp(deps: CredentialDeps, service: string, options: { wantValue: boolean }): Promise<LookUp> {
+  const args = ["find-generic-password", "-a", keychainAccountName(deps), ...(options.wantValue ? ["-w"] : []), "-s", service];
+  const found = await deps.security(args);
+  // `-w` prints the value and one newline; strip exactly that.
+  if (found.status === 0) return { kind: "found", value: found.stdout.replace(/\n$/, "") };
+  if (found.status === NOT_FOUND_STATUS) return { kind: "missing" };
+  return {
+    kind: "unusable",
+    reason: found.timedOut
+      ? `the macOS Keychain did not answer within ${SECURITY_TIMEOUT_MS}ms for this Account`
+      : `the macOS Keychain could not be read for this Account (security exited ${found.status ?? "without running"})`,
+  };
+}
+
+/**
+ * Claude Code keeps credentials in the Keychain on macOS and in a file everywhere else. Codex is
+ * file-based on every platform (`auth.json`, vendor.ts), so it never comes here.
+ */
+function usesKeychain(vendor: Vendor, platform: NodeJS.Platform): boolean {
+  return vendor === "claude" && platform === "darwin";
+}
+
+/**
+ * The Keychain items to try, in order.
+ *
+ * Normally exactly one: the item derived from this config directory. The default profile's
+ * unhashed item is tried **only when the directory is the default one**, which is the single case
+ * where both names can legitimately describe the same login: exporting `CLAUDE_CONFIG_DIR` makes
+ * the vendor write a hashed item, but somebody who has only ever used the default profile may have
+ * just the unhashed one.
+ *
+ * Trying it for every directory — which this did at first — is a hole, not a courtesy: a directory
+ * with no item of its own would have found the *default profile's* credential, so `--login` would
+ * register an Account nobody signed into, and the poller would file one identity's quota under
+ * another Account. Two Accounts would report one quota and the scheduler would believe twice the
+ * capacity that exists.
+ */
+function keychainServices(configDir: string, deps: CredentialDeps): string[] {
+  const services = [keychainServiceName(configDir)];
+  if (configDir === join(deps.home, CLAUDE_DEFAULT_CONFIG_DIR)) services.push(CLAUDE_DEFAULT_KEYCHAIN_SERVICE);
+  return services;
+}
+
+function credentialPath(vendor: Vendor, configDir: string): string {
+  return join(configDir, VENDOR_CREDENTIAL_FILE[vendor]);
+}

package/src/foreman/run-recipe.ts

@@ -32,10 +32,16 @@ export const VERIFY_MODES = ["auto", "browser", "none"] as const;
 export type VerifyMode = (typeof VERIFY_MODES)[number];
 
 export interface RunRecipe {
-  /** Shell command that serves the app; `{port}` and the port variable are substituted. */
-  start: string;
-  /** URL that answers once the app is up; `{port}` and the port variable are substituted. */
-  readinessUrl: string;
+  /** Shell command that serves the app; `{port}` and the port variable are substituted.
+   *
+   * Optional, because only the Verifier's browser round needs it and most repositories never ask
+   * for one. The Gates are the rest of the block and they run without it. `opsee init` writes it
+   * when the analyzer already knows a dev command and otherwise leaves it out rather than asking
+   * a question whose answer is "which of these six programs?" in a monorepo. */
+  start?: string;
+  /** URL that answers once the app is up; `{port}` and the port variable are substituted. Absent
+   * with `start`, present with it. */
+  readinessUrl?: string;
   /** Name of the environment variable set to the port when `start` runs. */
   portEnv: string;
   gates: RunRecipeGates;
@@ -81,10 +87,17 @@ function nonEmptyString(value: unknown): string | undefined {
 export function recipeFromConfig(raw: unknown, source: string): RunRecipe {
   if (!raw || typeof raw !== "object") throw new Error(`${source} has no foreman block; run opsee init to write the Run Recipe.`);
   const block = raw as Record<string, unknown>;
+  // Neither is required. A block with Gates and no start is a repository that never wanted a
+  // browser round, which is most of them; the Verifier says so and the Gates give the Verdict.
+  //
+  // A start command without a readiness URL is different: it is a half-written recipe. It would
+  // start the app and never know it was up, so the round would skip for a reason that looks like
+  // "you did not configure this" when the truth is "you configured half of it".
   const start = nonEmptyString(block.start);
   const readinessUrl = nonEmptyString(block.readiness_url);
-  if (!start) throw new Error(`${source}: foreman.start is missing; it is the command that serves the app.`);
-  if (!readinessUrl) throw new Error(`${source}: foreman.readiness_url is missing; it is the URL that answers once the app is up.`);
+  if (start && !readinessUrl) {
+    throw new Error(`${source}: foreman.start is set but foreman.readiness_url is missing; it is the URL that answers once the app is up.`);
+  }
   const gatesRaw = block.gates && typeof block.gates === "object" ? (block.gates as Record<string, unknown>) : {};
   const gates: RunRecipeGates = {};
   for (const name of ["test", "lint", "typecheck"] as const) {
@@ -97,7 +110,13 @@ export function recipeFromConfig(raw: unknown, source: string): RunRecipe {
   } catch (error) {
     throw new Error(`${source}: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return { start, readinessUrl, portEnv: nonEmptyString(block.port_env) ?? DEFAULT_PORT_ENV, gates, ...(block.verify === undefined ? {} : { verify }) };
+  return {
+    ...(start === undefined ? {} : { start }),
+    ...(readinessUrl === undefined ? {} : { readinessUrl }),
+    portEnv: nonEmptyString(block.port_env) ?? DEFAULT_PORT_ENV,
+    gates,
+    ...(block.verify === undefined ? {} : { verify }),
+  };
 }
 
 /** Resolves the Run Recipe of the repo at `root`. The JSON copy is authoritative when present
@@ -146,7 +165,17 @@ export interface AppHandle {
  * wrapper spawned underneath it. The child goes on this process's live registry
  * (worker-process.ts `trackLiveProcess`) beside the Workers, so a Foreman that is signalled or
  * exits stops the app with them rather than orphaning it. */
-export function startApp(recipe: RunRecipe, options: StartOptions): AppHandle {
+/** A recipe that can actually serve the app: both halves present. `startApp` takes this rather
+ * than a RunRecipe so a caller cannot forget the check, and the Verifier's "cannot start the app"
+ * branch is the one place that decides what to do about it. */
+export type StartableRecipe = RunRecipe & { start: string; readinessUrl: string };
+
+/** The recipe when it can serve the app, undefined when it cannot. */
+export function startable(recipe: RunRecipe): StartableRecipe | undefined {
+  return recipe.start && recipe.readinessUrl ? (recipe as StartableRecipe) : undefined;
+}
+
+export function startApp(recipe: StartableRecipe, options: StartOptions): AppHandle {
   const command = substitutePort(recipe.start, options.port, recipe.portEnv);
   const readinessUrl = substitutePort(recipe.readinessUrl, options.port, recipe.portEnv);
   const child = spawn(command, {

package/src/foreman/usage-activity.ts

@@ -0,0 +1,102 @@
+import { count } from "./core/text.js";
+import type { AccountUsage, ActivityTurn } from "./usage.js";
+import type { UsageStore } from "./usage-store.js";
+
+/**
+ * What this Foreman has itself spent on an Account (the multi-account headroom design, §6).
+ *
+ * What the Foreman itself has spent on an Account, from the `costUsd` and turn count that already
+ * ride the completed event and were, until now, explicitly unconsumed.
+ *
+ * **It deliberately reports no percentage.** The design sketched this as a third estimator
+ * producing estimated window percentages for Accounts the poller cannot measure, and that
+ * part is not built, because it cannot be built honestly: converting "eleven turns and $4.20" into
+ * "38% of a five-hour window" needs the plan's limit, which nothing on this machine knows and which
+ * differs by subscription tier. A number like that would be invented, and — worse — it would sit in
+ * the same column as measurements that are real.
+ *
+ * What it is good for is the question a percentage cannot answer anyway: *how hard has the Foreman
+ * been leaning on this Account?* That is a fact, it is this machine's to know, and it is what a
+ * human looks for when an Account keeps hitting its limit. It is reported beside the windows in
+ * `foreman account usage`, never used to hold an Account back or to rank a Lane.
+ *
+ * Called activity on purpose: `cli/CONTEXT.md` puts "Ledger" on the avoid list
+ * for both the Run Record and the Process Table, and a third thing wearing the word would undo
+ * exactly the vocabulary that file exists to keep straight.
+ */
+
+/** The windows this reports on, matching the vendor's own two. */
+const FIVE_HOURS = 5 * 60 * 60_000;
+const SEVEN_DAYS = 7 * 24 * 60 * 60_000;
+
+/** The longest window reported on: a turn older than this answers no question asked here. */
+const ACTIVITY_HORIZON_MS = SEVEN_DAYS;
+
+/** The most turns kept for one Account. A busy fleet would otherwise grow the record without bound,
+ * and the oldest turns are the ones that have already aged out of every window that matters. */
+export const ACTIVITY_TURN_CAP = 2_000;
+
+/** Turns inside `windowMs`, and what they cost. A turn whose cost the vendor did not report still
+ * counts as a turn: the turn happened, and that is the part this is sure of. */
+export function activityIn(usage: AccountUsage | undefined, windowMs: number, now: number): { turns: number; costUsd: number } {
+  let turns = 0;
+  let costUsd = 0;
+  for (const turn of usage?.activity?.turns ?? []) {
+    const at = Date.parse(turn.at);
+    if (!Number.isFinite(at) || at < now - windowMs || at > now) continue;
+    turns++;
+    if (typeof turn.costUsd === "number" && Number.isFinite(turn.costUsd)) costUsd += turn.costUsd;
+  }
+  return { turns, costUsd };
+}
+
+/** What the Foreman has spent on this Account, in one line, or undefined when it has run none. */
+export function summariseActivity(usage: AccountUsage | undefined, now: number): string | undefined {
+  const recent = activityIn(usage, FIVE_HOURS, now);
+  const week = activityIn(usage, SEVEN_DAYS, now);
+  if (week.turns === 0) return undefined;
+  const spent = week.costUsd > 0 ? `, $${week.costUsd.toFixed(2)} this week` : "";
+  return `this Foreman ran ${count(recent.turns, "turn")} in the last 5h and ${count(week.turns, "turn")} in 7d${spent}`;
+}
+
+/**
+ * Records one completed turn against an Account.
+ *
+ * Goes through the store's merge like everything else, so a turn recorded by one Run and a window
+ * measured by the poller at the same moment cannot lose each other (`mergeActivity`).
+ */
+export function recordTurn(store: UsageStore, account: string, at: number, costUsd: number | undefined): void {
+  store.observe(account, {}, at, {
+    turns: [costUsd === undefined ? { at: new Date(at).toISOString() } : { at: new Date(at).toISOString(), costUsd }],
+  });
+}
+
+/** Turns still worth keeping: inside the horizon, newest-last, and no more than the cap. */
+export function pruneTurns(turns: readonly ActivityTurn[], now: number): ActivityTurn[] {
+  const kept = turns
+    .filter((turn) => {
+      const at = Date.parse(turn.at);
+      return Number.isFinite(at) && at >= now - ACTIVITY_HORIZON_MS;
+    })
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+  return kept.length > ACTIVITY_TURN_CAP ? kept.slice(kept.length - ACTIVITY_TURN_CAP) : kept;
+}
+
+/**
+ * Both writers' turns, in order, with duplicates dropped.
+ *
+ * The usage store has two writers — a Run recording a turn, the daemon's poller recording windows —
+ * and per-Account files keep them from losing each other's *Accounts*. This is what keeps them from
+ * losing each other's *turns*: a read-modify-write that overwrote the activity list would drop
+ * whatever the other process appended in between.
+ *
+ * A turn is identified by its instant and its cost. Two genuinely simultaneous turns of identical
+ * cost on one Account collapse into one, which costs the record a turn it would have counted; the
+ * alternative is an id per turn on a record that is already advisory, and this record is explicitly
+ * not a number anything depends on.
+ */
+export function mergeActivity(mine: readonly ActivityTurn[] | undefined, theirs: readonly ActivityTurn[] | undefined, now: number): ActivityTurn[] {
+  const byKey = new Map<string, ActivityTurn>();
+  for (const turn of [...(mine ?? []), ...(theirs ?? [])]) byKey.set(`${turn.at}|${turn.costUsd ?? ""}`, turn);
+  return pruneTurns([...byKey.values()], now);
+}