jackherd 1.16.0 → 1.18.0

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 }
+}

package/src/lane/close-check.ts

@@ -9,11 +9,17 @@ export const BOARD_LANE = { open: 'open', closed: 'closed', missing: 'missing' }
 
 export type BoardLane = (typeof BOARD_LANE)[keyof typeof BOARD_LANE]
 
-/** The lane's branch, the head the check compared, and its merged pull request once nothing stands against closing it. */
-export type ClosableLane = { branch: string; head: string; pullRequest: MergedPullRequest }
+/**
+ * What the check proved once nothing stands against closing: a lane on a branch (its branch, the head the check
+ * compared, null when the branch is gone already, and its merged pull request), or a worktree on no branch whose head
+ * stands on the base branch.
+ */
+export type ClosableLane =
+  | { kind: 'branch'; branch: string; head: string | null; pullRequest: MergedPullRequest }
+  | { kind: 'detached'; head: string }
 
 /** Every reason against closing, or the lane ready to close; the second only when the first is empty. */
-export type CloseVerdict = { kind: 'refused'; refusals: string[] } | ({ kind: 'closable' } & ClosableLane)
+export type CloseVerdict = { kind: 'refused'; refusals: string[] } | { kind: 'closable'; lane: ClosableLane }
 
 /** One entry of `git status --porcelain`: its two status letters (`!!` ignored, `??` untracked) and its path. */
 export type StatusEntry = { code: string; path: string }
@@ -28,14 +34,19 @@ export type CloseFacts = {
   lane: string
   boardLane: BoardLane
   worktreeExists: boolean
+  /** The worktree's branch; without a worktree the branch `--branch` names, null when none was named. */
   branch: string | null
-  /** The commit the worktree's branch points to, as `git worktree list` reports it; null without a worktree. */
+  /** The commit the worktree or, without one, the named branch points to; null when neither exists. */
   head: string | null
   pullRequest: MergedPullRequest | null
   treeDiff: readonly string[]
   status: readonly StatusEntry[]
   setupFiles: readonly string[]
   handoverEntries: readonly string[]
+  /** Whether the head of a worktree on no branch is an ancestor of the base branch on the remote. */
+  headOnBase: boolean
+  /** The staged paths of a worktree on no branch that the base branch on the remote holds with the same content. */
+  baseHeldPaths: readonly string[]
   /** The agent named after the lane whose directory lies in the worktree, with its pane. */
   agent: { pane: string; status: string } | null
   /** The panes of other agents whose directory lies in the worktree: a helper, or a session without the lane's name. */
@@ -64,6 +75,10 @@ const BUILD_OUTPUT = [
 const BUILD_OUTPUT_DIRECTORY_ENTRIES = [new Bun.Glob('packages/*/bin')]
 const HANDOVER = claudePath(HANDOVER_DIRECTORY)
 
+/** A change that is staged and nothing more: the worktree file equals the index. */
+const isStagedOnly = (code: string): boolean =>
+  code[0] !== ' ' && code[0] !== '?' && code[0] !== IGNORED_CODE[0] && code[1] === ' '
+
 const withoutSlashes = (path: string): string => path.replace(/^\/+|\/+$/g, '')
 
 const isHandoverDirectory = (path: string): boolean => withoutSlashes(path) === HANDOVER
@@ -121,23 +136,33 @@ export const isBuildOutput = (path: string): boolean => {
  * The paths removing the worktree would delete for good: every tracked change and untracked file, and every ignored
  * path except dependencies (`node_modules` at any depth), the setup files, build output and the handover directory.
  */
-export const lostPathsOf = (status: readonly StatusEntry[], setupFiles: readonly string[]): string[] => {
+export const lostPathsOf = (
+  status: readonly StatusEntry[],
+  setupFiles: readonly string[],
+  baseHeldPaths: readonly string[] = [],
+): string[] => {
   const kept = (path: string) =>
     isDependencyPath(path) || isSetupFile(path, setupFiles) || isBuildOutput(path) || isHandoverDirectory(path)
-  return status.filter(({ code, path }) => code !== IGNORED_CODE || !kept(path)).map(({ path }) => path)
+  const held = ({ code, path }: StatusEntry) => isStagedOnly(code) && baseHeldPaths.includes(path)
+  return status
+    .filter((entry) => (entry.code !== IGNORED_CODE || !kept(entry.path)) && !held(entry))
+    .map(({ path }) => path)
 }
 
 /** The lost paths and the entries of the handover directory, each once: the directory stands for all of them. */
-const deletedPathsOf = ({ status, setupFiles, handoverEntries }: CloseFacts): string[] => [
-  ...new Set([...lostPathsOf(status, setupFiles), ...handoverEntries]),
+const deletedPathsOf = ({ status, setupFiles, handoverEntries, baseHeldPaths }: CloseFacts): string[] => [
+  ...new Set([...lostPathsOf(status, setupFiles, baseHeldPaths), ...handoverEntries]),
 ]
 
 /** A lane the board marks cleaned up already may still have its worktree left over; only a lane it never named is refused. */
 const boardRefusals = ({ lane, boardLane }: CloseFacts): string[] =>
   boardLane === BOARD_LANE.missing ? [`the board has no row for lane ${lane}`] : []
 
-const mergeRefusals = ({ lane, branch, pullRequest, treeDiff }: CloseFacts): string[] => {
-  if (branch === null) return [`the worktree of ${lane} is on no branch`]
+const detachedRefusals = ({ lane, headOnBase }: CloseFacts): string[] =>
+  headOnBase ? [] : [`the worktree of ${lane} is on no branch and its head is not on the base branch`]
+
+const mergeRefusals = ({ branch, pullRequest, treeDiff }: CloseFacts): string[] => {
+  if (branch === null) return []
   if (pullRequest === null) return [`branch ${branch} has no merged pull request`]
   return treeDiff.map(
     (path) => `branch ${branch} differs from the merge of #${pullRequest.number} (${pullRequest.mergeCommit}): ${path}`,
@@ -162,11 +187,17 @@ const lockRefusals = ({ lane, locked }: CloseFacts): string[] =>
  * on the worktree (a Claude Code session may still hold it).
  */
 export const closeRefusals = (facts: CloseFacts): string[] => {
-  if (!facts.worktreeExists) return [...boardRefusals(facts), `lane ${facts.lane} has no worktree`]
+  if (!facts.worktreeExists)
+    return [
+      ...boardRefusals(facts),
+      ...(facts.branch === null
+        ? [`lane ${facts.lane} has no worktree; name its branch with --branch to finish closing it`]
+        : mergeRefusals(facts)),
+    ]
   if (facts.runsInside) return [`run it outside the worktree of ${facts.lane}, which it would remove`]
   return [
     ...boardRefusals(facts),
-    ...mergeRefusals(facts),
+    ...(facts.branch === null ? detachedRefusals(facts) : mergeRefusals(facts)),
     ...deletedPathsOf(facts).map((path) => `removing the worktree deletes ${path}`),
     ...agentRefusals(facts),
     ...lockRefusals(facts),
@@ -176,8 +207,11 @@ export const closeRefusals = (facts: CloseFacts): string[] => {
 /** `closeRefusals` as a verdict that carries the branch and pull request it proved, so a caller needs no second check. */
 export const closeVerdict = (facts: CloseFacts): CloseVerdict => {
   const refusals = closeRefusals(facts)
+  if (refusals.length > 0) return { kind: 'refused', refusals }
   const { branch, head, pullRequest } = facts
-  if (refusals.length > 0 || branch === null || head === null || pullRequest === null)
-    return { kind: 'refused', refusals }
-  return { kind: 'closable', branch, head, pullRequest }
+  if (branch !== null && pullRequest !== null)
+    return { kind: 'closable', lane: { kind: 'branch', branch, head, pullRequest } }
+  return head === null
+    ? { kind: 'refused', refusals: [`the worktree of ${facts.lane} has no head to compare`] }
+    : { kind: 'closable', lane: { kind: 'detached', head } }
 }

package/src/lane/close-command.ts

@@ -13,9 +13,17 @@ import { runGh } from '../watch/gh'
 import { parseWatchedPullRequests, WATCHED_PULL_REQUEST_FIELDS } from '../watch/pull-requests'
 import { type ClosePorts, type CloseRequest, type CloseSurvey, closeLane } from './close'
 import { boardLaneOf } from './close-board'
-import { type CloseFacts, type MergedPullRequest, statusEntriesOf } from './close-check'
+import { type CloseFacts, type MergedPullRequest, type StatusEntry, statusEntriesOf } from './close-check'
 import { type CloseOptions, LANE_CLOSE_USAGE, parseCloseOptions } from './close-options'
-import { agentFactsOf, mergedPullRequestOf, openWorkspaceOf, type WorktreeEntry, worktreeEntryOf } from './close-survey'
+import {
+  agentFactsOf,
+  baseHeldPathsOf,
+  mergedPullRequestOf,
+  openWorkspaceOf,
+  stagedPlanPathsOf,
+  type WorktreeEntry,
+  worktreeEntryOf,
+} from './close-survey'
 
 /** Where the command runs and what it acts on, located once. */
 type CloseContext = { root: string; cwd: string; settings: PlansSettings; worktree: string; boardFile: string }
@@ -23,7 +31,16 @@ type CloseContext = { root: string; cwd: string; settings: PlansSettings; worktr
 /** The facts that only a worktree git lists has. */
 type WorktreeFacts = Pick<
   CloseFacts,
-  'worktreeExists' | 'branch' | 'head' | 'pullRequest' | 'treeDiff' | 'status' | 'handoverEntries' | 'locked'
+  | 'worktreeExists'
+  | 'branch'
+  | 'head'
+  | 'pullRequest'
+  | 'treeDiff'
+  | 'status'
+  | 'handoverEntries'
+  | 'headOnBase'
+  | 'baseHeldPaths'
+  | 'locked'
 >
 
 /** The file the lane setup copies into every new worktree, in `.gitignore` syntax. */
@@ -51,6 +68,8 @@ const ABSENT_WORKTREE: WorktreeFacts = {
   treeDiff: [],
   status: [],
   handoverEntries: [],
+  headOnBase: false,
+  baseHeldPaths: [],
   locked: null,
 }
 
@@ -97,30 +116,71 @@ const mergedPullRequestOn = async (context: CloseContext, branch: string): Promi
   return mergedPullRequestOf(parseWatchedPullRequests(answer.stdout), branch)
 }
 
+const remoteBase = (context: CloseContext): string => `origin/${context.settings.baseBranch}`
+
+/** Whether `head` is an ancestor of the base branch on the remote; false for an answer other than yes. */
+const isOnBase = (context: CloseContext, head: string): boolean =>
+  Bun.spawnSync(['git', '-C', context.root, 'merge-base', '--is-ancestor', head, remoteBase(context)]).exitCode === 0
+
+/** The staged plan changes of the worktree that the base branch on the remote holds as they are staged. */
+const baseHeldPathsIn = (context: CloseContext, status: readonly StatusEntry[]): string[] => {
+  const candidates = stagedPlanPathsOf(status, context.settings.planDirectory)
+  if (candidates.length === 0) return []
+  const differing = linesOf(
+    runGit(context.worktree, ['diff', '--cached', '--name-only', remoteBase(context), '--', ...candidates]),
+  )
+  return baseHeldPathsOf(candidates, differing)
+}
+
 /** Branch, merged pull request, tree difference, status, handover files and lock of the worktree git lists for the lane. */
 const worktreeFactsOf = async (context: CloseContext, entry: WorktreeEntry): Promise<WorktreeFacts> => {
   const pullRequest = entry.branch === null ? null : await mergedPullRequestOn(context, entry.branch)
+  const status = statusEntriesOf(
+    runGit(context.worktree, ['status', '--porcelain=v1', '-z', IGNORED_MATCHING, ALL_UNTRACKED]),
+  )
+  const detached = entry.branch === null
   return {
     worktreeExists: true,
     branch: entry.branch,
     head: entry.head,
     pullRequest,
     treeDiff: pullRequest === null ? [] : treeDiffOf(context, entry.head, pullRequest.mergeCommit),
-    status: statusEntriesOf(
-      runGit(context.worktree, ['status', '--porcelain=v1', '-z', IGNORED_MATCHING, ALL_UNTRACKED]),
-    ),
+    status,
     handoverEntries: handoverEntriesOf(context.worktree),
+    headOnBase: detached && isOnBase(context, entry.head),
+    baseHeldPaths: detached ? baseHeldPathsIn(context, status) : [],
     locked: entry.locked,
   }
 }
 
+/** The commit the local branch points to; null when there is no such branch. */
+const branchHeadOf = (context: CloseContext, branch: string): string | null => {
+  const result = Bun.spawnSync(
+    ['git', '-C', context.root, 'rev-parse', '--verify', '--quiet', `${BRANCH_REF}${branch}^{commit}`],
+    { stdout: 'pipe' },
+  )
+  return result.exitCode === 0 ? result.stdout.toString().trim() : null
+}
+
+/** What survives of a lane whose worktree is gone: the branch `--branch` names, if it is still there, and its merged pull request. */
+const branchFactsOf = async (context: CloseContext, branch: string): Promise<WorktreeFacts> => {
+  const head = branchHeadOf(context, branch)
+  const pullRequest = await mergedPullRequestOn(context, branch)
+  const treeDiff = head === null || pullRequest === null ? [] : treeDiffOf(context, head, pullRequest.mergeCommit)
+  return { ...ABSENT_WORKTREE, branch, head, pullRequest, treeDiff }
+}
+
 const workspaceOf = (context: CloseContext): string | null =>
   context.settings.adapter === TERMINAL_ADAPTER.herdr
     ? openWorkspaceOf(runHerdr(['worktree', 'list', '--cwd', context.root]), context.worktree)
     : null
 
+/** The facts of a lane without a worktree: only what survives in the branch `--branch` names, if one was named. */
+const absentWorktreeFactsOf = (context: CloseContext, branch: string | null): Promise<WorktreeFacts> | WorktreeFacts =>
+  branch === null ? ABSENT_WORKTREE : branchFactsOf(context, branch)
+
 /** What git, GitHub and the terminal say about the lane now; throws when one of them cannot be asked. */
-const surveyOf = async (lane: string, context: CloseContext): Promise<CloseSurvey> => {
+const surveyOf = async (lane: string, branch: string | null, context: CloseContext): Promise<CloseSurvey> => {
   const entry = worktreeEntryOf(runGit(context.root, ['worktree', 'list', '--porcelain']), context.worktree)
   const present = entry !== null && existsSync(context.worktree)
   const facts: CloseFacts = {
@@ -129,7 +189,7 @@ const surveyOf = async (lane: string, context: CloseContext): Promise<CloseSurve
     setupFiles: setupFilesOf(context.root),
     ...agentFactsOf(laneStatusSourceFor(context.settings.adapter).listAgents(), lane, context.worktree),
     runsInside: realPath(worktreeRoot(context.cwd)) === realPath(context.worktree),
-    ...(present ? await worktreeFactsOf(context, entry) : ABSENT_WORKTREE),
+    ...(present ? await worktreeFactsOf(context, entry) : await absentWorktreeFactsOf(context, branch)),
   }
   return { facts, workspace: present ? workspaceOf(context) : null }
 }
@@ -166,8 +226,8 @@ const deleteBranchIn =
     runGit(context.root, ['update-ref', '-d', `${BRANCH_REF}${branch}`, head])
   }
 
-const portsFor = (lane: string, context: CloseContext): ClosePorts => ({
-  survey: () => surveyOf(lane, context),
+const portsFor = (lane: string, branch: string | null, context: CloseContext): ClosePorts => ({
+  survey: () => surveyOf(lane, branch, context),
   exitAgent: exitAgentIn(context),
   removeWorktree: removeWorktreeIn(context),
   deleteBranch: deleteBranchIn(context),
@@ -209,7 +269,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
       now: new Date(),
       language: context.settings.planLanguage,
     }
-    return await closeLane(request, portsFor(options.lane, context))
+    return await closeLane(request, portsFor(options.lane, options.branch, context))
   } catch (error) {
     console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
     return 1