transcript-capture: durable fleet transcript archive + fleet-wide deletion disable

Implements designs/transcript-journal-capture.md § Builder spec (items 1–8).
Everything is INERT until a maintainer arms a transcripts remote
(config/transcripts-remote on journal2, absent today): unarmed, every host still
disables Claude Code's deletion and spools its finished transcripts locally,
losing nothing — only the push is gated.

- common.sh: GARDEN_TRANSCRIPTS_BRANCH/_SPOOL/_IDLE_SECS knobs + transcript_spool
  helper (offline-safe gzip-into-spool, never fails its caller).
- handlers/gardener-claude.sh: spool the finished transcript BEFORE the existing
  rm -f (the false-resume rm and its rationale stay verbatim).
- transcript-capture.sh: the per-tick sweep — reconcile cleanupPeriodDays=36500
  first/unconditionally (jq read-modify-write, foreign keys preserved), read the
  armed remote from the journal (inert if absent), ensure a partial+sparse
  transcripts2 clone (orphan-init when the branch is absent), drain the spool +
  sweep idle/changed ~/.claude/projects sessions through redact_stream then
  gzip -n, commit + verified CAS push (fetch/reset/reapply), clear spool + update
  ledger only after a verified push. Runs on EVERY host (no is-main-host gate).
- set-transcripts-remote.sh: CAS-writes config/transcripts-remote (the arming act).
- garden-transcript-capture.{service,timer}: hourly at :20, self-heal-run wrapped,
  no is-main-host ExecCondition; auto-enabled by install-units.
- garden launcher: seed cleanupPeriodDays=36500 into new instances' settings.json.
- test/transcript-capture-test.sh: 20 assertions, all green — inert-when-unarmed,
  settings reconcile (absent file + foreign keys), spool drain, redaction, idle
  gating, changed-session re-capture, and CAS retry against a racing peer commit.
- context/operations/transcripts.md: operator page (arming, browsing, rotation).

Arming (create the private repo, grant push, run set-transcripts-remote.sh, post
the role/liaison notice) is the maintainer's act, after this lands. Bring-up
surfacing + the liaison broadcast-reader are the serial follow-up child
build-liaison-broadcast-reader; starting.md and roles/liaison/AGENT.md are
deliberately untouched here to avoid conflicting with it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: endolinbot

context/operations/transcripts.md

@@ -0,0 +1,108 @@
+# Transcript durability (the archive)
+
+How the garden keeps its own session transcripts instead of letting Claude Code
+delete them, and how to browse one later. Two postures ship together:
+
+- **Deletion is disabled fleet-wide.** Claude Code deletes session transcripts
+  after `cleanupPeriodDays` (default 30). The garden sets `cleanupPeriodDays:
+  36500` ("effectively never") — the `garden` launcher seeds it into every new
+  instance's `~/.claude/settings.json`, and `transcript-capture.sh` reconciles the
+  same key on every existing host each tick (settings.json is gitignored, so it
+  cannot propagate via git — both prongs are required). This half needs **no
+  arming**; it is on the moment this build deploys.
+- **Transcripts are archived** into a dedicated `transcripts2` orphan branch on a
+  configurable remote, gzip-compressed and lightly redacted, keyed by host. This
+  half is **inert until you arm a transcripts remote** — until then every host
+  still disables deletion and **spools** its finished transcripts locally
+  (`$GARDEN_STATE/transcripts/spool`), losing nothing; only the push is gated.
+
+Design and rationale: [`designs/transcript-journal-capture.md`](../../designs/transcript-journal-capture.md).
+
+## Arming the archive (maintainer-only, deliberate)
+
+Transcripts are the fleet's raw working memory — tokens that scrolled through a
+shell, maintainer email, private reasoning. Publishing them is not a default any
+agent picks, so the remote is per-instance journal config and arming is your
+call.
+
+1. **Create a remote to hold the branch.** A **dedicated private repo** is
+   recommended (e.g. `kriskowal/garden-transcripts`); grant the bot push access.
+   Using the garden's own origin is possible but **it is public** — that would
+   publish the fleet's transcripts to the world.
+2. **Point the fleet at it:**
+
+   ```sh
+   scripts/jobs/set-transcripts-remote.sh git@github.com:kriskowal/garden-transcripts.git
+   ```
+
+   This CAS-writes `config/transcripts-remote` on `journal2`. The next
+   `garden-transcript-capture` tick on each host (hourly, at :20) reads it, drains
+   its spool, and pushes. If the `transcripts2` branch does not exist on the
+   remote yet, the first push creates it.
+3. **Record it** with a journal `message` entry (the arming is a standing state
+   change), and — because local `~/.claude` disk no longer self-prunes — post a
+   fleet notice so every liaison surfaces the disk-posture change:
+
+   ```sh
+   scripts/jobs/send-msg.sh role/liaison "transcript durability is armed; local ~/.claude no longer self-prunes — size disk accordingly"
+   ```
+
+Left unarmed, nothing breaks: deletion stays disabled and transcripts spool
+locally until you arm a remote (spooled entries drain on the first armed tick).
+
+## Where transcripts land
+
+```
+transcripts/<GARDEN>/<encoded-cwd>/<session-id>.jsonl.gz   # one per captured session
+index/<GARDEN>.tsv                                          # one appended row per capture
+```
+
+`<GARDEN>` is the host identity, so hosts never write each other's paths and
+concurrent pushes conflict only at the CAS. Each `index/<GARDEN>.tsv` row is
+`captured_at  session_id  job_base(or -)  encoded_cwd  raw_bytes  gz_bytes  raw_mtime`.
+The encoded cwd of a gardener job contains `gardener-wt-<base>`, so the job base
+is recoverable from the path alone.
+
+## Browsing a transcript
+
+Clone the transcripts remote's branch (or reuse a host's capture clone at
+`$GARDEN_STATE/transcripts/clone`):
+
+```sh
+git clone --branch transcripts2 <transcripts-remote> /tmp/transcripts
+# find a job's transcript across all hosts by its base:
+ls /tmp/transcripts/transcripts/*/*gardener-wt-build-thing*/
+# read one:
+git -C /tmp/transcripts show transcripts2:transcripts/<host>/<dir>/<sid>.jsonl.gz | gunzip | less
+```
+
+Secrets in known shapes (GitHub tokens, `sk-ant-…`, `Authorization: Bearer …`)
+are masked with `…REDACTED` before storage — defense in depth behind the
+private-remote scoping, which is the primary guarantee. No redaction list is
+complete; keep the remote private.
+
+## Rotation (the escape hatch, if the branch ever grows too large)
+
+With capture-on-completion each transcript is committed about once, so history
+overhead stays near the tree size and this is unlikely to bite for years. No
+pruning is built. If the branch ever needs shrinking, **rotate, don't rewrite**:
+
+```sh
+git -C <clone> tag transcripts2-archive-<year> transcripts2
+git -C <clone> push origin transcripts2-archive-<year>
+# then start a fresh orphan transcripts2 (delete the branch on the remote and let
+# the next capture tick re-init it), keeping the tagged snapshot for cold storage.
+```
+
+File an issue when the corpus first warrants it rather than pre-optimizing.
+
+## Knobs
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `GARDEN_TRANSCRIPTS_BRANCH` | `transcripts2` | the orphan branch transcripts live on |
+| `GARDEN_TRANSCRIPTS_SPOOL` | `$GARDEN_STATE/transcripts/spool` | per-host completion-hook staging dir |
+| `GARDEN_TRANSCRIPT_IDLE_SECS` | `21600` (6h) | a session is swept only once idle this long |
+
+The optional local janitor (delete originals already archived) and a
+`find-transcript.sh` wrapper are deferred follow-ons, not part of this build.

garden

@@ -108,10 +108,14 @@ cmd_reset() {
 # only when absent (a hand-edited file is preserved). The container's home IS
 # the bind-mounted repo root, so this one file covers both the user-level
 # (~/.claude/settings.json) and project-level (<repo>/.claude/settings.json)
-# scopes at once. Its sole content is a SessionStart hook running the container
-# guard, making the guard automatic for every session that starts in the garden
-# root — INCLUDING a host-side session, which is exactly where the guard must
-# fire. It deliberately does NOT set a permission defaultMode: the settings file
+# scopes at once. It carries a SessionStart hook running the container guard,
+# making the guard automatic for every session that starts in the garden root —
+# INCLUDING a host-side session, which is exactly where the guard must fire — plus
+# `cleanupPeriodDays: 36500` so Claude Code's 30-day transcript deletion is
+# disabled from the first session (the transcript archive keeps the garden's
+# record; designs/transcript-journal-capture.md). transcript-capture.sh reconciles
+# the same key on existing hosts, since this file is gitignored and cannot
+# propagate via git. It deliberately does NOT set a permission defaultMode: the settings file
 # is visible host-side too, so a settings-level bypass would silently make
 # host-side sessions permissionless. Auto mode rides the launch flag instead
 # (see the exec in cmd_enter), which applies only to the in-container session.
@@ -121,6 +125,7 @@ seed_claude_settings() {
     mkdir -p "${SCRIPT_DIR}/.claude"
     cat > "$settings" <<'JSON'
 {
+  "cleanupPeriodDays": 36500,
   "hooks": {
     "SessionStart": [
       {

scripts/jobs/common.sh

@@ -126,6 +126,29 @@ export GARDEN
 # the old marker, is never stranded. Remove once no host carries a NOPE marker.
 : "${GARDEN_KILLSWITCH:=$GARDEN_STATE/NOPE}"
 
+# --- transcript capture (designs/transcript-journal-capture.md) ---------------
+#
+# The garden captures every host's finished session transcripts into a dedicated
+# `transcripts2` orphan branch on a configurable transcripts remote, so the
+# journal holds the garden's transcript. All three knobs are overridable so the
+# test harness can point the same code at a throwaway spool/remote.
+#
+# GARDEN_TRANSCRIPTS_BRANCH — the orphan branch transcripts live on, mirroring the
+#   journal2 pattern; it is never merged with main2/journal2 and only the capture
+#   service and a browsing human ever fetch it.
+# GARDEN_TRANSCRIPTS_SPOOL — a per-host staging dir under $GARDEN_STATE (outside
+#   any reset-prone worktree) where the gardener completion hook drops a gzip copy
+#   of a finishing job's transcript BEFORE the handler's `rm -f` retires it (the
+#   false-resume hazard is real, so the rm stays). The hourly capture timer drains
+#   the spool. Spooling happens whether or not a remote is armed, so nothing is
+#   lost while the archive is unconfigured.
+# GARDEN_TRANSCRIPT_IDLE_SECS — the sweep captures a `~/.claude/projects` session
+#   only once its mtime is older than this (default six hours), so a live,
+#   still-growing session is not captured over and over.
+: "${GARDEN_TRANSCRIPTS_BRANCH:=transcripts2}"
+: "${GARDEN_TRANSCRIPTS_SPOOL:=$GARDEN_STATE/transcripts/spool}"
+: "${GARDEN_TRANSCRIPT_IDLE_SECS:=21600}"
+
 # --- bounded git network operations (the stuck-fetch hardening) --------------
 #
 # A journal fetch should finish in well under a second, but git has NO default
@@ -713,6 +736,47 @@ kill_stale_worktree_handlers() {
   return 0
 }
 
+# transcript_spool <jsonl-path> [<job-base>] — stage a finishing session's
+# transcript into the capture spool so the hourly sweep (transcript-capture.sh)
+# can archive it even though the gardener completion hook is about to `rm` the
+# original (the false-resume hazard the rm exists to prevent). gzip-copies
+# <jsonl-path> to
+#   $GARDEN_TRANSCRIPTS_SPOOL/<encoded-cwd>/<session-id>.jsonl.gz
+# and appends a pending index row (tab-separated: spooled_at, session_id,
+# job_base-or-'-', encoded_cwd) to $GARDEN_TRANSCRIPTS_SPOOL/pending.tsv. The
+# <encoded-cwd> is the parent directory NAME of the jsonl (Claude Code's project
+# dir), which already carries the `gardener-wt-<base>` pattern the sweep can
+# back-derive a base from. Does NO network work and NEVER fails its caller —
+# every path logs and returns 0 — so the completion path stays fast and
+# offline-safe and the spool survives under $GARDEN_STATE until the timer drains
+# it. A missing/empty source is a silent no-op (returns 0): the hook calls this
+# for BOTH candidate encodings and only one exists. Redaction is NOT applied here
+# (the spool is un-redacted, gzipped raw); the sweep redacts on drain, so
+# redaction lives in exactly one place.
+transcript_spool() {
+  local src="${1:-}" base="${2:--}"
+  [ -n "$src" ] && [ -f "$src" ] || return 0
+  local encoded_cwd sid spool_dir dest now
+  encoded_cwd="$(basename "$(dirname "$src")")"
+  sid="$(basename "$src" .jsonl)"
+  spool_dir="${GARDEN_TRANSCRIPTS_SPOOL}/${encoded_cwd}"
+  if ! mkdir -p "$spool_dir" 2>/dev/null; then
+    log "WARN: transcript_spool: cannot create spool dir $spool_dir; not spooling $sid"
+    return 0
+  fi
+  dest="$spool_dir/$sid.jsonl.gz"
+  if ! gzip -nc -- "$src" > "$dest" 2>/dev/null; then
+    log "WARN: transcript_spool: gzip of $src failed; not spooling $sid"
+    rm -f "$dest" 2>/dev/null || true
+    return 0
+  fi
+  now="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo -)"
+  printf '%s\t%s\t%s\t%s\n' "$now" "$sid" "${base:--}" "$encoded_cwd" \
+    >> "${GARDEN_TRANSCRIPTS_SPOOL}/pending.tsv" 2>/dev/null \
+    || log "WARN: transcript_spool: could not append pending index row for $sid"
+  return 0
+}
+
 bot_name()  { git -C "$GARDEN_ROOT" config --get user.name  2>/dev/null || echo garden-bot; }
 bot_email() { git -C "$GARDEN_ROOT" config --get user.email 2>/dev/null || echo garden-bot@localhost; }
 

scripts/jobs/handlers/gardener-claude.sh

@@ -305,6 +305,13 @@ fi
 # GARDEN_SCRATCH_GC_AGE hours of quiescence.
 if [ -n "${GARDEN_COMPLETION_SENTINEL:-}" ] && [ -e "$GARDEN_COMPLETION_SENTINEL" ]; then
   scratch_cleanup "$worktree"
+  # Spool the finished transcript into the capture archive BEFORE the rm below
+  # retires it (designs/transcript-journal-capture.md). transcript_spool is
+  # offline-safe and never fails the handler; it gzip-copies whichever candidate
+  # encoding exists into $GARDEN_TRANSCRIPTS_SPOOL and the hourly capture timer
+  # drains it. Carrying $base records the job identity authoritatively.
+  transcript_spool "$proj_dir/$session_id.jsonl" "$base"
+  transcript_spool "$proj_dir_alt/$session_id.jsonl" "$base"
   # Retire the session transcript too. The session id is DETERMINISTIC from the
   # base, so a later re-post of a drained base would otherwise find this
   # finished session and --resume it: a model whose history ends "job finished,

scripts/jobs/set-transcripts-remote.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# set-transcripts-remote.sh — arm the transcripts archive by declaring the remote
+# that carries the `transcripts2` orphan branch, in the journal (CAS).
+#
+# Usage: set-transcripts-remote.sh <git-url>
+#   e.g. set-transcripts-remote.sh git@github.com:kriskowal/garden-transcripts.git
+#
+# Writes config/transcripts-remote on the journal. transcript-capture.sh reads it
+# at runtime and is INERT until it exists: every host still disables Claude Code's
+# deletion and SPOOLS its finished transcripts locally, but pushes nowhere until a
+# remote is configured. Writing this file is therefore the deliberate ARMING act,
+# and — because transcripts are the fleet's raw working memory — a safety-weighted
+# one the maintainer performs (a private repo is recommended; the garden's own
+# origin is public). Record it with a journal `message` entry when you arm it.
+# See designs/transcript-journal-capture.md and context/operations/transcripts.md.
+#
+# Overwrites one file, so a rejected push just re-syncs and retries. Modeled on
+# set-garden-repo.sh.
+
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+GARDEN_TAG="set-transcripts-remote"
+
+url="${1:?usage: set-transcripts-remote.sh <git-url>}"
+# Accept the git URL shapes we actually push over: scp-like ssh
+# (git@host:owner/repo.git), ssh:// , https:// , and a local path (for tests).
+case "$url" in
+  *[[:space:]]*) die "illegal transcripts remote '$url' (contains whitespace)";;
+  git@*:*|ssh://*|https://*|http://*|/*|file://*) : ;;
+  *) die "illegal transcripts remote '$url' (expected git@host:owner/repo.git, ssh://…, https://…, or an absolute path)";;
+esac
+
+DIR="${GARDEN_PRODUCER_CLONE:-$GARDEN_STATE/producer/journal}"
+ensure_clone "$DIR"
+
+for attempt in $(seq 1 50); do
+  sync_clone "$DIR"
+  mkdir -p "$DIR/config"
+  printf '%s\n' "$url" > "$DIR/config/transcripts-remote"
+  git -C "$DIR" add "config/transcripts-remote"
+  # Capture the return with `|| rc=$?` (NOT an `if`): a false `if` with no `else`
+  # has exit status 0, which would swallow commit_and_push's rc=2 "nothing to
+  # commit" (the idempotent re-run) and loop forever.
+  rc=0; commit_and_push "$DIR" "config: transcripts-remote=$url" || rc=$?
+  [ "$rc" -eq 0 ] && { log "set transcripts-remote=$url"; exit 0; }
+  [ "$rc" -eq 2 ] && { log "transcripts-remote already $url"; exit 0; }
+  log "set transcripts-remote lost a push race (attempt $attempt); re-syncing"
+  backoff "$attempt"
+done
+die "could not set transcripts-remote after retries"