@pmelab/gtd 27.8.0 → 27.9.0

package/src/edge/Edge.ts

@@ -43,7 +43,6 @@ import {
   type JudgeVerdict,
   type ReachedStep,
   type ReplayOutcome,
-  type SliceRange,
   type TreeView,
 } from "../replay/index.js"
 import type { Mark, ScopeAccess } from "../flows/index.js"
@@ -53,6 +52,7 @@ import {
   UNATTRIBUTED_MODEL,
   type ApprovalEntry,
   type ModelCost,
+  type SliceEntry,
   type StepAccess,
 } from "../wire/index.js"
 
@@ -476,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 => {
@@ -897,7 +892,6 @@ interface Rest extends ResolvedRest {
   /** Total recorded cost of the process, and its per-model breakdown. */
   readonly cost: { readonly total: number; readonly byModel: readonly ModelCost[] }
   readonly setup: ReplaySetup
-  readonly slices: readonly SliceRange[]
 }
 
 /** Per-model token totals, highest-cost first (ties broken by model name). */
@@ -1072,12 +1066,74 @@ export const restAt = (
         byModel: costByModel(run.costEntries),
       },
       setup,
-      slices: sliceRangesOf(outcome.slices, run),
     }
   })
 
 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
@@ -1231,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")
@@ -1442,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 = (
@@ -1469,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"))
@@ -1507,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/replay/Replay.test.ts

@@ -1231,6 +1231,38 @@ describe("slice()", () => {
     ])
   })
 
+  it("an ended outcome carries every span of the episode that just ended", async () => {
+    const wf = async () => {
+      await slice("one", async () => {
+        await human("a")
+      })
+      await slice("two", async () => {
+        await human("b")
+      })
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "done")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "ended", via: "return" })
+    expect(spansOf(outcome)).toEqual([
+      { name: "one", enteredAt: hashOf(0), leftAt: hashOf(1) },
+      { name: "two", enteredAt: hashOf(1), leftAt: hashOf(2) },
+    ])
+  })
+
+  it("restart() inside a slice ends via restart with that span's leftAt undefined", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("risky", async () => {
+        await human("b")
+        await restart()
+      })
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "done")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "ended", via: "restart" })
+    expect(spansOf(outcome)).toEqual([{ name: "risky", enteredAt: hashOf(1), leftAt: undefined }])
+  })
+
   it("keeps leftAt undefined when the process rests inside the slice", async () => {
     const wf = async () => {
       await slice("refactor", async () => {

package/src/replay/Replay.ts

@@ -126,6 +126,8 @@ export type ReplayOutcome =
       readonly trace: readonly ReachedStep[]
       readonly landed: ReachedStep | undefined
       readonly marks: readonly Mark[]
+      /** Spans of the episode that just ended; a restart() inside a slice leaves its leftAt undefined. */
+      readonly slices: readonly SliceSpan[]
     }
   | { readonly kind: "divergence"; readonly message: string }
   | { readonly kind: "refused"; readonly message: string }
@@ -613,7 +615,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
           kind: "divergence",
           message: `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode — ${DIVERGED}`,
         }
-      : { kind: "ended", via, trace, landed, marks }
+      : { kind: "ended", via, trace, landed, marks, slices: slices.map((s) => ({ ...s })) }
 
   const changesSince = (hash: string): readonly Change[] => {
     const tree = treeAt(hash)

package/src/replay/Trailers.test.ts

@@ -115,6 +115,17 @@ describe("the commit-message codec", () => {
     expect(parsed.version).toBe("1.2.3")
   })
 
+  it("reads a Gtd-Version carrying control bytes as unknown, and keeps spaces and parens", () => {
+    const withVersion = (value: string) =>
+      formatCommitMessage({ actor: "a", to: "b" }).replace(
+        "Gtd-Format: 1",
+        `Gtd-Version: ${value}\nGtd-Format: 1`,
+      )
+    expect(parseCommitMessage(withVersion("1.0\u001b]0;x\u0007")).version).toBeUndefined()
+    expect(parseCommitMessage(withVersion("1.0\u009b")).version).toBeUndefined()
+    expect(parseCommitMessage(withVersion("0.0.1 (dev)")).version).toBe("0.0.1 (dev)")
+  })
+
   it("omits Gtd-Branch and Gtd-Version when unset, and reads them as undefined", () => {
     const message = formatCommitMessage({ actor: "agent", to: "idle" })
     expect(message).not.toContain("Gtd-Branch")

package/src/replay/Trailers.ts

@@ -196,7 +196,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
     if (value !== "") into.branch ??= value
   },
   "Gtd-Version": (value, into) => {
-    if (value !== "") into.version ??= value
+    // Untrusted (fetched history): control bytes would reach the terminal; a rejected value reads as unknown.
+    // eslint-disable-next-line no-control-regex
+    if (value !== "" && !/[\u0000-\u001f\u007f-\u009f]/.test(value)) into.version ??= value
   },
   "Gtd-Kept": (value, into) => {
     if (HASH_RE.test(value)) into.kept ??= value

package/src/replay/index.ts

@@ -12,4 +12,4 @@ export {
 export { accessShapeFault, foldAccess } from "./Access.js"
 export { formatFault } from "./Format.js"
 export { refNameFault } from "./RefName.js"
-export { sliceRanges, type SliceRange } from "./Slices.js"
+export { sliceRanges } from "./Slices.js"

package/src/wire/Slices.ts

@@ -0,0 +1,25 @@
+import { WIRE_SCHEMA } from "./constants.js"
+
+export interface SliceEntry {
+  readonly name: string
+  /** Full hash, exclusive: git's base..tip. */
+  readonly base: string
+  /** Full hash, inclusive; HEAD's hash for the open slice. */
+  readonly tip: string
+  /** false only for the last slice of an underway process. */
+  readonly closed: boolean
+}
+
+export interface SlicesDocument {
+  readonly schema: number
+  readonly slices: readonly SliceEntry[]
+}
+
+/** The ONLY place `gtd slices --json`'s shape is built; copies exactly the four fields, in order. */
+export const slicesDocument = (slices: readonly SliceEntry[]): SlicesDocument => ({
+  schema: WIRE_SCHEMA,
+  slices: slices.map(({ name, base, tip, closed }) => ({ name, base, tip, closed })),
+})
+
+export const renderSlicesJson = (document: SlicesDocument): string =>
+  JSON.stringify(document) + "\n"

package/src/wire/WireSchema.test.ts

@@ -9,6 +9,8 @@ import {
   landFields,
   renderBeatJson,
   renderLandJson,
+  renderSlicesJson,
+  slicesDocument,
   statusOf,
   WIRE_SCHEMA,
   type BeatKind,
@@ -116,6 +118,9 @@ const documents: Readonly<Record<string, string>> = {
     }),
   ),
   "judge.json": JUDGE,
+  "slices.json": renderSlicesJson(
+    slicesDocument([{ name: "build", base: "a".repeat(40), tip: "b".repeat(40), closed: true }]),
+  ),
 }
 
 describe(`wire schema ${WIRE_SCHEMA}`, () => {
@@ -139,6 +144,19 @@ describe(`wire schema ${WIRE_SCHEMA}`, () => {
     }
   })
 
+  describe("slicesDocument", () => {
+    it("stamps WIRE_SCHEMA and drops any field beyond the four", () => {
+      const doc = slicesDocument([
+        { name: "n", base: "b", tip: "t", closed: false, extra: 1 } as never,
+      ])
+      expect(doc).toEqual({
+        schema: WIRE_SCHEMA,
+        slices: [{ name: "n", base: "b", tip: "t", closed: false }],
+      })
+      expect(Object.keys(doc.slices[0]!)).toEqual(["name", "base", "tip", "closed"])
+    })
+  })
+
   describe("the shape check", () => {
     const land = JSON.parse(documents["land.json"]!) as Record<string, unknown>
     const { subject, ...rest } = land

package/src/wire/golden/1/slices.json

@@ -0,0 +1,11 @@
+{
+  "schema": 1,
+  "slices": [
+    {
+      "name": "build",
+      "base": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "tip": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "closed": true
+    }
+  ]
+}

package/src/wire/index.ts

@@ -10,3 +10,4 @@ export * from "./Judge.js"
 export { selectPath } from "./Select.js"
 export { resolveSession } from "./Sessions.js"
 export { globMatches } from "./Glob.js"
+export * from "./Slices.js"