@pmelab/gtd 64.2.0 → 65.0.0

package/src/twins/EmittedScriptRecognizer.ts

@@ -13,6 +13,12 @@ import {
   hardResetTo,
   keepTurn,
   mixedResetTo,
+  switchBranchTo,
+  switchBack,
+  switchTo,
+  deleteBranch,
+  pushRef,
+  shipCommit,
   shellQuote,
   softResetTo,
   updateRef,
@@ -26,6 +32,7 @@ import {
   modeContradictionSkipNotice,
   OUTCOME_MARKER,
   pinScript,
+  failRestScript,
   repinScript,
   unpinScript,
 } from "../emit/index.js"
@@ -161,6 +168,19 @@ const recognizeKeepTurn = (repo: InMemRepo, block: string): BlockOutcome | undef
   return failure === undefined ? { kind: "applied" } : { kind: "failed", error: failure, status: 1 }
 }
 
+const attempt = (apply: () => void): BlockOutcome => {
+  try {
+    apply()
+    return { kind: "applied" }
+  } catch (e) {
+    return {
+      kind: "failed",
+      error: `fatal: ${e instanceof Error ? e.message : String(e)}`,
+      status: 128,
+    }
+  }
+}
+
 // fallow-ignore-next-line complexity
 const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   if (block === discardPending()) {
@@ -250,6 +270,73 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
     return undefined
   }
 
+  if (block.startsWith("git switch -q -C ")) {
+    const [branch, start] = extractQuotedTokens(block)
+    if (branch !== undefined && switchBranchTo(branch, start) === block) {
+      return attempt(() => repo.switchBranchTo(branch, start))
+    }
+    return undefined
+  }
+
+  if (block.startsWith("if ! git switch -q ")) {
+    const [branch, , note] = extractQuotedTokens(block)
+    if (branch !== undefined && switchBack(branch) === block) {
+      try {
+        repo.switchTo(branch)
+        return { kind: "applied" }
+      } catch {
+        return { kind: "noop", output: `${note}\n` }
+      }
+    }
+    return undefined
+  }
+
+  if (block.startsWith("git switch -q ")) {
+    const [branch] = extractQuotedTokens(block)
+    if (branch !== undefined && switchTo(branch) === block) {
+      return attempt(() => repo.switchTo(branch))
+    }
+    return undefined
+  }
+
+  if (block.startsWith("git branch -q -D ")) {
+    const [branch] = extractQuotedTokens(block)
+    if (branch !== undefined && deleteBranch(branch) === block) {
+      return attempt(() => repo.deleteBranch(branch))
+    }
+    return undefined
+  }
+
+  if (block.startsWith("if ! git push --force ")) {
+    const [remote, refspec] = extractQuotedTokens(block)
+    const ref = refspec?.split(":")[0]
+    if (remote !== undefined && ref !== undefined && pushRef(remote, ref) === block) {
+      const failure = repo.pushRef(remote, ref)
+      if (failure === undefined) return { kind: "applied" }
+      const retry = extractQuotedTokens(block)[3]!
+      return { kind: "failed", error: `${failure}\n${retry}`, status: 1 }
+    }
+    return undefined
+  }
+
+  if (block.startsWith("gtd_ship_parent=")) {
+    const [parent, branch, history, shipMessage, message] = extractQuotedTokens(block)
+    if (
+      parent === undefined ||
+      branch === undefined ||
+      history === undefined ||
+      shipMessage === undefined ||
+      message === undefined ||
+      shipCommit(branch, parent, shipMessage, history, message) !== block
+    ) {
+      return undefined
+    }
+    const failure = repo.shipCommit(branch, parent, shipMessage, history, message)
+    return failure === undefined
+      ? { kind: "applied" }
+      : { kind: "failed", error: failure, status: 1 }
+  }
+
   if (block.startsWith("git update-ref -d ")) {
     const [ref] = extractQuotedTokens(block)
     if (ref !== undefined && deleteRef(ref) === block) {
@@ -375,6 +462,35 @@ const recognizeModeCommand = (
   return recognizeScriptedCommand(repo, new Map([[command, bound]]), command)
 }
 
+const FAIL_REST_MIDDLE = '\n} 2>&1 )" || gtd_run_status=$?\n'
+
+/** A `run(…, { onFail: "rest" })` body: the inner script's failure is recorded in the tree and the block itself succeeds. */
+// fallow-ignore-next-line complexity
+const recognizeFailRest = (
+  repo: InMemRepo,
+  commands: CommandTable,
+  block: string,
+): BlockOutcome | undefined => {
+  if (!block.startsWith("rm -f -- '") || !block.includes("gtd_run_out=")) return undefined
+  const [path] = extractQuotedTokens(block)
+  const headerEnd = block.indexOf('gtd_run_out="$( {\n')
+  const bodyEnd = block.indexOf(FAIL_REST_MIDDLE)
+  if (path === undefined || headerEnd === -1 || bodyEnd === -1) return undefined
+  const body = block.slice(headerEnd + 'gtd_run_out="$( {\n'.length, bodyEnd)
+  if (failRestScript(body, path) !== block) return undefined
+  if (repo.readFile(path) !== undefined) repo.deleteFile(path)
+  const result = applyEmittedScript(repo, commands, body)
+  if (!result.ok && result.error?.startsWith(UNRECOGNIZED_PREFIX)) {
+    return { kind: "failed", error: `${result.output}${result.error}` }
+  }
+  if (!result.ok) {
+    // Mirrors `$(…)` (strips trailing newlines) and the script's `tail -n 50`.
+    const lines = result.output.replace(/\n+$/, "").split("\n")
+    repo.writeFile(path, `exit ${result.status}\n${lines.slice(-50).join("\n")}\n`)
+  }
+  return { kind: "noop", output: result.output }
+}
+
 const FAILURE_PROMPT_HEADER = 'gtd_validate_status=0\ngtd_validate_out="$( {\n'
 const FAILURE_PROMPT_MIDDLE =
   '\n} 2>&1 )" || gtd_validate_status=$?\n' +
@@ -728,6 +844,7 @@ const recognizersFor = (
   (block) => (git ? recognizeGitBuilders(repo, block) : undefined),
   (block) => recognizeWriteLines(repo, block),
   (block) => recognizePinScripts(repo, block),
+  (block) => recognizeFailRest(repo, commands, block),
   (block) => recognizeFailurePromptWrapper(repo, commands, block),
   (block) => recognizePresentationSubshell(repo, commands, block, git),
   (block) => recognizeModeContradictionSkipNotice(block),

package/src/twins/EmittedScripts.test.ts

@@ -5,15 +5,20 @@ import {
   combinedScript,
   commitAll,
   commitAsIs,
+  deleteBranch,
   emitScripts,
+  failRestScript,
   failurePromptWrapper,
   fileExistsGuard,
   modeContradictionSkipNotice,
+  switchBranchTo,
+  switchBack,
+  switchTo,
   transitionOutcome,
   withFileVar,
   type EmitStep,
 } from "../emit/index.js"
-import { Effect } from "effect"
+import { Effect, Option } from "effect"
 import { ScriptSurface } from "../emit/index.js"
 import { GitService } from "../platform/index.js"
 import { listFormat } from "../steering/index.js"
@@ -305,6 +310,147 @@ printf '%s\n' 'a' '' 'it'\''s' '100%' '-x' 'a\b' '.gtd/packages/00-x.md' > '.gtd
       )
     })
 
+    describe("branch scripts", () => {
+      it("switchBranchTo creates the branch at HEAD and moves onto it", () => {
+        const head = t.observe.resolveRef("HEAD")
+        expect(run(switchBranchTo("gtd/x")).ok).toBe(true)
+        expect(t.observe.resolveRef("gtd/x")).toBe(head)
+        t.seed.writeFile("a.txt", "a\n")
+        expect(run(commitAll("gtd(agent): building")).ok).toBe(true)
+        expect(t.observe.resolveRef("gtd/x")).toBe(t.observe.resolveRef("HEAD"))
+        expect(t.observe.resolveRef("gtd/x")).not.toBe(head)
+      })
+
+      it("switchTo moves onto an existing branch and fails for a missing one", () => {
+        expect(run(switchBranchTo("gtd/x")).ok).toBe(true)
+        expect(run(switchTo("nope")).ok).toBe(false)
+        expect(run(switchBranchTo("gtd/y")).ok).toBe(true)
+        expect(run(switchTo("gtd/x")).ok).toBe(true)
+      })
+
+      const branch = () =>
+        t.provide(Effect.flatMap(GitService, (g) => g.currentBranch())).then(Option.getOrUndefined)
+
+      it("switchBack carries a change to a path both branches agree on", async () => {
+        expect(run(switchBranchTo("gtd/x")).ok).toBe(true)
+        t.seed.commit("feat: on gtd/x", { "b.txt": "b\n" })
+        expect(run(switchBranchTo("x", "HEAD~1")).ok).toBe(true)
+        expect(run(switchTo("gtd/x")).ok).toBe(true)
+        t.seed.writeFile("a.txt", "changed\n")
+        const result = run(switchBack("x"))
+        expect(result.ok).toBe(true)
+        expect(result.output).toBe("")
+        expect(await branch()).toBe("x")
+        expect(read("a.txt")).toBe("changed\n")
+        expect(read("b.txt")).toBeUndefined()
+      })
+
+      it("switchBack stays put, saying so, when a change would be overwritten", async () => {
+        expect(run(switchBranchTo("gtd/x")).ok).toBe(true)
+        t.seed.commit("feat: on gtd/x", { "b.txt": "b\n" })
+        expect(run(switchBranchTo("x", "HEAD~1")).ok).toBe(true)
+        expect(run(switchTo("gtd/x")).ok).toBe(true)
+        t.seed.writeFile("b.txt", "changed\n")
+        const result = run(switchBack("x"))
+        expect(result.ok).toBe(true)
+        expect(result.output).toContain("pending changes keep HEAD off x")
+        expect(await branch()).toBe("gtd/x")
+        expect(read("b.txt")).toBe("changed\n")
+      })
+
+      it("deleteBranch removes another branch and refuses the checked-out one", () => {
+        expect(run(switchBranchTo("gtd/x")).ok).toBe(true)
+        expect(run(deleteBranch("gtd/x")).ok).toBe(false)
+        expect(run(switchBranchTo("gtd/y")).ok).toBe(true)
+        expect(run(deleteBranch("gtd/x")).ok).toBe(true)
+        expect(t.observe.refExists("refs/heads/gtd/x")).toBe(false)
+      })
+    })
+
+    describe("shipCommit", () => {
+      const HISTORY = "refs/gtd/history/0123456789012345678901234567890123456789"
+      const LANDING = "gtd(check): shipping → after\n\nGtd-Format: 4"
+      const git = <A>(f: (g: GitService["Service"]) => Effect.Effect<A, Error>) =>
+        t.provide(Effect.flatMap(GitService, f))
+      // As a landing renders it: under `set -eu`.
+      const ship = (branch: string, parent: string, shipMessage: string) =>
+        ScriptSurface.render([
+          {
+            kind: "gitWrite",
+            write: {
+              kind: "ship",
+              branch,
+              parent,
+              shipMessage,
+              historyRef: HISTORY,
+              message: LANDING,
+            },
+          },
+        ])
+
+      it("squashes the staged tree minus .gtd/ onto the branch, then lands naming it", async () => {
+        const branch = await git((g) => g.currentBranch())
+        const user = Option.getOrElse(branch, () => "main")
+        const parent = t.observe.resolveRef("HEAD")
+        expect(run(switchBranchTo(`gtd/${user}`)).ok).toBe(true)
+        t.seed.writeFile("a.txt", "shipped\n")
+        t.seed.writeFile(".gtd/notes.md", "kept back\n")
+        const result = run(ship(user, parent, "feat: it's shipped"))
+        expect(result.ok).toBe(true)
+        const shipped = t.observe.resolveRef(user)
+        expect(shipped).not.toBe(parent)
+        expect(t.observe.resolveRef(`${shipped}~1`)).toBe(parent)
+        expect(await git((g) => g.readFileAtRef(shipped, "a.txt"))).toBe("shipped\n")
+        expect(await git((g) => g.diffPaths(parent, shipped))).toEqual(["a.txt"])
+        const message = await git((g) => g.lastCommitMessage(shipped))
+        expect(message).toContain("feat: it's shipped")
+        expect(message).toContain(`\n\nGtd-History: ${HISTORY}\nGtd-Tip: ${parent}`)
+        expect(await git((g) => g.lastCommitMessage("HEAD"))).toContain(`Gtd-Shipped: ${shipped}`)
+        expect(t.observe.statusPorcelain()).toBe("")
+      })
+
+      it("keeps the .gtd/ files the branch tracks as it has them", async () => {
+        const user = Option.getOrElse(await git((g) => g.currentBranch()), () => "main")
+        t.seed.commit("chore: track", { ".gtd/keep.md": "tracked\n" })
+        const parent = t.observe.resolveRef("HEAD")
+        expect(run(switchBranchTo(`gtd/${user}`)).ok).toBe(true)
+        t.seed.writeFile("a.txt", "shipped\n")
+        t.seed.writeFile(".gtd/keep.md", "process\n")
+        expect(run(ship(user, parent, "feat: x")).ok).toBe(true)
+        const shipped = t.observe.resolveRef(user)
+        expect(await git((g) => g.readFileAtRef(shipped, ".gtd/keep.md"))).toBe("tracked\n")
+        expect(await git((g) => g.diffPaths(parent, shipped))).toEqual(["a.txt"])
+      })
+
+      it("fails before landing when the branch moved since the decision", () => {
+        const head = t.observe.resolveRef("HEAD")
+        expect(run(switchBranchTo("gtd/x")).ok).toBe(true)
+        expect(run(switchBranchTo("x")).ok).toBe(true)
+        t.seed.commit("feat: moved", { "b.txt": "b\n" })
+        expect(run(switchTo("gtd/x")).ok).toBe(true)
+        t.seed.writeFile("a.txt", "a\n")
+        expect(run(ship("x", head, "feat: x")).ok).toBe(false)
+        expect(t.observe.resolveRef("HEAD")).toBe(head)
+      })
+    })
+
+    describe("failRestScript", () => {
+      const FAIL_PATH = ".gtd/run-failed.txt"
+      const wrapped = (body: string) => failRestScript(body, FAIL_PATH)
+
+      it("records the status and output, without the output's trailing newline, and succeeds", () => {
+        expect(run(wrapped(withFileVar(FAILING, FILE))).ok).toBe(true)
+        expect(read(FAIL_PATH)).toBe(`exit 2\nbad: ${FILE}\n`)
+      })
+
+      it("leaves no record when the body passes, and clears an earlier one", () => {
+        t.seed.writeFile(FAIL_PATH, "exit 1\nold\n")
+        t.seed.writeFile(FILE, "a\n")
+        expect(run(wrapped(withFileVar(COPY, FILE))).ok).toBe(true)
+        expect(read(FAIL_PATH)).toBeUndefined()
+      })
+    })
+
     describe("commitAll", () => {
       it("a staging hook's edit lands in the commit", () => {
         t.seed.stagingHook("readme.txt", "hooked")

package/src/twins/InMemRepo.ts

@@ -180,6 +180,89 @@ export class InMemRepo {
     this.index = new Map(tree)
   }
 
+  /** `git switch -C <name> [<start>]`: pending changes ride along only when the tip's tree is unchanged. */
+  switchBranchTo(name: string, start?: string): void {
+    const hash = start === undefined ? this.head : this.resolveRef(start)
+    if (hash === null) throw new Error(`invalid reference: ${start ?? "HEAD"}`)
+    this.moveToBranch(name, hash, true)
+  }
+
+  /** `git switch <name>`: a pending change rides along when its path is the same in both trees. */
+  switchTo(name: string): void {
+    const hash = this.branches.get(name)
+    if (hash === undefined) throw new Error(`invalid reference: ${name}`)
+    if (hash === this.head) return this.moveToBranch(name, hash, false)
+    const from = this.headTree()
+    const to = this.getCommit(hash)?.files ?? new Map<string, string>()
+    const pending = [
+      ...new Set([...from.keys(), ...this.index.keys(), ...this.worktree.keys()]),
+    ].filter(
+      (path) =>
+        this.index.get(path) !== from.get(path) || this.worktree.get(path) !== from.get(path),
+    )
+    if (pending.some((path) => to.get(path) !== from.get(path))) {
+      throw new Error(`cannot switch to '${name}': local changes would be overwritten`)
+    }
+    const carry = (side: Map<string, string>) => {
+      const out = new Map(to)
+      for (const path of pending) {
+        const content = side.get(path)
+        if (content === undefined) out.delete(path)
+        else out.set(path, content)
+      }
+      return out
+    }
+    this.worktree = carry(this.worktree)
+    this.index = carry(this.index)
+    this.head = hash
+    this.currentBranch = name
+  }
+
+  private moveToBranch(name: string, hash: string, reset: boolean): void {
+    if (hash !== this.head) {
+      if (this.statusPorcelain().trim() !== "") {
+        throw new Error(`cannot switch to '${name}': the working tree has uncommitted changes`)
+      }
+      const tree = this.getCommit(hash)?.files ?? new Map<string, string>()
+      this.head = hash
+      this.worktree = new Map(tree)
+      this.index = new Map(tree)
+    }
+    if (reset || !this.branches.has(name)) this.branches.set(name, hash)
+    this.currentBranch = name
+  }
+
+  deleteBranch(name: string): void {
+    if (name === this.currentBranch) throw new Error(`cannot delete branch '${name}' checked out`)
+    if (!this.branches.delete(name)) throw new Error(`branch '${name}' not found`)
+  }
+
+  private remotes: Map<string, Map<string, string>> = new Map()
+
+  /** Test setup: a remote that accepts pushes. */
+  // fallow-ignore-next-line unused-class-member
+  addRemote(name: string): void {
+    this.remotes.set(name, new Map())
+  }
+
+  /** What a remote holds after pushes: ref → hash. */
+  // fallow-ignore-next-line unused-class-member
+  remoteRefs(name: string): ReadonlyMap<string, string> {
+    return this.remotes.get(name) ?? new Map()
+  }
+
+  /** `git push --force <remote> <ref>:<ref>`; returns git's complaint, or `undefined`. */
+  pushRef(remote: string, ref: string): string | undefined {
+    const there = this.remotes.get(remote)
+    if (there === undefined) {
+      return `fatal: '${remote}' does not appear to be a git repository`
+    }
+    const hash = this.resolveRef(ref)
+    if (hash === null) return `error: src refspec ${ref} does not match any`
+    there.set(ref, hash)
+    return undefined
+  }
+
   /** Refs under `prefix`, newest tip first; the commit sequence number stands in for the committer date. */
   listRefs(prefix: string): Array<{ ref: string; hash: string; date: string }> {
     return [...this.refs.entries()]
@@ -473,6 +556,39 @@ export class InMemRepo {
     return undefined
   }
 
+  /** Twin of `GitScript.shipCommit`: the staged tree, with `.gtd/` as `branch` has it, onto `branch`, then the landing commit naming it. */
+  shipCommit(
+    branch: string,
+    parent: string,
+    shipMessage: string,
+    historyRef: string,
+    message: string,
+  ): string | undefined {
+    this.stageAll()
+    if (this.head === null) return "fatal: Needed a single revision"
+    if (this.signingFails) return "error: gpg failed to sign the data"
+    const kept = [...(this.commits.get(parent)?.files ?? [])]
+    const tree = new Map([
+      ...[...this.index].filter(([path]) => !path.startsWith(".gtd/")),
+      ...kept.filter(([path]) => path.startsWith(".gtd/")),
+    ])
+    const shipped = `${shipMessage}\n\nGtd-History: ${historyRef}\nGtd-Tip: ${this.head}\n`
+    const hash = makeHash(shipped, parent, tree)
+    if (this.branches.get(branch) !== parent) {
+      return `fatal: update_ref failed for ref 'refs/heads/${branch}': cannot lock ref 'refs/heads/${branch}': is at ${this.branches.get(branch) ?? "nothing"} but expected ${parent}`
+    }
+    this.commits.set(hash, {
+      hash,
+      message: shipped,
+      files: tree,
+      parent,
+      seq: this.nextSeq++,
+      signed: this.signingEnabled,
+    })
+    this.branches.set(branch, hash)
+    return this.commitAsIs(`${message}\nGtd-Shipped: ${hash}`)
+  }
+
   /** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
   discardPending(): void {
     this.index = new Map(this.worktree)

package/src/wire/Demand.ts

@@ -54,14 +54,24 @@ export const beatKindOf = (input: {
  * `stalled at "<state>"` stays a stable substring (see
  * `tests/integration/features/driver-doc.feature`).
  */
-export const stallDiagnosis = (state: StateName, actor: Actor): string =>
-  `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty ` +
-  `attempt, the tree is clean, and another dispatch would repeat it.\n\n` +
-  `Two ways out:\n` +
-  `  - sharpen the step's prompt so the turn has something concrete to author\n` +
-  `  - pass allowEmpty: true to the step, so an empty turn completes it and the\n` +
-  `    flow decides what follows — finishing, or an escalation step after N\n` +
-  `    empty turns\n`
+export const stallDiagnosis = (
+  state: StateName,
+  actor: Actor,
+  failure?: string,
+  blocked?: string,
+): string =>
+  blocked !== undefined
+    ? `stalled at "${state}": landing this ship step is refused.\n\n${blocked}\n`
+    : failure !== undefined
+      ? `stalled at "${state}": the script exited non-zero and its failure is recorded in the tree. ` +
+        `Change the tree to run the script again; the step advances only on a zero exit.\n\n${failure}`
+      : `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty ` +
+        `attempt, the tree is clean, and another dispatch would repeat it.\n\n` +
+        `Two ways out:\n` +
+        `  - sharpen the step's prompt so the turn has something concrete to author\n` +
+        `  - pass allowEmpty: true to the step, so an empty turn completes it and the\n` +
+        `    flow decides what follows — finishing, or an escalation step after N\n` +
+        `    empty turns\n`
 
 /** One dispatch session — `resume`'s own meaning lives with `src/wire/Sessions.ts`'s `resolveSession`, which produces it. */
 export interface DemandSession {
@@ -100,7 +110,7 @@ export type Demand =
 export const demandOf = (input: {
   readonly rendered: Pick<
     RenderedDemandSource,
-    "actor" | "content" | "state" | "skills" | "access" | "pin"
+    "actor" | "content" | "state" | "skills" | "access" | "pin" | "failure" | "blocked"
   >
   readonly kind: BeatKind
   readonly session?: DemandSession
@@ -108,7 +118,9 @@ export const demandOf = (input: {
 }): Demand => {
   const { rendered, kind, session, validate } = input
   const content =
-    kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor) : rendered.content
+    kind === "stalled"
+      ? stallDiagnosis(rendered.state, rendered.actor, rendered.failure, rendered.blocked)
+      : rendered.content
   const skills =
     rendered.skills !== undefined && rendered.skills.length > 0 ? rendered.skills : undefined
   const access = rendered.access ?? { read: null, write: null }

package/src/wire/constants.ts

@@ -23,3 +23,6 @@ export const ACCESS_REFUSAL =
 
 /** Where a process keeps its pin: the engine and workflow it runs on, as `gtd bundle` prints them. */
 export const PIN_PATH = ".gtd/process.gtdpin"
+
+/** Where a `run(…, { onFail: "rest" })` body's failure is recorded in the tree: the exit status and the output. */
+export const RUN_FAILED_PATH = ".gtd/run-failed.txt"

package/src/wire/types.ts

@@ -55,4 +55,8 @@ export interface RenderedDemandSource {
   readonly skills?: readonly string[]
   readonly access?: StepAccess
   readonly pin?: PinMark
+  /** The recorded output of a failed `onFail: "rest"` run, shown at the stalled beat. */
+  readonly failure?: string
+  /** Why landing a ship step is refused, shown at the stalled beat. */
+  readonly blocked?: string
 }

package/src/workflow/Workflow.ts

@@ -42,6 +42,7 @@ export interface StepDef {
   readonly requireRevert?: boolean
   readonly allowEmpty?: boolean
   readonly keep?: boolean
+  readonly onFail?: "rest"
   readonly acceptClean?: boolean
   readonly approve?: boolean
   readonly skills?: readonly string[]

package/src/workflow/compile.ts

@@ -8,6 +8,7 @@ export interface CompiledConfig {
   /** The built-in modes (qa/review, with gtd's own validators) merged with `config.modes`, per half. */
   readonly modes: Record<string, ModeDef>
   readonly ui?: UiSettings
+  readonly historyRemote?: string
   readonly skills: Readonly<Record<string, readonly string[]>>
   readonly access: GtdConfig["access"] & {}
   readonly diagnostics: readonly Diagnostic[]
@@ -48,6 +49,7 @@ export const compileConfig = (value: unknown, origin: string): CompiledConfig =>
   return {
     modes,
     ...(config.ui !== undefined ? { ui: config.ui } : {}),
+    ...(config.historyRemote !== undefined ? { historyRemote: config.historyRemote } : {}),
     // Null prototype: a `__proto__` key must stay an ordinary (reportable) entry.
     skills: Object.assign(Object.create(null), config.skills),
     access: Object.assign(Object.create(null), config.access),

package/src/workflow/load.ts

@@ -40,6 +40,7 @@ export interface ConfigOperations {
   readonly doors: ReadonlyMap<string, Door>
   /** `config.ui` (absent when unconfigured) — `gtd ui` and its CLI flags read it. */
   readonly ui?: flows.UiSettings
+  readonly historyRemote?: string
   /** Non-fatal findings, formatted through `formatDiagnostic` like an error. */
   readonly warnings: readonly Diagnostic[]
   /** The content hash of every file `gtd.config.ts`'s evaluation touched — itself plus any relative import — by path relative to the root. */
@@ -197,6 +198,7 @@ export const load: Effect.Effect<
       return entry === undefined ? undefined : resolve(name, entry)
     },
     ...(compiled.ui !== undefined ? { ui: compiled.ui } : {}),
+    ...(compiled.historyRemote !== undefined ? { historyRemote: compiled.historyRemote } : {}),
     warnings: diagnostics.filter((d) => d.severity === "warning"),
     fingerprint:
       pinned?.fingerprint ??