fix(template): install an optional session-end transcript archive hook in the devcontainer

[evanharmon1]

What

Teach the shared devcontainer image's installer to install an optional
session-end-archive.sh Claude hook, and ship that script in both devcontainer
config layers. This is step 1 of 3 — the hook is not registered yet, by
design (see Sequencing).

Why

Claude Code deletes transcripts after cleanupPeriodDays (unset, so the 30-day
default). Nothing in the devcontainer preserved them:

• .devcontainer/config/claude-settings.json registers PreToolUse,
  PostToolUse, and SessionStart — no SessionEnd
• no archive hook existed in claude-hooks/, in either layer
• the same config ships to every generated repo with a devcontainer

Container transcripts live on the claude-code-config-… named volume, so they
survive rebuilds — but they are still swept at 30 days, and lost entirely if the
volume is removed.

The equivalent host-side gap was fixed in harmon-dotfiles#68. That fix cannot
cover this case: there is no personal-settings layer inside a container, and
this repo may not depend on a dotfiles checkout. Either harmon-init wires it or
nothing does.

The guard is the interesting part

install-repo-config.sh gets a second, guarded hook loop:

for hook in \
    session-end-archive.sh; do
    [ -f "${config_dir}/claude-hooks/${hook}" ] || continue
    install -m 0755 "${config_dir}/claude-hooks/${hook}" "/etc/claude-code/hooks/${hook}"
done

The entry is deliberately absent from required_files. ${config_dir} is
the consuming repository's config, and repositories generated from older
templates have no such file. Listing it in required_files, or installing it
unguarded under set -e, would fail the devcontainer build of every repo that
has not adopted it yet. A new image must never break an old consumer.

Promoting it into required_files becomes correct only once the fleet has
taken the update, at which point a missing file is a real error rather than an
expected state.

Why not the simpler path

Pointing claude-settings.json at
/usr/local/share/devcontainer-config/claude-hooks/session-end-archive.sh — where
the COPY already lands it — would have avoided touching the image entirely and
shipped in one PR. Rejected: all seven existing registrations
(six hooks plus the statusline) use /etc/claude-code/…, and claude-settings.json
contains zero references to the staging directory. One hook at a different path
would be the sole exception to a uniform convention, in a repo whose premise is
that generated repos inherit one coherent setup. It would also sit outside
protect-files.sh's /etc/claude-code/ guard — the only agent-writable hook.

Sequencing — this PR does not enable archiving

The Dockerfiles pin an image digest, so registering the hook before that pin
moves would point at a path the pinned installer never creates.

1. This PR — installer support + the script, shipped inert
2. Merge → publish runs on main → new image published → pin bump lands
   in the root and template Dockerfiles
3. Follow-up PR — register SessionEnd in claude-settings.json, both
   layers, once the path is guaranteed to exist

Verification

• task verify — green, 6 template profiles PASS, 0 failures
• task test:devcontainer:image — shared image builds and smoke-tests with the
  repository overlay, exercising the new installer path
• Dogfood parity — 114 verbatim twins identical (up from 113)
• shellcheck --severity=error + shfmt -d clean on the installer and the hook
• Guard negative-controlled both ways: skips cleanly when the file is absent,
  installs when present

Rigor

standard (default) → challenge ≤3, review ≤3, shepherd 4. Resolved from
.devflow.toml on main; this change does not edit that file and carries no
rigor:* label.

• Challenge: converged at 2/3 — two consecutive rounds adjudicated to zero
  P0/P1. Round 2 confirmed the design directly: "the optional installer guard
  preserves compatibility with older consumers and the staged rollout is
  coherent."
• Review: converged at 2/3 — two consecutive adjudicated-clean rounds.

Both stages were run late, after the draft was opened, and only because they
were queried. The draft state is what made that recoverable.

Deferred findings

Five P2s across four rounds. One fixed here; four concern the script vendored
verbatim from harmon-devkit, where fixing them locally would fork a file whose
canonical copy and test suite live upstream.

• scripts/test-devcontainer-image.sh — fixed in 80e2ffd. The overlay
  builds from this repo, where the optional hook is present, so the install
  assertion passed whether the [ -f … ] guard worked or not — removing the
  guard or promoting the entry into required_files would have kept CI
  green while breaking every unmigrated consumer. Now builds a second
  overlay with the hook stripped out; negative-controlled both ways.
• session-end-archive.sh (corrupt archive never repaired) — filed as session-end-archive: a corrupt archive is never repaired — gzip -l failure exits 0 through the ERR trap harmon-devkit#439. gzip -l on a corrupt archive fails, the
  ERR trap exits 0, and the file is never rewritten.
• session-end-archive.sh (no retention) — filed as session-end-archive: archives accumulate without bound, and a full disk silently stops archiving harmon-devkit#440. Archives accumulate until the volume
  fills, after which archiving silently stops. Sharper here than on a host:
  the container's ~/.claude is a fixed-size volume.
• session-end-archive.sh (PID-reuse lock window) — filed as session-end-archive: a recycled PID keeps a dead lock alive for up to an hour, silently skipping archives harmon-devkit#441. A recycled PID keeps a dead lock alive for
  up to an hour, and each SessionEnd in that window exits without archiving.
• behavioural coverage of the hook — declined: harmon-devkit/scripts/test-archive-hook.sh
  already covers exactly the cases raised (happy path, unchanged no-op,
  growth with identical mtime, live and dead lock contention, invalid JSON,
  unwritable dir). The script is vendored verbatim, so a behavioural
  regression cannot originate here; this repo's responsibility is that it
  gets installed, which the new assertions cover.

Not in this PR

814 — pre-existing duplication in install-repo-config.sh (required_files,

the codex install loop, and /etc/codex/hooks each listed twice). Sits directly
beside this edit; kept separate so this diff stays reviewable.

🤖 Generated with Claude Code

[evanharmon1]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: 80e2ffd204

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[evanharmon1]

Blocker report — staying draft

The readiness gate fails on checks-failing, so this PR stays draft. Everything
else the gate needs is satisfied.

Condition	State
Required checks concluded successfully	❌ 6 failing
Current-head Codex cycle terminal and clean	✅ clean on 80e2ffd
Review findings fixed / declined / filed	✅
Inline review comments answered	✅ none outstanding
## Deferred findings all ticked	✅ 5/5, 0 unchecked
reviewDecision not CHANGES_REQUESTED	✅
mergeStateStatus not DIRTY/BEHIND/UNKNOWN	✅

The failures are an upstream outage, not this change

Every one dies fetching a dependency, none in repository code:

• guard, template-test (minimal), template-test (iac) — arduino/setup-task
  cannot download task v3.51.1: Failed to download version v3.51.1: Error: socket hang up
• candidate — Dockerfile:282 release downloads (zellij, workmux, aoe,
  agent-deck, sesh, herdr) fail, exit code: 2
• candidate-verify, verify — cascade from the above

Sustained rather than transient: the first wave hit at 16:49Z with
HTTP 503 on the same downloads, and it was still failing at 18:01Z with
socket hang up. One set of reruns in between did not clear it.

Evidence the change itself is sound

• task verify, task ci — green locally (6 template profiles, 0 FAIL lines)
• task test:devcontainer:image — candidate, repository overlay, and the new
  legacy overlay all pass
• Both negative controls pass: removing the hook script fails the install
  assertion; removing the [ -f … ] guard fails the legacy overlay build with
  install: cannot stat '…/claude-hooks/session-end-archive.sh'
• Dogfood parity — 114 verbatim twins identical
• 10 checks on this same head did pass, including both devcontainer build jobs

Next step

Re-run the failed jobs once the outage clears, then re-run the gate. No code
change is expected; if a rerun surfaces a failure that is not a dependency
download, that is new information and gets adjudicated on its own.

[evanharmon1]

Filed #829 to track step 3 — registering SessionEnd in claude-settings.json once the pin bump lands.

Raised by a reviewer: the hook this PR installs is never registered, so it is inert on merge. That is deliberate and documented above under "Sequencing", but it was recorded only in this PR body — which stops being visible once this merges. A reader scanning merged work would reasonably conclude container archiving is handled; it will not be until #829 lands.

Step 2 (publish + pin bump) needs no issue — publish-harmon-devcontainer.yml surfaces it automatically as a fix(devcontainer): update shared image to <sha> PR (precedents #740, #711, #706, #688, #651).

No change to this PR; the finding was about tracking, not correctness.