Devlog CLI

3 min read

Add locked session summaries and opt-in automatic logging

Summary

Made session_id mandatory and changed devlog storage to one replaceable summary per project and coding session. Implemented read, locked save (with add as an alias), and release using 15-minute persistent leases, content-digest checks, stale-token rejection, atomic replacement, and conflict detection. Matching append-style session logs can be read in full and migrated by saving a combined summary; file paths, entry IDs, and creation times remain stable while updated changes. Updated the repository and installed agent skills, CLI documentation, Pi auto-devlog extension, and integration documentation to use originating session IDs and read → combine → save or release. Rebuilt the repository and installed Go binaries. Added an opt-in folder allowlist to the existing extension, managed with /devlog-folders list, add, and remove; roots include descendants, use canonical paths, exclude prefix siblings and symlink escapes, and persist privately with atomic replacement. Missing or empty configuration disables automatic logging, invalid configuration fails closed, and unapproved folders produce no worker, report, or transcript. Configuration changes apply at shutdown without reloading; automatic logging still runs only on interactive quit, not after each task. Installed the extension with an initially empty allowlist; Pi reload remained necessary to activate the new command. Verification in the transcript included passing Go race tests, go vet, cross-process locking/replacement checks, worker syntax checks, and seven mocked extension tests covering handoff, recursion guards, allowlist persistence, path boundaries, invalid configuration, deleted roots, and live configuration changes. No end-to-end model-driven logging test was shown. Inspected two older journal files without session metadata and confirmed the installed CLI rejected missing session IDs; their creating tool remained unidentified. During this journal update, the installed extension matched the source, but Git diff review was unavailable because the workspace had no Git metadata.

Decisions

  • Keep one current summary per project and coding session rather than timestamped append-only entries or subsessions.
  • Acquire the persistent session lock during read and require its returned lock token for save or release; reject tokenless writes and externally changed files.
  • Keep session_id as provenance and lock_token as short-lived update authorization.
  • Have the agent, not the CLI or extension, combine existing material with newly completed outcomes before replacement.
  • Make automatic logging opt-in through a folder allowlist in the existing Pi extension; an empty list approves nothing, while manual devlog use remains available anywhere.

Learnings

  • A save-only lock cannot prevent lost updates from stale reads; locking must cover the read-combine-save interval.
  • A journal summary mentioning session support does not prove the file has session metadata, and creation dates alone do not identify its writing tool.
  • Reload or restart Pi after extension code changes; already-running detached workers retain their original prompts. Folder configuration changes do not require another reload.
  • Folder authorization needs canonical path and descendant-boundary checks rather than string-prefix matching.