@pmelab/gtd 65.0.0 → 66.0.0

package/src/steering/review.ts

@@ -37,6 +37,7 @@ import {
 } from "./MarkdownTree.js"
 import { FREE_TEXT_PLACEHOLDER, normalizeFreeTextAnswer } from "./qa.js"
 import type {
+  SteeringAction,
   SteeringAnchor,
   SteeringAnnotateResult,
   SteeringEdit,
@@ -46,6 +47,7 @@ import type {
   SteeringOutlineNode,
   SteeringView,
   SteeringViewNode,
+  SteeringViewSection,
 } from "./SteeringFormat.js"
 
 interface ReviewFile {
@@ -55,6 +57,8 @@ interface ReviewFile {
   /** 1-based post-image end line of a `#<start>-<end>` range — `line` holds the start. Absent for a bare `#<line>` pointer or a `#`-less one. */
   readonly rangeEnd?: number
   readonly checked: boolean
+  /** A finding's location: a plain list item with no tick box. */
+  readonly plain?: boolean
   /** The pointer's explanation: same-line text (if any) first, then the lines gathered from BELOW it, joined with " ". */
   readonly note?: string
   /** `note`'s own inline structure, image-collapsed (R2) — feeds the hunk node's `detailInline`. Absent exactly where `note` is. */
@@ -68,10 +72,14 @@ interface ReviewFile {
 interface Changeset {
   readonly title: string
   readonly description: string
+  /** `description` without the drafted comment: what the view shows. */
+  readonly detail: string
   /** The same leading run collapsed into `description`, projected as block nodes (`Blocks.ts#blockNodesOfRun`) instead of flattened text — `Review.tsx`'s chunk screen renders these through the shared prose-block rendering. */
   readonly descriptionNodes: readonly SteeringViewNode[]
   /** `description`'s own inline structure, image-collapsed (R2) — feeds the chunk node's `detailInline`. */
   readonly descriptionInline: readonly InlineNode[]
+  /** The drafted PR comment (de-quoted markdown) of a decision chunk, when it carries one. */
+  readonly comment?: string
   readonly files: readonly ReviewFile[]
   /** 0-based index of this chunk's `##` heading. */
   readonly headingLine: number
@@ -375,6 +383,7 @@ const buildHunkFile = (
     ...(parsed.line !== undefined ? { line: parsed.line } : {}),
     ...(parsed.rangeEnd !== undefined ? { rangeEnd: parsed.rangeEnd } : {}),
     checked: item.checked === true,
+    ...(item.checked === null ? { plain: true } : {}),
     sourceLine,
     endLine: hunkOwnEndLine(item, sourceLine),
     ...(note.length > 0 ? { note, noteInline } : {}),
@@ -530,6 +539,31 @@ const answerListOf = (
   return { lead, list, options }
 }
 
+const COMMENT_LABEL_RE = /^(Impact|Fix):[ \t]*/
+
+/** Splits a drafted comment at its `Impact:` / `Fix:` lines (outside fences) into labelled block sections; no labels is one What. */
+const commentSections = (comment: string): readonly SteeringViewSection[] => {
+  const parts: { label: string; lines: string[] }[] = [{ label: "What", lines: [] }]
+  let fence: string | undefined
+  for (const line of comment.split("\n")) {
+    const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+    if (marker !== undefined) {
+      if (fence === undefined) fence = marker
+      else if (marker.startsWith(fence)) fence = undefined
+    }
+    const label = fence === undefined && marker === undefined ? COMMENT_LABEL_RE.exec(line) : null
+    if (label) parts.push({ label: label[1]!, lines: [line.slice(label[0].length)] })
+    else parts.at(-1)!.lines.push(line)
+  }
+  return parts
+    .map(({ label, lines }) => ({ label, text: lines.join("\n").trim() }))
+    .filter(({ text }) => text.length > 0)
+    .map(({ label, text }) => ({
+      label,
+      body: blockNodesOfRun(text, parseMarkdown(text).children),
+    }))
+}
+
 /** A leading severity line is the chunk's tier, never its prose. */
 const splitSeverity = (
   content: string,
@@ -550,17 +584,32 @@ const splitSeverity = (
   }
 }
 
+/** Every `listItem` under `node`, task or plain, at any depth. */
+const allListItems = (node: RootContent): readonly ListItem[] => {
+  const items: ListItem[] = []
+  const walk = (n: { type: string; children?: readonly unknown[] }): void => {
+    if (n.type === "listItem") items.push(n as unknown as ListItem)
+    n.children?.forEach((c) => walk(c as { type: string; children?: readonly unknown[] }))
+  }
+  walk(node)
+  return items
+}
+
 /** Splits one chunk's body nodes into its file pointers (hunk pointers are task items, collected recursively at ANY nesting depth via `taskItems` — a nested hunk is the same kind of hunk as a top-level one) and description prose. The description is the chunk's own leading run and never a node that contains a hunk pointer: it stops at the first node whose `taskItems` include a real pointer (at any depth — a blockquote wrapping a pointer list stops it just as a top-level list would). Every node kind in what's left before that point contributes — a `footnoteDefinition` is the one exception, excluded by `blockNodesOfRun` itself (it's a note, never document content). */
+// fallow-ignore-next-line complexity
 const parseChunkBody = (
   content: string,
   lines: readonly string[],
   title: string,
   body: readonly RootContent[],
   answerable: boolean,
+  finding: boolean,
 ): {
   readonly description: string
+  readonly detail: string
   readonly descriptionNodes: readonly SteeringViewNode[]
   readonly descriptionInline: readonly InlineNode[]
+  readonly comment?: string
   readonly files: readonly ReviewFile[]
   readonly errors: readonly SteeringFinding[]
   readonly answers?: readonly AnswerOption[]
@@ -573,33 +622,70 @@ const parseChunkBody = (
   const answer = answerable ? answerListOf(content, body) : undefined
   const isAnswer = (n: RootContent): boolean =>
     answer !== undefined && (n === answer.list || n === body[answer.lead])
+  const pointerItems = (n: RootContent): readonly ListItem[] =>
+    finding ? allListItems(n) : taskItems(n)
   const firstPointerIndex = body.findIndex(
-    (n) => !isAnswer(n) && taskItems(n).some((item) => hasPointerToken(content, item)),
+    (n) => !isAnswer(n) && pointerItems(n).some((item) => hasPointerToken(content, item)),
   )
   const run = (firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)).filter(
     (n) => !isAnswer(n),
   )
-  const { severity, leadingRun } = splitSeverity(content, run)
+  // The drafted comment: the blockquote right after a `Draft PR comment:` line, wherever the pointer sits.
+  const draftIndex =
+    answer !== undefined
+      ? body.findIndex(
+          (n, i) =>
+            !isAnswer(n) &&
+            n.type === "blockquote" &&
+            body[i - 1]?.type === "paragraph" &&
+            /^draft pr comment:?$/i.test(sourceText(content, body[i - 1]!).trim()),
+        )
+      : -1
+  const comment =
+    draftIndex === -1
+      ? undefined
+      : content
+          .slice(body[draftIndex]!.position!.start.offset!, body[draftIndex]!.position!.end.offset!)
+          .split("\n")
+          .map((l) => l.replace(/^\s*> ?/, ""))
+          .join("\n")
+          .trim()
+  const draftNodes = new Set(draftIndex === -1 ? [] : [body[draftIndex], body[draftIndex - 1]])
+  const { severity, leadingRun: fullRun } = splitSeverity(content, run)
+  const leadingRun = fullRun.filter((n) => !draftNodes.has(n))
   const descriptionNodes = blockNodesOfRun(content, leadingRun)
   const descriptionInline = collapseImages(blockRunInline(content, leadingRun))
-  const description = leadingRun
-    .filter((n) => n.type !== "footnoteDefinition")
-    .map((n) => sourceText(content, n))
-    .join(" ")
-    .trim()
+  const textOf = (nodes: readonly RootContent[]): string =>
+    nodes
+      .filter((n) => n.type !== "footnoteDefinition")
+      .map((n) => sourceText(content, n))
+      .join(" ")
+      .trim()
+  // `description` stays whole: it is the decision body gtd hands to the fixer.
+  const description = textOf(fullRun)
+  const detail = textOf(leadingRun)
 
   const files: ReviewFile[] = []
   const errors: SteeringFinding[] = []
-  for (const item of body.filter((n) => !isAnswer(n)).flatMap((n) => taskItems(n))) {
+  for (const item of body.filter((n) => !isAnswer(n)).flatMap((n) => pointerItems(n))) {
     const parsed = parseHunk(content, lines, title, item)
     if (!parsed) continue
+    if (finding && item.checked !== null) {
+      errors.push({
+        message: `Chunk "${title}" finding location ${pointerDisplay(parsed.file)} must be a plain list item — drop the checkbox`,
+        line: parsed.file.sourceLine,
+        range: lineRange(lines, parsed.file.sourceLine),
+      })
+    }
     files.push(parsed.file)
     errors.push(...parsed.errors)
   }
   return {
     description,
+    detail,
     descriptionNodes,
     descriptionInline,
+    ...(comment === undefined ? {} : { comment }),
     files,
     errors,
     ...(answer === undefined
@@ -690,15 +776,24 @@ const parseChangesets = (
     const title = headingText(content, heading)
     const {
       description,
+      detail,
       descriptionNodes,
       descriptionInline,
+      comment,
       files,
       answers,
       answerLine,
       severity,
       boxed,
       errors: bodyErrors,
-    } = parseChunkBody(content, lines, title, body, section !== "walkthrough")
+    } = parseChunkBody(
+      content,
+      lines,
+      title,
+      body,
+      section !== "walkthrough",
+      section === "findings",
+    )
     errors.push(...bodyErrors)
     // A prose-only chunk is a note gtd composed; a box with no pointer is a pointer gone wrong.
     if (files.length === 0 && boxed) {
@@ -711,8 +806,10 @@ const parseChangesets = (
     changesets.push({
       title,
       description,
+      detail,
       descriptionNodes,
       descriptionInline,
+      ...(comment === undefined ? {} : { comment }),
       files,
       headingLine,
       ...(answers === undefined ? {} : { answers, answerLine: answerLine! }),
@@ -878,7 +975,7 @@ const decisionNodes = (
 }
 
 const isOpenChunk = (chunk: Changeset, markers: number): boolean =>
-  chunk.files.some((file) => !file.checked) ||
+  chunk.files.some((file) => !file.plain && !file.checked) ||
   markers > 0 ||
   (chunk.answers !== undefined && decisionOf(chunk) === undefined)
 
@@ -917,7 +1014,7 @@ const reviewOutline = (content: string): readonly SteeringOutlineNode[] => {
     if (!listed && !isOpenChunk(chunk, chunkMarkers.length)) return []
     const node: SteeringOutlineNode = {
       name:
-        chunk.files.length === 0
+        chunk.files.length === 0 || chunk.section === "findings"
           ? chunk.title
           : `${chunk.title} (${checkedCount}/${chunk.files.length})`,
       range: spanRange(lines, start, end),
@@ -991,6 +1088,39 @@ const footnoteBlockEnd = (content: string, tree: Root, cursorLine: number): numb
   return block?.position ? toLspPosition(block.position.end).line : cursorLine
 }
 
+const FINDING_ACTIONS = [
+  { title: "gtd: accept finding", index: 0 },
+  { title: "gtd: reject finding", index: 1 },
+  { title: "gtd: answer finding", index: 2 },
+] as const
+
+/** Accept / reject / answer for one finding chunk; the one matching its single current tick is left out. */
+const findingActions = (
+  content: string,
+  chunk: Changeset,
+  chunkIndex: number,
+): Array<{ title: string; edits: readonly SteeringEdit[]; select?: SteeringAction["select"] }> => {
+  if (chunk.answers?.length !== 3) return []
+  const ticked = chunk.answers.flatMap((o, i) => (o.checked ? [i] : []))
+  const current = ticked.length === 1 ? ticked[0] : undefined
+  const items = answerItemsOf(content, chunkIndex)
+  return FINDING_ACTIONS.filter((a) => a.index !== current).flatMap((a) => {
+    const result = decisionEdits(content, chunkIndex, a.index, {})
+    if (!result.ok) return []
+    const slot = items[2]
+    const from = slot ? firstParagraphContentOffset(slot) : undefined
+    const to = slot?.children.find((c) => c.type === "paragraph")?.position?.end.offset
+    const select =
+      a.index === 2 && from !== undefined && to !== undefined
+        ? {
+            start: toLspPositionFromOffset(content, from),
+            end: toLspPositionFromOffset(content, to),
+          }
+        : undefined
+    return [{ title: a.title, edits: result.edits, ...(select ? { select } : {}) }]
+  })
+}
+
 /**
  * Actions for `.gtd/REVIEW.md`: "check/uncheck this hunk" when `range` sits
  * on a hunk line, "check/uncheck all hunks" when `range` sits anywhere in a
@@ -1014,7 +1144,7 @@ const reviewActions: SteeringFormat["actions"] = (content, range) => {
     const hunk = chunk.files.find(
       (file) => cursorLine >= file.sourceLine && cursorLine <= file.endLine,
     )
-    if (hunk) {
+    if (hunk && !hunk.plain) {
       const edit = toggleFilePointer(content, hunk.sourceLine)
       if (edit) {
         actions.push({
@@ -1029,7 +1159,15 @@ const reviewActions: SteeringFormat["actions"] = (content, range) => {
       chunk.section === undefined
         ? Math.max(chunk.headingLine, (changesets[i + 1]?.headingLine ?? lines.length) - 1)
         : (endLines.get(chunk.headingLine) ?? chunk.headingLine)
-    if (chunk.files.length > 0 && cursorLine >= chunk.headingLine && cursorLine <= chunkEnd) {
+    if (chunk.section === "findings" && cursorLine >= chunk.headingLine && cursorLine <= chunkEnd) {
+      actions.push(...findingActions(content, chunk, i))
+    }
+    if (
+      chunk.section !== "findings" &&
+      chunk.files.length > 0 &&
+      cursorLine >= chunk.headingLine &&
+      cursorLine <= chunkEnd
+    ) {
       const edits = toggleChunkEdits(content, chunk.headingLine)
       if (edits.length > 0) {
         const checkedCount = chunk.files.filter((file) => file.checked).length
@@ -1113,7 +1251,10 @@ const reviewDocumentLinks = (content: string): readonly SteeringLink[] => {
   const tree = parseMarkdown(content)
   const links: SteeringLink[] = []
   for (const block of splitChunks(tree, content).chunks) {
-    for (const item of block.body.flatMap((n) => taskItems(n))) {
+    const items = block.body.flatMap((n) =>
+      block.section === "findings" ? allListItems(n) : taskItems(n),
+    )
+    for (const item of items) {
       const link = hunkLinkFor(content, item)
       if (link) links.push(link)
     }
@@ -1129,9 +1270,10 @@ const reviewView = (content: string): SteeringView => {
     ...(shortHash ? { header: shortHash } : {}),
     nodes: changesets.map((chunk, chunkIndex) => ({
       title: chunk.title,
-      detail: chunk.description,
+      detail: chunk.detail,
       detailInline: chunk.descriptionInline,
       body: chunk.descriptionNodes,
+      ...(chunk.comment === undefined ? {} : { comment: commentSections(chunk.comment) }),
       ...(chunk.severity === undefined ? {} : { status: chunk.severity.label }),
       anchor: { kind: "chunk", index: chunkIndex },
       ...(chunk.section === undefined ? {} : { group: REVIEW_SECTIONS[chunk.section] }),
@@ -1151,7 +1293,7 @@ const reviewView = (content: string): SteeringView => {
         path: file.path,
         ...(file.line !== undefined ? { line: file.line } : {}),
         ...(file.rangeEnd !== undefined ? { endLine: file.rangeEnd } : {}),
-        checked: file.checked,
+        ...(file.plain ? {} : { checked: file.checked }),
         ...(file.note !== undefined
           ? { detail: file.note, detailInline: file.noteInline ?? [] }
           : {}),
@@ -1339,12 +1481,12 @@ const reviewApply: SteeringFormat["apply"] = (content, anchor, opts) => {
   const checked = opts.checked ?? true
   if (anchor.kind === "hunk") {
     const file = changesets[anchor.chunkIndex]?.files[anchor.index]
-    if (!file) return { ok: false, reason: "anchor-not-found" }
+    if (!file || file.plain) return { ok: false, reason: "anchor-not-found" }
     return { ok: true, edits: setFileTickEdits(content, [file], checked) }
   }
   if (anchor.kind === "chunk") {
     const chunk = changesets[anchor.index]
-    if (!chunk) return { ok: false, reason: "anchor-not-found" }
+    if (!chunk || chunk.section === "findings") return { ok: false, reason: "anchor-not-found" }
     return { ok: true, edits: setFileTickEdits(content, chunk.files, checked) }
   }
   return { ok: false, reason: "anchor-not-found" }

package/src/step/RepoSnapshot.ts

@@ -28,10 +28,14 @@ export type Landing =
       readonly pushHistory?: string
       /** A ship step's squash onto the user's branch, made ahead of the landing commit. */
       readonly ship?: ShipSpec
+      /** The history ref of a landing that only records an earlier ship (`ship` is unset). */
+      readonly recordedHistory?: string
       /** Printed after the landing: why a ship step shipped nothing. */
       readonly note?: string
       /** The one path this landing commits; every other pending change stays pending. */
       readonly only?: string
+      /** Review-gate landing into an agent turn: the human's ticks are committed. */
+      readonly keepTicks?: boolean
     }
 
 /**

package/src/step/planStep.ts

@@ -24,11 +24,11 @@ export type StepOutcome =
     }
 
 /**
- * At the human review gate an unconditional `gtd uncheck '<file>'` runs
- * ahead of the commit, resetting every checkbox before `git add -A` picks it
- * up — a tick is read-progress, never sign-off.
+ * Clear ticks at the human review gate, a tick is read-progress. Keep them when
+ * the next step is an agent turn: the agent reads them.
  */
-const uncheckStep = (snapshot: RepoSnapshot): readonly LandStep[] =>
+const uncheckStep = (snapshot: RepoSnapshot, keepTicks: boolean): readonly LandStep[] =>
+  !keepTicks &&
   snapshot.stepDef.actor === "human" &&
   snapshot.stepDef.mode === "review" &&
   snapshot.file !== undefined
@@ -82,7 +82,7 @@ export const planStep = (
     ...(opts.judge !== undefined && opts.judge.length > 0 ? { judge: opts.judge } : {}),
   })
   const subject = message.split("\n")[0]!
-  const historyRef = landing.keepHistory ?? landing.ship?.historyRef
+  const historyRef = landing.keepHistory ?? landing.ship?.historyRef ?? landing.recordedHistory
   const outcome: LandStep =
     landing.to === snapshot.state
       ? { kind: "outcome", outcome: { kind: "commit", subject } }
@@ -94,7 +94,7 @@ export const planStep = (
     subject,
     steps: [
       ...writeIf(landing.startBranch, (branch) => ({ kind: "switchBranch", branch })),
-      ...uncheckStep(snapshot),
+      ...uncheckStep(snapshot, landing.keepTicks === true),
       { kind: "gitWrite", write: gitWriteOf(landing, message) },
       ...writeIf(historyRef, (ref) => ({ kind: "updateRef", ref, target: "HEAD" })),
       ...writeIf(landing.leaveBranch, (branch) => ({ kind: "switchTo", branch })),

package/src/twins/EmittedScriptRecognizer.ts

@@ -681,7 +681,7 @@ const recognizeGtdCheck = (repo: InMemRepo, block: string): BlockOutcome | undef
 
 const GTD_UNCHECK_RE = /^gtd uncheck (.+)$/
 
-/** `gtd uncheck <file>` — the review-gate reset prepended ahead of the human's commit, so no tick ever reaches it. Re-runs the REAL `clearTicks`, writing back only on an actual change. */
+/** `gtd uncheck <file>` — the review-gate reset prepended ahead of the human's commit, absent when the next step is an agent turn. Re-runs the REAL `clearTicks`, writing back only on an actual change. */
 const recognizeGtdUncheck = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   const match = GTD_UNCHECK_RE.exec(block)
   if (!match) return undefined

package/src/twins/InMemRepo.ts

@@ -27,6 +27,11 @@ function makeHash(message: string, parent: string | null, tree: Map<string, stri
   return sha1(`${message}\n${parent ?? "null"}\n${treeStr}`)
 }
 
+/** An executable file's content carries this prefix inside the twin, so every tree copy keeps the mode for free; only the read edges strip it. */
+const EXEC = "\u0000exec\u0000"
+const plain = (content: string): string =>
+  content.startsWith(EXEC) ? content.slice(EXEC.length) : content
+
 export class InMemRepo {
   // Data-only marker read by no code path: embeds the sentinel in every
   // instance so a leaked object still carries it.
@@ -367,7 +372,8 @@ export class InMemRepo {
     if (!hash) return null
     const c = this.getCommit(hash)
     if (!c) return null
-    return c.files.get(path) ?? null
+    const content = c.files.get(path)
+    return content === undefined ? null : plain(content)
   }
 
   /**
@@ -400,7 +406,20 @@ export class InMemRepo {
 
   /** The worktree content of `path`, or `undefined` when absent. A LIVE read — never a snapshot. */
   readFile(path: string): string | undefined {
-    return this.worktree.get(path)
+    const content = this.worktree.get(path)
+    return content === undefined ? undefined : plain(content)
+  }
+
+  /** `chmod +x` / `-x` on a working-tree file. */
+  setExecutable(path: string, on: boolean): void {
+    const content = this.readFile(path)
+    if (content !== undefined) this.worktree.set(path, on ? EXEC + content : content)
+  }
+
+  /** Every path's file mode at `ref`, or in the working tree when `ref` is `undefined`. */
+  modesAt(ref: string | undefined): Map<string, string> {
+    const tree = ref === undefined ? this.worktree : this.treeAt(ref)
+    return new Map([...tree].map(([path, c]) => [path, c.startsWith(EXEC) ? "100755" : "100644"]))
   }
 
   /** True when `path` is exactly a worktree file, or a directory prefix of one (any worktree key starts with `path/`). */
@@ -673,7 +692,9 @@ export class InMemRepo {
   }
 
   writeFile(path: string, content: string): void {
-    this.worktree.set(path, content)
+    // A live overwrite keeps the mode.
+    const was = this.worktree.get(path)
+    this.worktree.set(path, was?.startsWith(EXEC) ? EXEC + content : content)
   }
 
   deleteFile(path: string): void {

package/src/twins/Layers.ts

@@ -119,6 +119,7 @@ export const makeInMemoryWorkspaceOps = (repo: InMemRepo, root: string): Workspa
       Effect.succeed(
         new Map([...(base !== undefined ? [base] : []), ...commits].map((h) => [h, treeOf(h)])),
       ),
+    modeSync: (ref) => repo.modesAt(ref),
     worktreeSync: () =>
       new Map(
         repo

package/src/twins/SyncIo.test.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process"
-import { mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs"
+import { chmodSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { afterEach, describe, expect, it } from "vitest"
@@ -12,6 +12,7 @@ interface Tier {
   readonly root: string
   readonly uid: number | undefined
   readonly symlink: (path: string, target: string) => void
+  readonly chmod: (path: string, executable: boolean) => void
   /** Commits `files`, repository-relative, as the only change. */
   readonly commit: (files: Record<string, string>) => void
 }
@@ -29,6 +30,7 @@ const liveTier = (): Tier => {
     root,
     uid: process.getuid?.(),
     symlink: (path, target) => symlinkSync(target, path),
+    chmod: (path, executable) => chmodSync(path, executable ? 0o755 : 0o644),
     commit: (files) => {
       for (const [path, content] of Object.entries(files))
         nodeSyncIo.writeText(join(root, path), content)
@@ -48,6 +50,7 @@ const inMemTier = (): Tier => {
     root,
     uid: 501,
     symlink: io.symlink,
+    chmod: io.setExecutable,
     commit: (files) => {
       for (const [path, content] of Object.entries(files)) {
         io.writeText(`${root}/${path}`, content)
@@ -106,9 +109,9 @@ describe.each([
     symlink(`${root}/link`, "dir")
     symlink(`${root}/dangling`, "nowhere")
 
-    expect(io.stat(`${root}/dir/f`)).toEqual({ type: "file", uid })
-    expect(io.stat(`${root}/link`)).toEqual({ type: "directory", uid })
-    expect(io.lstat(`${root}/link`)).toEqual({ type: "symlink", uid })
+    expect(io.stat(`${root}/dir/f`)).toMatchObject({ type: "file", uid })
+    expect(io.stat(`${root}/link`)).toMatchObject({ type: "directory", uid })
+    expect(io.lstat(`${root}/link`)).toMatchObject({ type: "symlink", uid })
     expect(io.lstat(`${root}/missing`)).toBeUndefined()
     expect(io.stat(`${root}/dangling`)).toBeUndefined()
     expect(io.readLink(`${root}/link`)).toBe("dir")
@@ -117,6 +120,18 @@ describe.each([
     expect(() => io.realPath(`${root}/dangling`)).toThrow()
   })
 
+  it("reports the executable bit of files, kept across an overwrite", () => {
+    const { io, root, chmod } = makeTier()
+    io.writeText(`${root}/f`, "x")
+    expect(io.stat(`${root}/f`)?.executable).toBe(false)
+    chmod(`${root}/f`, true)
+    expect(io.stat(`${root}/f`)?.executable).toBe(true)
+    io.writeText(`${root}/f`, "y")
+    expect(io.lstat(`${root}/f`)?.executable).toBe(true)
+    chmod(`${root}/f`, false)
+    expect(io.stat(`${root}/f`)?.executable).toBe(false)
+  })
+
   it("reads committed content through git", () => {
     const { io, root, commit } = makeTier()
     commit({ "a.txt": "committed\n" })

package/src/twins/SyncIo.ts

@@ -15,6 +15,8 @@ const decoder = new TextDecoder("utf-8", { ignoreBOM: true })
 
 export interface InMemorySyncIo extends SyncIo {
   readonly symlink: (path: string, target: string) => void
+  /** `chmod +x` / `-x` on a file. */
+  readonly setExecutable: (path: string, on: boolean) => void
 }
 
 /**
@@ -27,6 +29,7 @@ export const inMemorySyncIo = (
   const files = new Map<string, Uint8Array>()
   const links = new Map<string, string>()
   const dirs = new Set<string>(["/"])
+  const execs = new Set<string>()
 
   /** `path` with every symlink resolved, the last component's only when `followLast`. */
   const resolve = (path: string, followLast: boolean): string => {
@@ -68,7 +71,9 @@ export const inMemorySyncIo = (
 
   const info = (path: string): FileInfo | undefined => {
     const type = typeOf(path)
-    return type === undefined ? undefined : { type, uid: opts.uid }
+    return type === undefined
+      ? undefined
+      : { type, uid: opts.uid, ...(type === "file" ? { executable: execs.has(path) } : {}) }
   }
 
   const readFile = (path: string): Uint8Array | undefined => {
@@ -136,6 +141,8 @@ export const inMemorySyncIo = (
       links.delete(target)
       files.set(target, bytes)
       files.delete(source)
+      execs.delete(target)
+      if (execs.delete(source)) execs.add(target)
     },
     stat: (path) => info(resolve(path, true)),
     lstat: (path) => info(resolve(path, false)),
@@ -152,6 +159,11 @@ export const inMemorySyncIo = (
     git,
     gitBytes: (cwd, args) => encoder.encode(git(cwd, args)),
     hash: pureHash,
+    setExecutable: (path, on) => {
+      const real = resolve(path, true)
+      if (on) execs.add(real)
+      else execs.delete(real)
+    },
     symlink: (path, target) => {
       links.set(resolve(path, false), target)
     },

package/src/wire/BeatDocument.test.ts

@@ -31,6 +31,7 @@ interface DocumentInput {
   readonly log?: string
   readonly session?: { readonly id: string; readonly resume: boolean }
   readonly validate?: string
+  readonly fresh?: string | null
   readonly changes?: readonly StatusChange[]
   readonly next?: NextMatch | null
   readonly cost?: number
@@ -47,6 +48,7 @@ const demandInput = (
   kind: input.kind,
   ...(input.session !== undefined ? { session: input.session } : {}),
   ...(input.validate !== undefined ? { validate: input.validate } : {}),
+  ...(input.fresh !== undefined ? { fresh: input.fresh } : {}),
 })
 
 /** `statusOf`'s own input, isolated for the same reason as `demandInput` above. */
@@ -84,6 +86,7 @@ describe("beatDocument / renderBeatJson", () => {
       content: "fix it",
       idle: false,
       initial: false,
+      fresh: null,
       log: ".git/gtd-loop.log",
       state: "build.fixing",
       actor: "agent",
@@ -138,6 +141,16 @@ describe("beatDocument / renderBeatJson", () => {
     expect(parsed.validate).toBe("gtd check qa 'TODO.md'")
   })
 
+  it("carries fresh at kind prompt and null at every other kind", () => {
+    const parsed = JSON.parse(renderJsonLine({ kind: "prompt", fresh: "p\n\nc" })) as {
+      fresh: unknown
+    }
+    expect(parsed.fresh).toBe("p\n\nc")
+    for (const kind of BEAT_KINDS.filter((k) => k !== "prompt")) {
+      expect((JSON.parse(renderJsonLine({ kind })) as { fresh: unknown }).fresh).toBeNull()
+    }
+  })
+
   it("omits session/validate at kind prompt when the caller supplied none, never emitting null", () => {
     const line = renderJsonLine({ kind: "prompt" })
     const parsed = JSON.parse(line) as Record<string, unknown>
@@ -256,6 +269,7 @@ describe("beatDocument / renderBeatJson", () => {
       "model",
       "system",
       "validate",
+      "fresh",
       "log",
       "state",
       "actor",
@@ -395,6 +409,7 @@ describe("golden bytes", () => {
         content: "fix it",
         idle: false,
         initial: false,
+        fresh: null,
         log: ".git/gtd-loop.log",
         state: "build.fixing",
         actor: "agent",