@pmelab/gtd 28.0.0 → 28.2.0

package/src/cli/Program.ts

@@ -162,7 +162,7 @@ export type Command =
   | { readonly kind: "uncheck"; readonly file: string }
   | { readonly kind: "install" }
   | { readonly kind: "loop" }
-  | { readonly kind: "summary" }
+  | { readonly kind: "summary"; readonly slice?: string }
   | { readonly kind: "base" }
   | { readonly kind: "judge" }
   | { readonly kind: "judgeAnswer" }
@@ -326,13 +326,20 @@ const planLanding = (
  * closes or sits inside its own closing message. Writes nothing — no git, no
  * state transition, no file. Refuses (throws, mapped to the runtime-error
  * exit code) when the workflow declares no `summary` prompt, or the resolved
- * run has no commits to name.
+ * run has no commits to name. The edge never narrates: the CLI prints the
+ * version warning, before the unknown-slice refusal; a replay refusal carries
+ * it in its message.
  */
-const runSummaryCommand = (out: ArtifactOut): Effect.Effect<void, Error, CommandRequirements> =>
+const runSummaryCommand = (
+  out: ArtifactOut,
+  sliceName: string | undefined,
+): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
     const run = yield* summaryRun
-    const rendered = yield* summaryFor(run)
-    if (rendered === undefined) {
+    const { prompt, versionWarning, unknownSlice } = yield* summaryFor(run, sliceName)
+    if (versionWarning !== undefined) yield* (yield* Narrator).warn(versionWarning)
+    if (unknownSlice !== undefined) return yield* Effect.fail(new Error(unknownSlice))
+    if (prompt === undefined) {
       return yield* Effect.fail(
         new Error(
           `gtd summary: refused — either this workflow declares no "summary:" template, or ` +
@@ -340,7 +347,7 @@ const runSummaryCommand = (out: ArtifactOut): Effect.Effect<void, Error, Command
         ),
       )
     }
-    out.write(rendered.endsWith("\n") ? rendered : rendered + "\n")
+    out.write(prompt.endsWith("\n") ? prompt : prompt + "\n")
   })
 
 /** Prints the review anchor hash bare, so an external tool can be pointed at the range under review. Nothing is written. Refuses when the run has no commits, where the hash would name a range with no review. */
@@ -1270,7 +1277,7 @@ const dispatchVoidCommand = (
     case "loop":
       return runLoopCommand()
     case "summary":
-      return runSummaryCommand(out)
+      return runSummaryCommand(out, command.slice)
     case "base":
       return runBaseCommand(out)
     case "judge":

package/src/edge/Edge.test.ts

@@ -13,6 +13,7 @@ import {
   reviewBaseFor,
   snapshotFromRest,
   stalledAt,
+  summaryFor,
   summaryRun,
   TRUNCATION_NOTICE,
   UNATTRIBUTED_MODEL,
@@ -278,9 +279,9 @@ export const again = async () => {
     )
     const run = await provide(currentRun, repo)
     expect(run.costEntries).toEqual([
-      { cost: 120, model: "opus" },
-      { cost: 50, model: UNATTRIBUTED_MODEL },
-      { cost: 300, model: "haiku" },
+      { cost: 120, model: "opus", hash: run.trace[0]!.hash },
+      { cost: 50, model: UNATTRIBUTED_MODEL, hash: run.trace[1]!.hash },
+      { cost: 300, model: "haiku", hash: run.trace[2]!.hash },
     ])
   })
 
@@ -761,7 +762,262 @@ describe("processSlices", () => {
   })
 })
 
+describe("summaryFor", () => {
+  const SLICED = `import { agent, human, slice, mark } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "idle-message" })
+  mark("risk-tier", "high")
+  await slice("build", async () => {
+    await agent("building", "build-prompt")
+  })
+  await human("gate", { message: "gate-message" })
+  await slice("verify", async () => {
+    await agent("checking", "check-prompt")
+  })
+}
+
+export const summary = (it) => JSON.stringify(it)
+`
+  const landCost = async (repo: InMemRepo, files: Files, cost: number, model: string) => {
+    write(repo, files)
+    const { stdout, stderr, exitCode } = await cli(
+      repo,
+      "land",
+      "--json",
+      `--cost=${cost}`,
+      `--model=${model}`,
+    )
+    if (exitCode !== 0) throw new Error(`gtd land exited ${exitCode}: ${stderr}${stdout}`)
+    return applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+  }
+  type Rendered = {
+    entryCommit: string
+    processBase: string
+    processTip: string
+    humanCommits: { hash: string; state: string }[]
+    processCost: number
+    processCostByModel: { model: string; cost: number }[]
+    marks: Mark[]
+    slice?: unknown
+  }
+
+  /** Entry (human, idle→building), build agent, human gate, verify agent closing. */
+  const finished = async () => {
+    const repo = repoWith(SLICED)
+    const boundary = headOf(repo)
+    const entry = await landCost(repo, { "NOTE.md": "n\n" }, 1, "opus")
+    const built = await landCost(repo, { "a.txt": "a\n" }, 10, "opus")
+    const gate = await landCost(repo, { "b.txt": "b\n" }, 100, "haiku")
+    const closing = await landCost(repo, { "c.txt": "c\n" }, 1000, "haiku")
+    return { repo, boundary, entry, built, gate, closing }
+  }
+  const render = async (repo: InMemRepo, sliceName?: string) => {
+    const run = await provide(summaryRun, repo)
+    const { prompt } = await provide(summaryFor(run, sliceName), repo)
+    return JSON.parse(prompt!) as Rendered
+  }
+
+  it("resolves each slice with its range, 1-based index and count", async () => {
+    const { repo, boundary, built, closing } = await finished()
+    expect((await render(repo, "build")).slice).toEqual({
+      name: "build",
+      base: boundary,
+      tip: built,
+      index: 1,
+      count: 2,
+    })
+    expect((await render(repo, "verify")).slice).toEqual({
+      name: "verify",
+      base: built,
+      tip: closing,
+      index: 2,
+      count: 2,
+    })
+  })
+
+  it("renders no slice key for the plain call", async () => {
+    const { repo } = await finished()
+    expect("slice" in (await render(repo))).toBe(false)
+  })
+
+  it("narrows range and human commits to the slice's window, base exclusive and tip inclusive", async () => {
+    const { repo, boundary, built, gate, closing } = await finished()
+    const whole = await render(repo)
+    expect(whole.humanCommits.map((c) => c.hash)).toEqual([gate])
+    const build = await render(repo, "build")
+    const verify = await render(repo, "verify")
+    // the gate commit falls in the gap between the slices and folds into the later one
+    expect([build.processBase, build.processTip]).toEqual([boundary, built])
+    expect([verify.processBase, verify.processTip]).toEqual([built, closing])
+    expect(build.humanCommits).toEqual([])
+    expect(verify.humanCommits.map((c) => c.hash)).toEqual([gate])
+  })
+
+  it("splits cost by slice so the parts sum to the whole, gap commits included", async () => {
+    const { repo } = await finished()
+    const whole = await render(repo)
+    const build = await render(repo, "build")
+    const verify = await render(repo, "verify")
+    expect(whole.processCost).toBe(1111)
+    expect(build.processCost + verify.processCost).toBe(whole.processCost)
+    expect(build.processCost).toBe(11)
+    expect(verify.processCost).toBe(1100)
+    const byModel = new Map<string, number>()
+    for (const part of [build, verify])
+      for (const m of part.processCostByModel)
+        byModel.set(m.model, (byModel.get(m.model) ?? 0) + m.cost)
+    expect([...byModel.entries()].sort()).toEqual(
+      whole.processCostByModel.map((m) => [m.model, m.cost] as const).sort(),
+    )
+  })
+
+  it("keeps entryCommit and marks whole-process under a slice", async () => {
+    const { repo, entry } = await finished()
+    const whole = await render(repo)
+    const verify = await render(repo, "verify")
+    expect(verify.entryCommit).toBe(entry)
+    expect(verify.entryCommit).toBe(whole.entryCommit)
+    expect(verify.marks).toEqual(whole.marks)
+    expect(verify.marks.length).toBeGreaterThan(0)
+  })
+
+  it("refuses a named slice on an empty trace, while the plain call has nothing to render", async () => {
+    const repo = repoWith(SLICED)
+    const run = await provide(summaryRun, repo)
+    const exit = await provideExit(summaryFor(run, "build"), repo)
+    expect(Exit.isFailure(exit) ? String(exit.cause) : "").toContain(
+      "gtd summary: refused — HEAD neither closes nor sits inside a process",
+    )
+    expect(await provide(summaryFor(run), repo)).toEqual({ prompt: undefined })
+  })
+
+  it("refuses config drift at a closing HEAD with the summary prefix", async () => {
+    const { repo } = await finished()
+    const run = await provide(summaryRun, repo)
+    repo.writeFile("gtd.config.ts", `${SLICED}\n// edited\n`)
+    const exit = await provideExit(summaryFor(run, "build"), repo)
+    const message = Exit.isFailure(exit) ? String(exit.cause) : ""
+    expect(message).toContain("gtd summary: refused — config differs at")
+    expect(message).toContain("revert or stash")
+  })
+
+  it.each([
+    { recorded: GTD_VERSION, warned: false },
+    { recorded: "0.0.1", warned: true },
+  ])(
+    "refuses a closed process that does not end under today's config (recorded $recorded)",
+    async ({ recorded, warned }) => {
+      const { repo } = await finished()
+      const tip = withTipMessage(repo, (m) =>
+        m.replace(`Gtd-Version: ${GTD_VERSION}`, `Gtd-Version: ${recorded}`),
+      )
+      const run = await Effect.runPromise(
+        summaryRun.pipe(
+          Effect.provideService(GitService, tip),
+          Effect.provide(testLayers(repo, {})),
+        ),
+      )
+      repo.writeFile(
+        "gtd.config.ts",
+        SLICED.replace(
+          'await agent("checking", "check-prompt")',
+          'await agent("checking", "check-prompt")\n    await human("idle", { message: "again" })\n    await agent("polishing", "polish-prompt")',
+        ),
+      )
+      // Every ref reads as the working tree: only replay divergence remains.
+      const git: GitOperations = {
+        ...tip,
+        readFileAtRef: (_ref, path) => Effect.succeed(repo.readFile(path) ?? ""),
+      }
+      const exit = await Effect.runPromiseExit(
+        summaryFor(run, "build").pipe(
+          Effect.provideService(GitService, git),
+          Effect.provide(testLayers(repo, {})),
+        ),
+      )
+      const message = Exit.isFailure(exit) ? String(exit.cause) : ""
+      expect(message).toContain(
+        `gtd summary: refused — ${repo.resolveRef("HEAD")!.slice(0, 7)} closes a process that does not end under today's config`,
+      )
+      if (warned) expect(message).toContain(`recorded by gtd ${recorded}`)
+      else expect(message).not.toContain("recorded by gtd")
+    },
+  )
+
+  it("returns no prompt, not a failure, when an edited config no longer exports a summary", async () => {
+    const { repo } = await finished()
+    const run = await provide(summaryRun, repo)
+    repo.writeFile("gtd.config.ts", SLICED.replace(/export const summary.*\n/, ""))
+    expect(await provide(summaryFor(run, "build"), repo)).toEqual({ prompt: undefined })
+  })
+
+  it("plain summaryFor still returns a prompt under a config edited since the close, never replaying", async () => {
+    const { repo } = await finished()
+    const run = await provide(summaryRun, repo)
+    repo.writeFile("gtd.config.ts", `${SLICED}\n// edited\n`)
+    expect((await provide(summaryFor(run), repo)).prompt).toBeDefined()
+  })
+
+  it("returns a version warning for a closing commit by another gtd version, not a failure", async () => {
+    const { repo } = await finished()
+    const git = withTipMessage(repo, (m) =>
+      m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+    )
+    const result = await Effect.runPromise(
+      Effect.flatMap(summaryRun, (run) => summaryFor(run, "build")).pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+    expect(result.versionWarning).toContain("0.0.1")
+    expect(result.prompt).toBeDefined()
+  })
+
+  it("an unknown slice name returns unknownSlice naming every slice, and keeps the version warning", async () => {
+    const { repo } = await finished()
+    const git = withTipMessage(repo, (m) =>
+      m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+    )
+    const result = await Effect.runPromise(
+      Effect.flatMap(summaryRun, (run) => summaryFor(run, "nope")).pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+    expect(result.prompt).toBeUndefined()
+    expect(result.unknownSlice).toContain('no slice named "nope"')
+    expect(result.unknownSlice).toContain("build, verify")
+    expect(result.versionWarning).toContain("0.0.1")
+  })
+})
+
 describe("restAt", () => {
+  it("totals recorded cost and breaks it down by model, highest first", async () => {
+    const repo = repoWith(LINEAR)
+    for (const [file, cost, model] of [
+      ["a.txt", 1, "opus"],
+      ["b.txt", 10, "haiku"],
+    ] as const) {
+      write(repo, { [file]: "x\n" })
+      const { stdout, exitCode } = await cli(
+        repo,
+        "land",
+        "--json",
+        `--cost=${cost}`,
+        `--model=${model}`,
+      )
+      expect(exitCode).toBe(0)
+      await applied(repo, (JSON.parse(stdout) as { readonly script: string }).script)
+    }
+    const { cost } = await provide(currentRest, repo)
+    expect(cost.total).toBe(11)
+    expect(cost.byModel).toEqual([
+      { model: "haiku", cost: 10 },
+      { model: "opus", cost: 1 },
+    ])
+  })
+
   it("restAt(ref) resolves where the process rested at that commit", async () => {
     const repo = repoWith(LINEAR)
     const boundary = headOf(repo)

package/src/edge/Edge.ts

@@ -45,7 +45,7 @@ import {
   type ReplayOutcome,
   type TreeView,
 } from "../replay/index.js"
-import type { Mark, ScopeAccess } from "../flows/index.js"
+import type { Mark, ScopeAccess, SummaryContext, SummarySlice } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
 import {
   judgeJson,
@@ -126,6 +126,8 @@ const locateEpisode = (def: WorkflowDefinition, history: History): EpisodeLocati
 export interface CostEntry {
   readonly cost: number
   readonly model: string
+  /** The process commit whose `Gtd-Cost` trailer recorded it. */
+  readonly hash: string
 }
 
 export interface JudgeVerdictEntry {
@@ -203,8 +205,8 @@ const traceEntryOf = (
   actor: message.parsed?.actor ?? "",
 })
 
-const costEntriesOf = (message: ReturnType<typeof parseCommitMessage>): CostEntry[] =>
-  message.cost.map((c) => ({ cost: c.cost, model: c.model ?? UNATTRIBUTED_MODEL }))
+const costEntriesOf = (hash: string, message: ReturnType<typeof parseCommitMessage>): CostEntry[] =>
+  message.cost.map((c) => ({ cost: c.cost, model: c.model ?? UNATTRIBUTED_MODEL, hash }))
 
 const hashAt = (history: History, index: number): string | undefined => history[index]?.hash
 
@@ -278,7 +280,7 @@ const buildRun = (
     startParentHash,
     diffBase: first?.reviewBase ?? startParentHash,
     trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i]!)),
-    costEntries: parsed.flatMap(costEntriesOf),
+    costEntries: parsed.flatMap((m, i) => costEntriesOf(processCommits[i]!.hash, m)),
     judgeVerdicts: parsed.flatMap((m) => m.judge),
     marks: parsed.flatMap((m) => m.marks),
     approvals: processCommits.flatMap((c, i) => approvalEntryOf(c.hash, parsed[i]!)),
@@ -904,6 +906,11 @@ const costByModel = (entries: readonly CostEntry[]): ModelCost[] => {
     .sort((a, b) => b.cost - a.cost || a.model.localeCompare(b.model))
 }
 
+const costTotals = (entries: readonly CostEntry[]): Rest["cost"] => ({
+  total: entries.reduce((sum, entry) => sum + entry.cost, 0),
+  byModel: costByModel(entries),
+})
+
 export type RestRequirements = ConfigRequirements
 
 const setupFor = (
@@ -1061,10 +1068,7 @@ export const restAt = (
       memory: memory.key,
       memoryResumed: memory.resumed,
       hints: hintsOf(stepDef),
-      cost: {
-        total: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
-        byModel: costByModel(run.costEntries),
-      },
+      cost: costTotals(run.costEntries),
       setup,
     }
   })
@@ -1076,21 +1080,42 @@ export interface ProcessSlices {
   readonly versionWarning?: string
 }
 
+type EndedOutcome = Extract<ReplayOutcome, { kind: "ended" }>
+type UnendedOutcome = Exclude<ReplayOutcome, { kind: "ended" }>
+
+/** Every slice refusal reads `<command>: refused — <reason>`; replay's own `gtd: ` lead is dropped. */
+const slicesDivergence = (command: string, run: ProcessRun, outcome: ReplayOutcome): Error => {
+  const reason =
+    outcome.kind === "rest" && run.closingHash !== undefined
+      ? `${run.closingHash.slice(0, 7)} closes a process that does not end under today's config`
+      : (replayError(outcome)?.message.replace(/^gtd: /, "") ?? "replay failed")
+  return new Error(`${command}: refused — ${reason}`)
+}
+
 /**
- * The slices of the process HEAD closes or sits inside, current episode only,
- * stack order. Reads like `historyTrail`, never `restAt`: it narrates and
- * writes nothing, and returns a version warning for a closed run.
+ * The replay `gtd slices` and `gtd summary --slice` share: the slice ranges of
+ * `run`, plus whether HEAD closes it. Reads like `historyTrail`, never
+ * `restAt`: it narrates and writes nothing.
  */
-export const processSlices: Effect.Effect<ProcessSlices, Error, RestRequirements> = Effect.gen(
-  function* () {
-    const git = yield* GitService
-    const config = yield* (yield* ConfigService).load
+const replayedSlices = (
+  config: ConfigOperations,
+  run: ProcessRun,
+  how: { readonly command: string; readonly configReason: string },
+): Effect.Effect<
+  {
+    readonly ranges: ReturnType<typeof sliceRangesOf>
+    readonly closed: boolean
+    readonly versionWarning?: string
+  },
+  Error,
+  RestRequirements
+> =>
+  Effect.gen(function* () {
     const workspace = yield* Workspace
     const host = yield* Host
-    const run = yield* runAtHead(git, config.workflow)
     if (run.trace.length === 0) {
       return yield* Effect.fail(
-        new Error("gtd slices: refused — HEAD neither closes nor sits inside a process"),
+        new Error(`${how.command}: refused — HEAD neither closes nor sits inside a process`),
       )
     }
     const closing = run.closingHash
@@ -1098,42 +1123,51 @@ export const processSlices: Effect.Effect<ProcessSlices, Error, RestRequirements
     let versionWarning: string | undefined
     if (closing !== undefined) {
       const replayed = yield* replayFinishedProcess(config, run, closing, {
-        command: "gtd slices",
-        configReason:
-          "HEAD's process replays under today's config; revert or stash the edit to list its slices",
-        notEnded: (o) => slicesDivergence(run, o),
+        command: how.command,
+        configReason: how.configReason,
+        notEnded: (o) => slicesDivergence(how.command, run, o),
       })
       outcome = replayed.outcome
       versionWarning = replayed.versionWarning
     } else {
       const { setup } = yield* setupFor(config, run, workspace, host)
       outcome = yield* Effect.promise(() => replayFor(setup))
-      if (outcome.kind !== "rest") return yield* Effect.fail(slicesDivergence(run, outcome))
+      if (outcome.kind !== "rest")
+        return yield* Effect.fail(slicesDivergence(how.command, run, outcome))
     }
     return {
-      slices: sliceRangesOf(outcome.slices, run).map(({ name, base, tip, open }) => ({
+      ranges: sliceRangesOf(outcome.slices, run),
+      closed: closing !== undefined,
+      ...(versionWarning !== undefined ? { versionWarning } : {}),
+    }
+  })
+
+/**
+ * The slices of the process HEAD closes or sits inside, current episode only,
+ * stack order. Returns a version warning for a closed run.
+ */
+export const processSlices: Effect.Effect<ProcessSlices, Error, RestRequirements> = Effect.gen(
+  function* () {
+    const git = yield* GitService
+    const config = yield* (yield* ConfigService).load
+    const run = yield* runAtHead(git, config.workflow)
+    const { ranges, closed, versionWarning } = yield* replayedSlices(config, run, {
+      command: "gtd slices",
+      configReason:
+        "HEAD's process replays under today's config; revert or stash the edit to list its slices",
+    })
+    return {
+      slices: ranges.map(({ name, base, tip, open }) => ({
         name,
         base,
         tip,
-        closed: closing !== undefined || !open,
+        closed: closed || !open,
       })),
       ...(versionWarning !== undefined ? { versionWarning } : {}),
     }
   },
 )
 
-type EndedOutcome = Extract<ReplayOutcome, { kind: "ended" }>
-type UnendedOutcome = Exclude<ReplayOutcome, { kind: "ended" }>
-
-/** Every `gtd slices` refusal reads `gtd slices: refused — <reason>`; replay's own `gtd: ` lead is dropped. */
-const slicesDivergence = (run: ProcessRun, outcome: ReplayOutcome): Error => {
-  const reason =
-    outcome.kind === "rest" && run.closingHash !== undefined
-      ? `${run.closingHash.slice(0, 7)} closes a process that does not end under today's config`
-      : (replayError(outcome)?.message.replace(/^gtd: /, "") ?? "replay failed")
-  return new Error(`gtd slices: refused — ${reason}`)
-}
-
 /**
  * Whether `gtd --workflow <name>` can start a process here: the workflow must
  * reach a step from the tree the opening commit would capture. That step is
@@ -1440,29 +1474,107 @@ export const snapshotFromRest = (
 
 // ── Summary ─────────────────────────────────────────────────────────────────
 
-/** `gtd summary`'s prompt for `run`, or `undefined` when the workflow has none or there is nothing to summarize. */
+const narrowToSlice = (
+  run: ProcessRun,
+  slice: SummarySlice | undefined,
+): Pick<ProcessRun, "trace" | "costEntries"> => {
+  if (slice === undefined) return { trace: run.trace, costEntries: run.costEntries }
+  // `base` is exclusive: -1 when it is the episode's start parent, before the first entry.
+  const from =
+    slice.base === run.startParentHash ? -1 : run.trace.findIndex((e) => e.hash === slice.base)
+  const to = run.trace.findIndex((e) => e.hash === slice.tip)
+  const trace = run.trace.slice(from + 1, to + 1)
+  const hashes = new Set(trace.map((e) => e.hash))
+  return { trace, costEntries: run.costEntries.filter((c) => hashes.has(c.hash)) }
+}
+
+interface SummaryResult {
+  readonly prompt: string | undefined
+  readonly versionWarning?: string
+  readonly unknownSlice?: string
+}
+
+const humanCommitsOf = (
+  trace: ProcessRun["trace"],
+  entryCommit: string,
+): { hash: string; state: StateName }[] =>
+  trace
+    .filter((entry) => entry.actor === "human" && entry.hash !== entryCommit)
+    .map((entry) => ({ hash: entry.hash, state: entry.state }))
+
+const summaryInput = (
+  run: ProcessRun,
+  slice: SummarySlice | undefined,
+  settings: Pick<SummaryContext, "vars" | "env">,
+) => {
+  const entryCommit = run.trace[0]!.hash
+  const { trace, costEntries } = narrowToSlice(run, slice)
+  const { total, byModel } = costTotals(costEntries)
+  return {
+    entryCommit,
+    processBase: slice?.base ?? run.startParentHash,
+    processTip: slice?.tip ?? run.trace[run.trace.length - 1]!.hash,
+    humanCommits: humanCommitsOf(trace, entryCommit),
+    processCost: total,
+    processCostByModel: byModel,
+    marks: run.marks,
+    ...settings,
+    ...(slice !== undefined ? { slice } : {}),
+  }
+}
+
+const locateSlice = (
+  config: ConfigOperations,
+  run: ProcessRun,
+  sliceName: string | undefined,
+): Effect.Effect<
+  | { readonly slice?: SummarySlice; readonly versionWarning?: string }
+  | { readonly unknownSlice: string; readonly versionWarning?: string },
+  Error,
+  RestRequirements
+> =>
+  Effect.gen(function* () {
+    if (sliceName === undefined) return {}
+    const replayed = yield* replayedSlices(config, run, {
+      command: "gtd summary",
+      configReason:
+        "HEAD's process replays under today's config; revert or stash the edit to summarize its slices",
+    })
+    const { ranges, versionWarning } = replayed
+    const warn = versionWarning !== undefined ? { versionWarning } : {}
+    const at = ranges.findIndex((r) => r.name === sliceName)
+    if (at < 0) {
+      return {
+        unknownSlice: `gtd summary: refused — no slice named "${sliceName}"; the slices, in stack order: ${ranges.map((r) => r.name).join(", ")}`,
+        ...warn,
+      }
+    }
+    const { base, tip } = ranges[at]!
+    return { slice: { name: sliceName, base, tip, index: at + 1, count: ranges.length }, ...warn }
+  })
+
+/**
+ * A plain call never replays; under a slice, `entryCommit` and `marks` stay
+ * whole-process.
+ */
 export const summaryFor = (
   run: ProcessRun,
-): Effect.Effect<string | undefined, Error, RestRequirements> =>
+  sliceName?: string,
+): Effect.Effect<SummaryResult, Error, RestRequirements> =>
   Effect.gen(function* () {
     const config = yield* (yield* ConfigService).load
     const host = yield* Host
     const resolved = yield* workflowOf(config, run)
     const summary = resolved.def.summary
-    if (summary === undefined || run.trace.length === 0) return undefined
-    const entryCommit = run.trace[0]!.hash
-    return summary({
-      entryCommit,
-      processBase: run.startParentHash,
-      processTip: run.trace[run.trace.length - 1]!.hash,
-      humanCommits: run.trace
-        .filter((entry) => entry.actor === "human" && entry.hash !== entryCommit)
-        .map((entry) => ({ hash: entry.hash, state: entry.state })),
-      processCost: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
-      processCostByModel: costByModel(run.costEntries),
-      marks: run.marks,
-      ...settingsFor(resolved, run.pinnedVars, host.env, {}, {}),
-    })
+    if (summary === undefined) return { prompt: undefined }
+    if (sliceName === undefined && run.trace.length === 0) return { prompt: undefined }
+    const located = yield* locateSlice(config, run, sliceName)
+    if ("unknownSlice" in located) return { prompt: undefined, ...located }
+    const { slice, versionWarning } = located
+    const prompt = summary(
+      summaryInput(run, slice, settingsFor(resolved, run.pinnedVars, host.env, {}, {})),
+    )
+    return { prompt, ...(versionWarning !== undefined ? { versionWarning } : {}) }
   })
 
 export interface HistoryStep {
@@ -1601,15 +1713,20 @@ const replayFinishedProcess = (
     const git = yield* GitService
     const workspace = yield* Workspace
     const host = yield* Host
-    const differing = yield* differingConfigPaths(git, workspace, host.root, config, run, hash)
-    if (differing.length > 0)
-      return yield* Effect.fail(configRefusal(how.command, hash, differing, how.configReason))
-    const { setup } = yield* setupFor(config, run, workspace, host)
-    const outcome = yield* Effect.promise(() => replayFor(setup))
-    if (outcome.kind !== "ended") return yield* Effect.fail(how.notEnded(outcome))
     const recorded = parseCommitMessage(
       run.episode.commits.find((c) => c.hash === hash)?.message ?? "",
     ).version
     const versionWarning = versionWarningFor(recorded)
+    // A refusal is often caused by the version change, so it carries the warning.
+    const withWarning = (err: Error): Error =>
+      versionWarning === undefined ? err : new Error(`${err.message}\n${versionWarning}`)
+    const differing = yield* differingConfigPaths(git, workspace, host.root, config, run, hash)
+    if (differing.length > 0)
+      return yield* Effect.fail(
+        withWarning(configRefusal(how.command, hash, differing, how.configReason)),
+      )
+    const { setup } = yield* setupFor(config, run, workspace, host)
+    const outcome = yield* Effect.promise(() => replayFor(setup))
+    if (outcome.kind !== "ended") return yield* Effect.fail(withWarning(how.notEnded(outcome)))
     return { outcome, recorded, ...(versionWarning !== undefined ? { versionWarning } : {}) }
   })