@pmelab/gtd 27.7.1 → 27.9.0

package/src/edge/Edge.test.ts

@@ -3,10 +3,10 @@ import { describe, expect, it } from "vitest"
 import { runCli } from "../cli/index.js"
 import {
   currentRest,
-  closedRunAt,
   currentRun,
   historyTrail,
   noProcessUnderway,
+  processSlices,
   renderRest,
   restAt,
   restIsIdle,
@@ -596,6 +596,171 @@ export const summary = (it) => it.marks.map((m) => m.name + "=" + m.value).join(
   })
 })
 
+const withTipMessage = (repo: InMemRepo, edit: (message: string) => string): GitOperations => {
+  const real = fakeGitOperations(repo)
+  const head = repo.resolveRef("HEAD")
+  return {
+    ...real,
+    commitHistory: (base, tip) =>
+      Effect.map(real.commitHistory(base, tip), (commits) =>
+        commits.map((c) => (c.hash === head ? { ...c, message: edit(c.message) } : c)),
+      ),
+  }
+}
+
+describe("processSlices", () => {
+  const failure = async (repo: InMemRepo): Promise<string> => {
+    const exit = await provideExit(processSlices, repo)
+    expect(Exit.isFailure(exit)).toBe(true)
+    return Exit.isFailure(exit) ? String(exit.cause) : ""
+  }
+
+  it("never reports an open slice for a closed run whose replay no longer ends", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    await land(repo, { "c.txt": "c\n" })
+    repo.writeFile(
+      "gtd.config.ts",
+      LINEAR.replace(
+        'await agent("checking", "check-prompt")',
+        'await agent("checking", "check-prompt")\n  await human("idle", { message: "again" })\n  await agent("polishing", "polish-prompt")',
+      ),
+    )
+    // Stands for a flow change with no in-repo config edit (an upgraded
+    // out-of-repo import): every ref reads as the working tree, so the
+    // config-differs refusal stays quiet and only replay drift remains.
+    const git: GitOperations = {
+      ...fakeGitOperations(repo),
+      readFileAtRef: (_ref, path) => Effect.succeed(repo.readFile(path) ?? ""),
+    }
+    const exit = await Effect.runPromiseExit(
+      processSlices.pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+    expect(Exit.isFailure(exit)).toBe(true)
+    const message = Exit.isFailure(exit) ? String(exit.cause) : ""
+    expect(message).toContain(
+      `gtd slices: refused — ${repo.resolveRef("HEAD")!.slice(0, 7)} closes a process that does not end under today's config`,
+    )
+  })
+
+  it("never reports a closed slice for an underway run whose replay now ends", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    repo.writeFile(
+      "gtd.config.ts",
+      LINEAR.replace('  await agent("checking", "check-prompt")\n', ""),
+    )
+    const message = await failure(repo)
+    expect(message).toContain("gtd slices: refused")
+    expect(message).toContain("the workflow changed under this process")
+    expect(message).toContain("gtd abandon")
+    expect(message).not.toContain("gtd slices: gtd:")
+  })
+
+  it("refuses with no process at HEAD, naming that HEAD neither closes nor sits inside one", async () => {
+    const repo = repoWith(LINEAR)
+    expect(await failure(repo)).toContain(
+      "gtd slices: refused — HEAD neither closes nor sits inside a process",
+    )
+  })
+
+  it("refuses a renamed step with replay's message, prefixed and without a gtd: lead", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    repo.writeFile("gtd.config.ts", LINEAR.replace('agent("building"', 'agent("constructing"'))
+    const message = await failure(repo)
+    expect(message).toContain("gtd slices: refused — ")
+    expect(message).not.toContain("HEAD neither closes nor sits inside a process")
+    expect(message).not.toContain("refused — gtd: ")
+    expect(message).not.toContain("gtd slices: gtd:")
+  })
+
+  it("refuses a finished process whose config file was edited since", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    await land(repo, { "c.txt": "c\n" })
+    repo.writeFile("gtd.config.ts", `${LINEAR}\n// edited\n`)
+    const message = await failure(repo)
+    expect(message).toContain(
+      `gtd slices: refused — config differs at ${repo.resolveRef("HEAD")!.slice(0, 7)}: gtd.config.ts. HEAD's process replays under today's config; revert or stash the edit to list its slices`,
+    )
+  })
+
+  const finishedProcess = async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    await land(repo, { "c.txt": "c\n" })
+    return repo
+  }
+  const slicesWith = (repo: InMemRepo, git: GitOperations) =>
+    Effect.runPromise(
+      processSlices.pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+
+  it("warns about a closed run recorded by another version, slices unchanged", async () => {
+    const repo = await finishedProcess()
+    const plain = await provide(processSlices, repo)
+    const git = withTipMessage(repo, (m) =>
+      m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+    )
+    const result = await slicesWith(repo, git)
+    expect(result.versionWarning).toContain("0.0.1")
+    expect(result.versionWarning).toContain(GTD_VERSION)
+    expect(result.slices).toEqual(plain.slices)
+  })
+
+  it("warns about an unknown version when the closing commit records none", async () => {
+    const repo = await finishedProcess()
+    const git = withTipMessage(repo, (m) => m.replace(/Gtd-Version: .*\n?/, ""))
+    expect((await slicesWith(repo, git)).versionWarning).toContain("an unknown gtd version")
+  })
+
+  it("does not warn for a closed run landed at the running version", async () => {
+    const repo = await finishedProcess()
+    expect((await provide(processSlices, repo)).versionWarning).toBeUndefined()
+  })
+
+  it("does not warn for an underway process", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    const git = withTipMessage(repo, (m) =>
+      m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+    )
+    expect((await slicesWith(repo, git)).versionWarning).toBeUndefined()
+  })
+
+  it("refuses on config drift before replay-ends drift", async () => {
+    const repo = await finishedProcess()
+    repo.writeFile(
+      "gtd.config.ts",
+      LINEAR.replace(
+        'await agent("checking", "check-prompt")',
+        'await agent("checking", "check-prompt")\n  await human("idle", { message: "again" })\n  await agent("polishing", "polish-prompt")',
+      ),
+    )
+    const message = await failure(repo)
+    expect(message).toContain("config differs at")
+    expect(message).not.toContain("does not end")
+  })
+
+  it("still lists an underway process's slices after the same config edit", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    repo.writeFile("gtd.config.ts", `${LINEAR}\n// edited\n`)
+    expect((await provide(processSlices, repo)).slices).toHaveLength(1)
+  })
+})
+
 describe("restAt", () => {
   it("restAt(ref) resolves where the process rested at that commit", async () => {
     const repo = repoWith(LINEAR)
@@ -1126,30 +1291,6 @@ describe("the pending working tree is read at most once per restAt, and never st
   })
 })
 
-describe("closedRunAt", () => {
-  it("is the run summaryRun reads when HEAD is the tip", async () => {
-    const repo = repoWith(LINEAR)
-    await land(repo, { "a.txt": "a\n" })
-    await land(repo, { "b.txt": "b\n" })
-    const tip = await land(repo, { "c.txt": "c\n" })
-    expect(await provide(closedRunAt(tip), repo)).toEqual(await provide(summaryRun, repo))
-  })
-
-  it("resolves the closed run with HEAD elsewhere", async () => {
-    const repo = repoWith(LINEAR)
-    const building = await land(repo, { "a.txt": "a\n" })
-    await land(repo, { "b.txt": "b\n" })
-    const tip = await land(repo, { "c.txt": "c\n" })
-    const closed = await provide(closedRunAt(tip), repo)
-    repo.writeFile("d.txt", "d\n")
-    repo.seedCommit("chore: unrelated")
-    const later = await provide(closedRunAt(tip), repo)
-    expect(later).toEqual(closed)
-    expect(later.closingHash).toBe(tip)
-    expect(later.startHash).toBe(building)
-  })
-})
-
 describe("finishing landings keep history", () => {
   const landingOf = async (repo: InMemRepo, git?: GitOperations) => {
     const rest = await provide(currentRest, repo)
@@ -1439,14 +1580,6 @@ export default async () => {
     expect(trail.versionWarning).toBeUndefined()
   })
 
-  const withTipMessage = (repo: InMemRepo, edit: (message: string) => string): GitOperations => {
-    const real = fakeGitOperations(repo)
-    return {
-      ...real,
-      lastCommitMessage: (ref) => Effect.map(real.lastCommitMessage(ref), edit),
-    }
-  }
-
   it("warns, never refuses, when the recorded version differs", async () => {
     const { repo, tip } = await finished()
     const git = withTipMessage(repo, (m) =>
@@ -1476,13 +1609,63 @@ export default async () => {
     expect(trail.versionWarning).toContain(GTD_VERSION)
   })
 
+  it("reads a recorded version carrying control bytes as unknown", async () => {
+    const { repo, tip } = await finished()
+    const raw = "1.0\u001b]0;x\u0007"
+    const git = withTipMessage(repo, (m) =>
+      m.replace(`Gtd-Version: ${GTD_VERSION}`, `Gtd-Version: ${raw}`),
+    )
+    const trail = await Effect.runPromise(
+      historyTrail(tip).pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+    expect(trail.version.recorded).toBeUndefined()
+    expect(trail.versionWarning).toContain("an unknown gtd version")
+    // eslint-disable-next-line no-control-regex
+    expect(trail.versionWarning).not.toMatch(/[\u0000-\u001f\u007f-\u009f]/)
+  })
+
   it("refuses naming the config file that differs at the tip", async () => {
     const { repo, tip } = await finished()
     repo.writeFile("gtd.config.ts", `${LINEAR}\n// edited\n`)
     repo.seedCommit("chore: edit config")
     const exit = await provideExit(historyTrail(tip), repo)
     expect(Exit.isFailure(exit)).toBe(true)
-    expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")
+    expect(String(Exit.isFailure(exit) && exit.cause)).toContain(
+      `gtd history: refused — config differs at ${tip.slice(0, 7)}: gtd.config.ts. A history ref replays under today's config, so it is unreadable after the config changes`,
+    )
+  })
+
+  it("refuses a resting tip with the exact message", async () => {
+    const repo = repoWith(LINEAR)
+    const tip = await land(repo, { "a.txt": "a\n" })
+    const exit = await provideExit(historyTrail(tip), repo)
+    expect(String(Exit.isFailure(exit) && exit.cause)).toContain(
+      `gtd history: ${tip.slice(0, 7)} does not close a process under today's config`,
+    )
+  })
+
+  it("reads the episode's trees exactly once", async () => {
+    const { repo, tip } = await finished()
+    let calls = 0
+    const trail = await Effect.runPromise(
+      Effect.gen(function* () {
+        const real = yield* Workspace
+        return yield* historyTrail(tip).pipe(
+          Effect.provideService(Workspace, {
+            ...real,
+            episodeTrees: (...args: Parameters<typeof real.episodeTrees>) => {
+              calls++
+              return real.episodeTrees(...args)
+            },
+          }),
+        )
+      }).pipe(Effect.provide(testLayers(repo, {}))),
+    )
+    expect(trail.steps).toHaveLength(3)
+    expect(calls).toBe(1)
   })
 
   it("refuses naming a config file missing from the tip", async () => {

package/src/edge/Edge.ts

@@ -37,6 +37,7 @@ import {
   isRecordableApproval,
   parseCommitMessage,
   replay,
+  sliceRanges,
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
@@ -51,6 +52,7 @@ import {
   UNATTRIBUTED_MODEL,
   type ApprovalEntry,
   type ModelCost,
+  type SliceEntry,
   type StepAccess,
 } from "../wire/index.js"
 
@@ -474,26 +476,21 @@ const runAtTip = (
     return yield* runOf([...before, ...closing], { ...location }, tip.hash)
   })
 
+const runAtHead = (git: GitOperations, def: WorkflowDefinition) =>
+  Effect.gen(function* () {
+    // Cheap: just HEAD's own subject, never the commits before it.
+    return yield* runAtTip(git, def, (yield* git.subjectHistory(1, 0))[0])
+  })
+
 /** The process HEAD closes or sits inside — `gtd summary`'s run. */
 export const summaryRun: Effect.Effect<ProcessRun, Error, ConfigRequirements> = Effect.gen(
   function* () {
     const git = yield* GitService
     const def = (yield* (yield* ConfigService).load).workflow
-    // Cheap: just HEAD's own subject, never the commits before it.
-    return yield* runAtTip(git, def, (yield* git.subjectHistory(1, 0))[0])
+    return yield* runAtHead(git, def)
   },
 )
 
-/** The process whose finishing commit is `tip` — reads from `tip`'s own ancestry, so it works when no branch reaches it. */
-export const closedRunAt = (tip: string): Effect.Effect<ProcessRun, Error, ConfigRequirements> =>
-  Effect.gen(function* () {
-    const git = yield* GitService
-    const def = (yield* (yield* ConfigService).load).workflow
-    const hash = yield* git.resolveRef(tip)
-    const subject = yield* git.lastCommitSubject(hash)
-    return yield* runAtTip(git, def, { hash, subject })
-  })
-
 // ── Trees ───────────────────────────────────────────────────────────────────
 
 const commitTree = (workspace: WorkspaceOps, hash: string): TreeView => {
@@ -987,6 +984,15 @@ const pendingChanges = (git: GitOperations, withIndex: boolean) =>
     return [...worktree, ...(yield* git.stagedPaths()).filter((e) => !seen.has(e.path))]
   })
 
+const sliceRangesOf = (
+  slices: Parameters<typeof sliceRanges>[0],
+  run: { readonly startParentHash: string; readonly trace: readonly { readonly hash: string }[] },
+) =>
+  sliceRanges(slices, {
+    base: run.startParentHash,
+    tip: run.trace.at(-1)?.hash ?? run.startParentHash,
+  })
+
 /** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
 export const restAt = (
   ref: string | undefined,
@@ -1065,6 +1071,69 @@ export const restAt = (
 
 export const currentRest: Effect.Effect<Rest, Error, RestRequirements> = restAt(undefined)
 
+export interface ProcessSlices {
+  readonly slices: readonly SliceEntry[]
+  readonly versionWarning?: string
+}
+
+/**
+ * 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.
+ */
+export const processSlices: Effect.Effect<ProcessSlices, Error, RestRequirements> = Effect.gen(
+  function* () {
+    const git = yield* GitService
+    const config = yield* (yield* ConfigService).load
+    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"),
+      )
+    }
+    const closing = run.closingHash
+    let outcome: ReplayOutcome
+    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),
+      })
+      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))
+    }
+    return {
+      slices: sliceRangesOf(outcome.slices, run).map(({ name, base, tip, open }) => ({
+        name,
+        base,
+        tip,
+        closed: closing !== undefined || !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
@@ -1218,7 +1287,7 @@ const multilineRefusal = (vars: Record<string, string>): Landing | undefined =>
 }
 
 const landingTarget = (
-  outcome: Awaited<ReturnType<typeof replayFor>>,
+  outcome: ReplayOutcome,
   rest: Rest,
 ): Effect.Effect<StateName | Landing, Error> => {
   if (outcome.kind === "refused")
@@ -1429,10 +1498,14 @@ const inRepoConfigPaths = (
   return [...paths].filter((p) => p !== "" && !p.startsWith("..") && !isAbsolute(p)).sort()
 }
 
-const configRefusal = (tip: string, paths: readonly string[]): Error =>
+const configRefusal = (
+  command: string,
+  tip: string,
+  paths: readonly string[],
+  reason = "A history ref replays under today's config, so it is unreadable after the config changes",
+): Error =>
   new Error(
-    `gtd history: refused — config differs at ${tip.slice(0, 7)}: ${paths.join(", ")}. ` +
-      `A history ref replays under today's config, so it is unreadable after the config changes`,
+    `${command}: refused — config differs at ${tip.slice(0, 7)}: ${paths.join(", ")}. ${reason}`,
   )
 
 const differingConfigPaths = (
@@ -1456,10 +1529,7 @@ const differingConfigPaths = (
     return differing
   })
 
-const notClosedError = (
-  hash: string,
-  outcome: Exclude<Awaited<ReturnType<typeof replayFor>>, { kind: "ended" }>,
-): Error =>
+const notClosedError = (hash: string, outcome: UnendedOutcome): Error =>
   outcome.kind === "rest"
     ? new Error(`gtd history: ${hash.slice(0, 7)} does not close a process under today's config`)
     : (replayError(outcome) ?? new Error("gtd history: replay failed"))
@@ -1494,30 +1564,52 @@ export const historyTrail = (tip: string): Effect.Effect<HistoryTrail, Error, Re
   Effect.gen(function* () {
     const git = yield* GitService
     const config = yield* (yield* ConfigService).load
-    const workspace = yield* Workspace
-    const host = yield* Host
     const hash = yield* git.resolveRef(tip)
-    const run = yield* closedRunAt(hash)
-
-    const differing = yield* differingConfigPaths(git, workspace, host.root, config, run, hash)
-    if (differing.length > 0) return yield* Effect.fail(configRefusal(hash, differing))
-
-    const { setup } = yield* setupFor(config, run, workspace, host)
-    yield* workspace.episodeTrees(
-      run.episode.base,
-      run.episode.commits.map((c) => c.hash),
-    )
-    const outcome = yield* Effect.promise(() => replayFor(setup))
-    if (outcome.kind !== "ended") return yield* Effect.fail(notClosedError(hash, outcome))
-
-    const steps = historySteps(run)
-    const recorded = parseCommitMessage(yield* git.lastCommitMessage(hash)).version
-    const versionWarning = versionWarningFor(recorded)
+    const subject = yield* git.lastCommitSubject(hash)
+    const run = yield* runAtTip(git, config.workflow, { hash, subject })
+    const { outcome, recorded, versionWarning } = yield* replayFinishedProcess(config, run, hash, {
+      command: "gtd history",
+      notEnded: (o) => notClosedError(hash, o),
+    })
     return {
       tip: hash,
-      steps,
+      steps: historySteps(run),
       ended: outcome.via,
       version: { recorded, running: GTD_VERSION },
       ...(versionWarning !== undefined ? { versionWarning } : {}),
     }
   })
+
+interface FinishedReplay {
+  readonly outcome: EndedOutcome
+  readonly recorded: string | undefined
+  readonly versionWarning?: string
+}
+
+/** Refuses on config drift before replaying, so a stale config never runs the flow. */
+const replayFinishedProcess = (
+  config: ConfigOperations,
+  run: ProcessRun,
+  hash: string,
+  how: {
+    readonly command: string
+    readonly configReason?: string
+    readonly notEnded: (outcome: UnendedOutcome) => Error
+  },
+): Effect.Effect<FinishedReplay, Error, RestRequirements> =>
+  Effect.gen(function* () {
+    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)
+    return { outcome, recorded, ...(versionWarning !== undefined ? { versionWarning } : {}) }
+  })

package/src/edge/index.ts

@@ -14,4 +14,5 @@ export {
   snapshotFromRest,
   summaryFor,
   historyTrail,
+  processSlices,
 } from "./Edge.js"

package/src/flows/runtime.test.ts

@@ -7,6 +7,7 @@ import {
   kept,
   mark,
   protocolMismatch,
+  slice,
   type FlowContext,
 } from "./runtime.js"
 
@@ -127,3 +128,29 @@ describe("kept()", () => {
     expect(FLOWS_PROTOCOL).toBe(1)
   })
 })
+
+describe("slice()", () => {
+  const withSlices = () => {
+    const calls: string[] = []
+    installContext({
+      enterSlice: (n: string) => calls.push(`enter ${n}`),
+      leaveSlice: () => calls.push("leave"),
+    } as unknown as FlowContext)
+    return calls
+  }
+
+  it("brackets fn with enter and leave and resolves to its value", async () => {
+    const calls = withSlices()
+    const value = await slice("refactor", async () => {
+      calls.push("fn")
+      return 42
+    })
+    expect(value).toBe(42)
+    expect(calls).toEqual(["enter refactor", "fn", "leave"])
+  })
+
+  it("runs fn unsliced on a context without enterSlice", async () => {
+    installContext(context)
+    expect(await slice("refactor", async () => "ran")).toBe("ran")
+  })
+})

package/src/flows/runtime.ts

@@ -150,6 +150,9 @@ export interface FlowContext {
   readonly refuse: (message: string) => never
   readonly pushScope: (scope: ScopeOptions) => void
   readonly popScope: () => void
+  /** Absent on an engine older than `slice`; FLOWS_PROTOCOL stays 1. */
+  readonly enterSlice?: (name: string) => void
+  readonly leaveSlice?: () => void
   readonly read: (path: string) => string | undefined
   readonly glob: (pattern: string) => readonly string[]
   /** The last step's changes, content read on demand. */
@@ -284,6 +287,21 @@ export const scope = async <T>(scope: string | ScopeOptions, fn: () => Promise<T
   }
 }
 
+/**
+ * Mark the span `fn` covers as one named slice of the process. Lands no
+ * commit, prefixes no step name, opens no memory scope.
+ */
+export const slice = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+  const context = ctx()
+  if (typeof context.enterSlice !== "function") return fn()
+  context.enterSlice(name)
+  try {
+    return await fn()
+  } finally {
+    context.leaveSlice?.()
+  }
+}
+
 // ── Reads of the commit replay stands on ────────────────────────────────────
 
 export const read = (path: string): string | undefined => ctx().read(path)