jackherd 1.16.0 → 1.17.0

package/src/config/personal-sources.ts

@@ -4,40 +4,68 @@ import { errorMessage } from '../sync/error-message'
 import { SOURCE_ORIGIN, type SourceOrigin, type SourceSettings } from '../watch/sources'
 import { personalSourcesPath } from './location'
 import { readResolvedConfig } from './read-config'
+import { isRepositoryIn } from './repository-identity'
 import { parsePersonalSourcesFile } from './schema'
 
-export type MergedSources = { sources: SourceSettings[]; notes: string[] }
+/** Why a personal source with `repos` does not run in this repository. */
+export const EXCLUDED_REASON = { otherRepository: 'not for this repo', noOrigin: 'no origin' } as const
+
+export type ExcludedReason = (typeof EXCLUDED_REASON)[keyof typeof EXCLUDED_REASON]
+
+/** A personal source left out because of its `repos`, kept so `jh secret list` and the dry run can still name it. */
+export type ExcludedSource = { source: SourceSettings; reason: ExcludedReason }
+
+export type MergedSources = { sources: SourceSettings[]; notes: string[]; excluded: ExcludedSource[] }
 
 /** What a note starts with when an invalid personal file was left out. */
 export const PERSONAL_IGNORED = 'personal sources ignored:'
 
 const skippedPrefix = (name: string): string => `personal source ${name} in `
 
+const excludedPrefix = (name: string): string => `${name}: `
+
 const skippedNote = (name: string, path: string): string =>
   `${skippedPrefix(name)}${path} skipped: the repository has a source of that name`
 
-/** Whether a merge note concerns the source `name`: the personal source of that name was skipped, or the file was ignored. */
+/** The note for a source left out for its `repos`: `<name>: not for this repo` or `<name>: no origin`. */
+export const excludedNote = ({ source, reason }: ExcludedSource): string => `${excludedPrefix(source.name)}${reason}`
+
+/** Whether a merge note concerns the source `name`: the personal source of that name was skipped or left out for its `repos`, or the file was ignored. */
 export const isNoteAbout = (note: string, name: string): boolean =>
-  note.startsWith(skippedPrefix(name)) || note.startsWith(PERSONAL_IGNORED)
+  note.startsWith(skippedPrefix(name)) || note.startsWith(excludedPrefix(name)) || note.startsWith(PERSONAL_IGNORED)
 
 const withOrigin = (sources: readonly SourceSettings[], origin: SourceOrigin): SourceSettings[] =>
   sources.map((source) => ({ ...source, origin }))
 
+const exclusionOf = (source: SourceSettings, repository: string | null): ExcludedReason | null => {
+  if (source.repos === undefined || isRepositoryIn(repository, source.repos)) return null
+  return repository === null ? EXCLUDED_REASON.noOrigin : EXCLUDED_REASON.otherRepository
+}
+
 /**
  * The repository's sources, then the personal ones, each marked with its origin. A personal source whose name a
- * repository source has is left out and named in a note; `path` is how the notes spell the personal file.
+ * repository source has is left out and named in a note, and so is one whose `repos` do not list `repository`
+ * (`owner/name` of this checkout's origin, null without one); `path` is how the notes spell the personal file.
  */
 export const mergedSources = (
   repo: readonly SourceSettings[],
   personal: readonly SourceSettings[],
   path: string,
+  repository: string | null,
 ): MergedSources => {
   const repoNames = new Set(repo.map(({ name }) => name))
-  const kept = personal.filter(({ name }) => !repoNames.has(name))
+  const unclashed = personal.filter(({ name }) => !repoNames.has(name))
   const skipped = personal.filter(({ name }) => repoNames.has(name))
+  const excluded = withOrigin(unclashed, SOURCE_ORIGIN.personal).flatMap((source): ExcludedSource[] => {
+    const reason = exclusionOf(source, repository)
+    return reason === null ? [] : [{ source, reason }]
+  })
+  const left = new Set(excluded.map(({ source }) => source.name))
+  const kept = unclashed.filter(({ name }) => !left.has(name))
   return {
     sources: [...withOrigin(repo, SOURCE_ORIGIN.repo), ...withOrigin(kept, SOURCE_ORIGIN.personal)],
-    notes: skipped.map(({ name }) => skippedNote(name, path)),
+    notes: [...skipped.map(({ name }) => skippedNote(name, path)), ...excluded.map(excludedNote)],
+    excluded,
   }
 }
 
@@ -64,14 +92,19 @@ export const readPersonalSources = (
  */
 export const sourcesWithPersonal = (
   repo: readonly SourceSettings[],
+  repository: string | null,
   home: string = homedir(),
   exists: (path: string) => boolean = existsSync,
   readText?: (path: string) => string,
 ): MergedSources => {
   try {
-    return mergedSources(repo, readPersonalSources(home, exists, readText), personalSourcesPath(home))
+    return mergedSources(repo, readPersonalSources(home, exists, readText), personalSourcesPath(home), repository)
   } catch (error) {
-    return { sources: withOrigin(repo, SOURCE_ORIGIN.repo), notes: [`${PERSONAL_IGNORED} ${errorMessage(error)}`] }
+    return {
+      sources: withOrigin(repo, SOURCE_ORIGIN.repo),
+      notes: [`${PERSONAL_IGNORED} ${errorMessage(error)}`],
+      excluded: [],
+    }
   }
 }
 
@@ -79,5 +112,8 @@ export const sourcesWithPersonal = (
  * The sources of the project config of the first of `roots` that has one (`readResolvedConfig`), with the personal
  * ones of `home` merged in; throws like `readResolvedConfig` when the project config is missing or invalid.
  */
-export const configuredSources = (roots: string[], home: string = homedir()): MergedSources =>
-  sourcesWithPersonal(readResolvedConfig(roots, home).config.watch.sources, home)
+export const configuredSources = (
+  roots: string[],
+  repository: string | null,
+  home: string = homedir(),
+): MergedSources => sourcesWithPersonal(readResolvedConfig(roots, home).config.watch.sources, repository, home)

package/src/config/repository-identity.ts

@@ -0,0 +1,40 @@
+/** `owner/name` as `repos` spells a repository. */
+export const REPOSITORY_NAME = /^[\w.-]+\/[\w.-]+$/
+
+const SCP_REMOTE = /^[\w.-]+@[\w.-]+:([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/
+
+/** `owner/name` of a URL path with exactly those two segments; a deeper or shorter path names no repository of ours. */
+const ownerAndName = (path: string): string | null => {
+  const segments = path
+    .replace(/\.git\/?$/, '')
+    .split('/')
+    .filter((segment) => segment !== '')
+  return segments.length === 2 ? segments.join('/') : null
+}
+
+/**
+ * `owner/name` of a git remote URL: `git@host:owner/name(.git)`, `https://host/owner/name(.git)` (credentials
+ * allowed) and `ssh://git@host(:port)/owner/name(.git)`. Null for anything else: a local path, a `file://` URL, a
+ * path with more or fewer than two segments.
+ */
+export const repositoryOf = (remoteUrl: string): string | null => {
+  const remote = remoteUrl.trim()
+  const scp = SCP_REMOTE.exec(remote)
+  if (scp) return `${scp[1]}/${scp[2]}`
+  try {
+    const url = new URL(remote)
+    return ['https:', 'http:', 'ssh:'].includes(url.protocol) ? ownerAndName(url.pathname) : null
+  } catch {
+    return null
+  }
+}
+
+/** Whether `repository` is one of `repos`; GitHub names compare without regard to case. A repository nobody could name is in none. */
+export const isRepositoryIn = (repository: string | null, repos: readonly string[]): boolean =>
+  repository !== null && repos.some((repo) => repo.toLowerCase() === repository.toLowerCase())
+
+/** The repository the checkout at `root` pushes to (`origin`), null without a git repository, an origin or a URL `repositoryOf` knows. */
+export const readRepositoryIdentity = (root: string): string | null => {
+  const result = Bun.spawnSync(['git', '-C', root, 'remote', 'get-url', 'origin'], { stdout: 'pipe', stderr: 'ignore' })
+  return result.exitCode === 0 ? repositoryOf(result.stdout.toString()) : null
+}

package/src/config/schema.ts

@@ -12,12 +12,16 @@ import { DEFAULT_BASE_BRANCH } from './base-branch'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
 import { isRepositoryDirectory } from './repository-directory'
+import { REPOSITORY_NAME } from './repository-identity'
 import { DEFAULT_TONES, TONE_NAMES } from './tones'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
 export type TerminalAdapter = (typeof TERMINAL_ADAPTER)[keyof typeof TERMINAL_ADAPTER]
 
+/** The environments a standing approval may cover; production is never one. */
+export const STANDING_ENVIRONMENT = { stage: 'stage' } as const
+
 // TODO: draft role list taken from the agents the kit ships; confirm it before more kit files render model
 // IDs per role.
 export const MODEL_ROLE = {
@@ -302,6 +306,16 @@ const sourceSchema = z
       .optional(),
     /** `entries` shows the source's entries open, in a herd block of its own; not for a ticket source, whose entries are badges. */
     show: z.literal(SOURCE_SHOW.entries).optional(),
+    /**
+     * `owner/name` of the repositories a personal source runs in (matched without regard to case); without it every
+     * repository. Only in the personal sources file: the repository's own config is for that repository already.
+     */
+    repos: z
+      .array(z.string().regex(REPOSITORY_NAME, 'owner/name, such as acme/tool'))
+      .min(1)
+      .max(20)
+      .refine((repos) => new Set(repos.map((repo) => repo.toLowerCase())).size === repos.length, 'repos must be unique')
+      .optional(),
   })
   .refine(canChange, {
     message: 'map needs updatedAt, a content field (title, author, body, url) or reportOn',
@@ -327,6 +341,22 @@ const sourceSchema = z
 const hasUniqueNames = (sources: readonly { name: string }[]): boolean =>
   new Set(sources.map(({ name }) => name)).size === sources.length
 
+/** The sources of the repository's own config: none may name `repos`, which only a personal source has. */
+const repositorySources = z
+  .array(sourceSchema)
+  .refine(hasUniqueNames, 'source names must be unique')
+  .superRefine((sources, context) => {
+    sources.forEach((source, index) => {
+      if (source.repos === undefined) return
+      context.addIssue({
+        code: 'custom',
+        path: [index, 'repos'],
+        message:
+          'repos belongs in the personal sources file (~/.jackherd/sources.json): this config is for one repository',
+      })
+    })
+  })
+
 const coordinatorSchema = z
   .strictObject({
     /** Tokens in the coordinator's context from which the watcher reports `coordinator warn`. */
@@ -336,6 +366,18 @@ const coordinatorSchema = z
   })
   .refine(warnBelowAlert, WARN_BELOW_ALERT)
 
+/**
+ * An SQL tool of an MCP server by its full name (`mcp__<server>__execute_sql`), never one whose name says `prod`. The
+ * approval gate hook applies the same rule (`kit/hooks/hooks/approval-gate/settings.ts`), which cannot import this.
+ */
+const standingTool = z
+  .string()
+  .regex(
+    /^mcp__[A-Za-z0-9_-]+__execute_sql$/,
+    'a full MCP tool name ending in execute_sql, such as mcp__<server>__execute_sql',
+  )
+  .refine((name) => !/prod/i.test(name), 'a tool whose name says prod never runs under a standing approval')
+
 /** A guarded command as words: a program and one to three plain words after it, never an option, a quote or a shell character. */
 const guardedCommand = z
   .string()
@@ -420,6 +462,14 @@ const guardFields = z.strictObject({
     .strictObject({
       /** How long the approval gate hook holds a lane's call for the coordinator's dialog before it denies it; below the hook's 10 minutes. */
       waitMinutes: z.number().int().min(1).max(9).default(8),
+      /**
+       * The calls a standing approval of the user may let through once the coordinator marked them checked: each tool
+       * by its full name and the environment it writes to, only `stage`. A tool whose name says `prod` is refused, as the
+       * hook refuses it under a broken config; which project a server reaches is the project's start script's to say.
+       */
+      standing: z
+        .strictObject({ tools: z.record(standingTool, z.enum(Object.values(STANDING_ENVIRONMENT))) })
+        .optional(),
     })
     .prefault({}),
   /**
@@ -531,6 +581,8 @@ export const jackherdConfigSchema = z.strictObject({
       copy: z.array(laneCopyPath).default([]),
       /** The dependency lock file a rebase takes from the base branch and regenerates, never merges by hand; detected from the repository when left out. */
       lockFile: lockFilePath.optional(),
+      /** Free gigabytes the disk must hold before `jh lane space` lets a new lane install its dependencies; 5 when left out. */
+      minFreeGb: z.number().positive().optional(),
     })
     .prefault({}),
   models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),
@@ -582,7 +634,7 @@ export const jackherdConfigSchema = z.strictObject({
       parallelTasks: parallelTasksSchema.prefault({}),
       taskSignalMinutes: z.number().int().positive().default(DEFAULT_TASK_SIGNAL_MINUTES),
       previews: previewsSchema.optional(),
-      sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
+      sources: repositorySources.default([]),
     })
     .prefault({}),
   /** Read by the merge guard hook, which asks before the listed commands run, and by `/orchestrate`. */

package/src/context/command.ts

@@ -2,13 +2,15 @@ import { homedir } from 'node:os'
 import { basename, join } from 'node:path'
 import { CLAUDE_DIRECTORY } from '../claude/paths'
 import { mainCheckout, worktreeRoot } from '../plans/git'
-import { type PlansSettings, readSettings } from '../plans/settings'
+import { type PlansSettings, readSettings, worktreeOf } from '../plans/settings'
 import { type LaneAgent, laneStatusSourceFor } from '../terminal'
 import { AUTO_COMPACT_ENV, autoCompactWindow, compactsBeforeAlertNote, readClaudeSettings } from './auto-compact'
 import { resolveCoordinatorName } from './coordinator-name'
 import { type ContextOptions, coordinatorSettings, parseContextOptions } from './options'
 import { type ContextReport, contextReport, noValueNote, unnamedPaneNote } from './report'
-import { agentLog } from './session-log'
+import { agentLog, defaultProjectsDirectory } from './session-log'
+import { parseSince, sumUsage, usageReport } from './usage'
+import { usageEntriesOf } from './usage-logs'
 
 type ResolvedAgents = { lane: string; named: LaneAgent[]; agents: LaneAgent[] }
 
@@ -56,6 +58,30 @@ const printNotes = ({ lane, named, agents }: ResolvedAgents, report: ContextRepo
   if (report === null) console.error(noValueNote(agents, lane))
 }
 
+/**
+ * `--usage`: the tokens used by the lane's sessions and their subagents, as one line of JSON. The scope is the lane's
+ * worktree (the one the command runs in without a name), or with `--coordinator` the main checkout without its
+ * worktrees.
+ */
+const usageSubject = (
+  options: ContextOptions,
+  settings: PlansSettings,
+  root: string,
+  worktree: string,
+): { label: string; directory: string } => {
+  if (options.coordinator) return { label: basename(root), directory: root }
+  if (options.lane) return { label: options.lane, directory: worktreeOf(root, settings, options.lane) }
+  return { label: basename(worktree), directory: worktree }
+}
+
+const printUsage = (options: ContextOptions, settings: PlansSettings, root: string, worktree: string): void => {
+  const { label, directory } = usageSubject(options, settings, root, worktree)
+  const since = options.since === null ? null : parseSince(options.since, Date.now())
+  const exclude = directory === root ? [join(root, settings.worktreeDirectory)] : []
+  const entries = usageEntriesOf(defaultProjectsDirectory(), directory, since)
+  console.log(JSON.stringify(usageReport(label, sumUsage(entries, { root: directory, exclude, since }), since)))
+}
+
 /**
  * `jh context [<name>] [--coordinator]`: prints how full the context of an agent is as one line of JSON
  * (`tokens`, `window`, `share`, `model`, `level`), or `null` when there is no value. The name defaults to the
@@ -63,6 +89,7 @@ const printNotes = ({ lane, named, agents }: ResolvedAgents, report: ContextRepo
  * agent still carries that old name. `--coordinator` also takes
  * the level from the coordinator's thresholds (`plans.context.coordinator`). Reads the session log, never writes it.
  * One more line on stderr when Claude Code's auto-compact window is not above the alert threshold.
+ * `jh context --usage [--since 24h|7d|<date>] [<name>] [--coordinator]` prints the tokens used instead (`printUsage`).
  */
 export const run = async (args: string[]): Promise<number> => {
   try {
@@ -70,6 +97,10 @@ export const run = async (args: string[]): Promise<number> => {
     const root = mainCheckout(process.cwd())
     const worktree = worktreeRoot(process.cwd())
     const settings = readSettings([worktree, root])
+    if (options.usage) {
+      printUsage(options, settings, root, worktree)
+      return 0
+    }
     const resolved = resolveAgents(options, settings, root, worktree)
     const context = options.coordinator ? coordinatorSettings(settings.context) : settings.context
     const report = contextReport(resolved.agents, resolved.lane, agentLog, context)

package/src/context/options.ts

@@ -2,24 +2,49 @@ import { CLI_NAME } from '../version/release'
 import type { ContextWindows } from './fill'
 import type { ContextThresholds } from './level'
 
-/** `lane` is null when the command names none; it then measures the agent of the worktree it runs in. */
-export type ContextOptions = { lane: string | null; coordinator: boolean }
+/**
+ * `lane` is null when the command names none; it then measures the agent of the worktree it runs in. `usage` asks for
+ * the tokens used instead of the fill, `since` (the text of `--since`) limits them to a period.
+ */
+export type ContextOptions = { lane: string | null; coordinator: boolean; usage: boolean; since: string | null }
 
 export type ContextSettings = ContextWindows & ContextThresholds & { coordinator: ContextThresholds }
 
 const COORDINATOR_OPTION = '--coordinator'
 
-const KNOWN_OPTIONS = [COORDINATOR_OPTION]
+const USAGE_OPTION = '--usage'
+const SINCE_OPTION = '--since'
 
-const USAGE = `usage: ${CLI_NAME} context [<name>] [${COORDINATOR_OPTION}]`
+const KNOWN_OPTIONS = [COORDINATOR_OPTION, USAGE_OPTION, SINCE_OPTION]
 
-/** Reads `[<name>] [--coordinator]` in any order; throws with the usage on an unknown option or a second name. */
+const USAGE = `usage: ${CLI_NAME} context [<name>] [${COORDINATOR_OPTION}] [${USAGE_OPTION} [${SINCE_OPTION} <24h|7d|date>]]`
+
+const optionName = (arg: string): string => arg.split('=')[0] ?? arg
+
+/** The value of `--since`, given as `--since <value>` or `--since=<value>`, and the arguments without it; null without the option. */
+const takeSince = (args: readonly string[]): { since: string | null; rest: string[] } => {
+  const index = args.findIndex((arg) => optionName(arg) === SINCE_OPTION)
+  if (index === -1) return { since: null, rest: [...args] }
+  const arg = args[index] ?? ''
+  const inline = arg.includes('=')
+  const value = inline ? arg.slice(arg.indexOf('=') + 1) : args[index + 1]
+  if (!value || value.startsWith('--')) throw new Error(`${SINCE_OPTION} needs a value\n${USAGE}`)
+  return { since: value, rest: args.filter((_, position) => position !== index && (inline || position !== index + 1)) }
+}
+
+/**
+ * Reads `[<name>] [--coordinator] [--usage [--since <value>]]` in any order; throws with the usage on an unknown
+ * option, a second name, a `--since` without a value or one without `--usage`.
+ */
 export const parseContextOptions = (args: readonly string[]): ContextOptions => {
-  const unknown = args.find((arg) => arg.startsWith('--') && !KNOWN_OPTIONS.includes(arg))
+  const unknown = args.find((arg) => arg.startsWith('--') && !KNOWN_OPTIONS.includes(optionName(arg)))
   if (unknown) throw new Error(`unknown option ${unknown}\n${USAGE}`)
-  const names = args.filter((arg) => !arg.startsWith('--'))
+  const { since, rest } = takeSince(args)
+  const usage = rest.includes(USAGE_OPTION)
+  if (since !== null && !usage) throw new Error(`${SINCE_OPTION} belongs to ${USAGE_OPTION}\n${USAGE}`)
+  const names = rest.filter((arg) => !arg.startsWith('--'))
   if (names.length > 1) throw new Error(`one name at most, got ${names.join(' ')}\n${USAGE}`)
-  return { lane: names[0] ?? null, coordinator: args.includes(COORDINATOR_OPTION) }
+  return { lane: names[0] ?? null, coordinator: rest.includes(COORDINATOR_OPTION), usage, since }
 }
 
 /** The settings with the coordinator's thresholds in place of a lane's; the windows stay the same. */

package/src/context/usage-logs.ts

@@ -0,0 +1,53 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { projectDirectoryOf } from './session-log'
+import { parseUsageLine, type UsageEntry } from './usage'
+
+const SUBAGENTS_DIRECTORY = 'subagents'
+const LOG_EXTENSION = '.jsonl'
+const USAGE_MARK = '"usage"'
+
+const directoriesOf = (path: string): string[] =>
+  readdirSync(path, { withFileTypes: true })
+    .filter((each) => each.isDirectory())
+    .map((each) => each.name)
+
+const logsIn = (directory: string): string[] =>
+  existsSync(directory)
+    ? readdirSync(directory)
+        .filter((name) => name.endsWith(LOG_EXTENSION))
+        .map((name) => join(directory, name))
+    : []
+
+/** The session logs of a project directory and the logs of the subagents of each session. */
+const logsOfProject = (directory: string): string[] => [
+  ...logsIn(directory),
+  ...directoriesOf(directory).flatMap((session) => logsIn(join(directory, session, SUBAGENTS_DIRECTORY))),
+]
+
+/** The project directories of the working directory `root` and of every directory below it (Claude Code names one per working directory). */
+const projectDirectoriesFor = (projectsDirectory: string, root: string): string[] => {
+  const prefix = projectDirectoryOf(root)
+  return existsSync(projectsDirectory)
+    ? directoriesOf(projectsDirectory)
+        .filter((name) => name === prefix || name.startsWith(`${prefix}-`))
+        .map((name) => join(projectsDirectory, name))
+    : []
+}
+
+const entriesOfLog = (path: string): UsageEntry[] =>
+  readFileSync(path, 'utf8')
+    .split('\n')
+    .filter((line) => line.includes(USAGE_MARK))
+    .flatMap((line) => parseUsageLine(line) ?? [])
+
+/**
+ * The usage entries of every session and subagent log whose project directory is `root`'s or lies below it; the
+ * caller sums them within a scope. A log last written before `since` (milliseconds) cannot hold a later request and
+ * is not read. The directory name is only a coarse filter: `cwd` in each line decides in `sumUsage`.
+ */
+export const usageEntriesOf = (projectsDirectory: string, root: string, since: number | null): UsageEntry[] =>
+  projectDirectoriesFor(projectsDirectory, root)
+    .flatMap(logsOfProject)
+    .filter((path) => since === null || statSync(path).mtimeMs >= since)
+    .flatMap(entriesOfLog)

package/src/context/usage.ts

@@ -0,0 +1,110 @@
+import { isRecord } from '../shared/is-record'
+
+/** One answer's token counts out of a session log line, with the request it belongs to and where and when it ran. */
+export type UsageEntry = {
+  requestId: string
+  cwd: string
+  /** The time of the line in milliseconds; null when the line carries none. */
+  at: number | null
+  input: number
+  cacheRead: number
+  cacheWrite: number
+  output: number
+}
+
+export type UsageTotals = { requests: number; input: number; cacheRead: number; cacheWrite: number; output: number }
+
+/**
+ * What a sum counts: the entries run in `root` or below it, none below an `exclude` directory (the main checkout
+ * leaves its worktrees out), and, with `since` (milliseconds), none from before it and none without a time.
+ */
+export type UsageScope = { root: string; exclude: readonly string[]; since: number | null }
+
+const HOUR = 3_600_000
+const DAY = 24 * HOUR
+const SINCE_FORM = /^(\d+)([hd])$/
+const SINCE_FORMS = 'use 24h, 7d or an ISO date (YYYY-MM-DD)'
+
+const count = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
+
+const timeOf = (value: unknown): number | null => {
+  const time = typeof value === 'string' ? Date.parse(value) : Number.NaN
+  return Number.isNaN(time) ? null : time
+}
+
+/** The usage of one log line; null for a line without usage, request or working directory, and for anything that is no JSON. */
+export const parseUsageLine = (line: string): UsageEntry | null => {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(line)
+  } catch {
+    return null
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.message) || !isRecord(parsed.message.usage)) return null
+  const { requestId, cwd, timestamp } = parsed
+  if (typeof requestId !== 'string' || typeof cwd !== 'string') return null
+  const usage = parsed.message.usage
+  return {
+    requestId,
+    cwd,
+    at: timeOf(timestamp),
+    input: count(usage.input_tokens),
+    cacheRead: count(usage.cache_read_input_tokens),
+    cacheWrite: count(usage.cache_creation_input_tokens),
+    output: count(usage.output_tokens),
+  }
+}
+
+const isBelow = (directory: string, parent: string): boolean =>
+  directory === parent || directory.startsWith(`${parent}/`)
+
+/** Whether a working directory is the scope's root or below it, and not below an excluded directory. */
+export const isWithinScope = (cwd: string, { root, exclude }: UsageScope): boolean =>
+  isBelow(cwd, root) && !exclude.some((excluded) => isBelow(cwd, excluded))
+
+const addUsage = (totals: UsageTotals, entry: UsageEntry): UsageTotals => ({
+  requests: totals.requests + 1,
+  input: totals.input + entry.input,
+  cacheRead: totals.cacheRead + entry.cacheRead,
+  cacheWrite: totals.cacheWrite + entry.cacheWrite,
+  output: totals.output + entry.output,
+})
+
+const fromSince = (entry: UsageEntry, since: number | null): boolean =>
+  since === null || (entry.at !== null && entry.at >= since)
+
+/**
+ * The tokens of the requests in `scope`, each request once however many log lines or logs repeat it (Claude Code
+ * writes one answer as several lines with the same counts).
+ */
+export const sumUsage = (entries: readonly UsageEntry[], scope: UsageScope): UsageTotals => {
+  const seen = new Set<string>()
+  return entries.reduce<UsageTotals>(
+    (totals, entry) => {
+      if (seen.has(entry.requestId) || !isWithinScope(entry.cwd, scope) || !fromSince(entry, scope.since)) return totals
+      seen.add(entry.requestId)
+      return addUsage(totals, entry)
+    },
+    { requests: 0, input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
+  )
+}
+
+/** What `jh context --usage` prints: the sums in tokens, no price, `total` their sum, `since` the start as an ISO time or null. */
+export const usageReport = (scope: string, totals: UsageTotals, since: number | null) => ({
+  scope,
+  since: since === null ? null : new Date(since).toISOString(),
+  ...totals,
+  total: totals.input + totals.cacheRead + totals.cacheWrite + totals.output,
+})
+
+/** The start time of `--since`: `<n>h` or `<n>d` before `now`, or an ISO date; throws with the accepted forms otherwise. */
+export const parseSince = (text: string, now: number): number => {
+  const relative = SINCE_FORM.exec(text)
+  if (relative) {
+    const amount = Number(relative[1])
+    if (amount > 0) return now - amount * (relative[2] === 'h' ? HOUR : DAY)
+  }
+  const date = /^\d{4}-\d{2}-\d{2}/.test(text) ? Date.parse(text) : Number.NaN
+  if (Number.isNaN(date)) throw new Error(`cannot read --since ${text}: ${SINCE_FORMS}`)
+  return date
+}

package/src/lane/base-command.ts

@@ -0,0 +1,35 @@
+import { existsOnRef, mainCheckout } from '../plans/git'
+import { baseRefOf, readSettings } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { type BaseFacts, baseOf, LANE_BASE_USAGE, parseBaseOptions } from './base'
+
+const gitSucceeds = (root: string, args: string[]): boolean =>
+  Bun.spawnSync(['git', '-C', root, ...args], { stdout: 'ignore', stderr: 'ignore' }).exitCode === 0
+
+/** What git says about `plan` against `baseRef` in the main checkout, whose copy of the plan is the one that counts. */
+const factsOf = (root: string, baseRef: string, plan: string): BaseFacts => ({
+  onBase: existsOnRef(root, baseRef, plan),
+  unchanged: gitSucceeds(root, ['diff', '--quiet', baseRef, '--', plan]),
+})
+
+/**
+ * `jh lane base <plan>`: prints the ref a lane's worktree starts from, `origin/<base branch>` or
+ * `origin/docs/plan-<topic>` (orchestrate § 2 step 2). Run `git fetch origin <base branch>` first. Exit 0 printed, 1
+ * on a wrong line.
+ */
+export const run = (args: string[], cwd: string = process.cwd()): number => {
+  if (asksForHelp(args)) {
+    console.log(LANE_BASE_USAGE)
+    return 0
+  }
+  try {
+    const { plan } = parseBaseOptions(args)
+    const root = mainCheckout(cwd)
+    const baseRef = baseRefOf(readSettings([root]))
+    console.log(baseOf(plan, baseRef, factsOf(root, baseRef, plan)))
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/lane/base.ts

@@ -0,0 +1,43 @@
+import { basename } from 'node:path'
+import { BASE_REMOTE } from '../plans/settings'
+import { CLI_NAME } from '../version/release'
+
+/** What git says about a plan against the base branch. */
+export type BaseFacts = {
+  /** The plan exists on the base branch (`git cat-file -e <base>:<plan>`). */
+  onBase: boolean
+  /** The working copy equals the base branch's (`git diff --quiet <base> -- <plan>`). */
+  unchanged: boolean
+}
+
+export type BaseOptions = { plan: string }
+
+const DOCS_BRANCH_PREFIX = 'docs/plan-'
+const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/
+const MARKDOWN_EXTENSION = /\.md$/
+
+export const LANE_BASE_USAGE = `usage: ${CLI_NAME} lane base <plan>
+
+Prints the ref a lane's worktree starts from: the base branch when the plan is on it and equals the working copy,
+else origin/${DOCS_BRANCH_PREFIX}<topic> with the plan's topic. Where the documentation commit of § 2 step 0 covered
+several files and was named after the board's directory, use that branch instead. <plan> is the plan's path from the
+repository root, without "..". The file decides, not the state of any pull request. Run \`git fetch origin <base
+branch>\` first.`
+
+/** The topic of a plan: its file name without date and extension, as the documentation branch names it. */
+export const planTopicOf = (plan: string): string =>
+  basename(plan).replace(MARKDOWN_EXTENSION, '').replace(DATE_PREFIX, '')
+
+/** The base of the lane that implements `plan`: `baseRef` when the plan is there and unchanged, else the documentation branch. */
+export const baseOf = (plan: string, baseRef: string, { onBase, unchanged }: BaseFacts): string => {
+  if (onBase && unchanged) return baseRef
+  return `${BASE_REMOTE}/${DOCS_BRANCH_PREFIX}${planTopicOf(plan)}`
+}
+
+/** Reads `<plan>`; throws with the usage on none, a second word, an option or a path that leaves the tree. */
+export const parseBaseOptions = (args: readonly string[]): BaseOptions => {
+  const [plan, ...rest] = args
+  const leaves = plan?.split('/').includes('..') === true
+  if (plan === undefined || plan.startsWith('-') || rest.length > 0 || leaves) throw new Error(LANE_BASE_USAGE)
+  return { plan }
+}