gbrain/recipes/agent-voice/install/refresh-algorithm.md

Refresh algorithm (diff-and-propose)

gbrain integrations install agent-voice --refresh re-walks the manifest, classifies every file into one of five states, and lets the operator decide per-file. The reference implementation is in src/commands/integrations.ts under the install_kind: copy-into-host-repo branch.

State machine

For each file declared in install/manifest.json:

Let src_hash    = SHA-256 of gbrain-side file at manifest.src
Let host_path   = <target-repo>/<manifest.target>
Let recorded   = .gbrain-source.json.files[].sha256 for this entry (or absent if first refresh)
Let host_hash  = SHA-256 of host_path (or absent if file deleted on host side)

State:
  - "unchanged-identical"  iff host_hash == src_hash
                           → no-op
  - "unchanged-stale"      iff host_hash == recorded AND host_hash != src_hash
                           → operator unmodified, source moved → offer update
  - "locally-modified"     iff host_hash != recorded AND host_hash != src_hash AND host_hash is defined
                           → operator edited locally; offer three options (see below)
  - "host-deleted"         iff host_hash is absent AND src exists
                           → operator removed the file; offer to restore or to remove from manifest
  - "source-deleted"       iff src is absent AND host_hash is defined
                           → gbrain reference removed the file; offer cleanup (remove from host)

A path-mapping renames table in the manifest (renames: [{from, to}], not yet shipped) allows the refresh algorithm to detect a source-renamed file as a logical update rather than a delete+add.

"Locally-modified" decision

When a file shows locally-modified, the operator picks one of three options:

• keep-mine — leave host file untouched. The manifest entry's sha256 is updated to the current host hash (the operator's edit becomes the new "recorded" baseline; future refreshes won't re-flag it until they edit it again OR the source changes).
• take-theirs — copy the gbrain reference over the host file. The recorded SHA becomes the new src_hash.
• merge — print a unified diff. Operator hand-merges in their editor; the refresh command exits without writing. Re-run --refresh after the merge to confirm.

Transaction journal

<target-repo>/services/voice-agent/.gbrain-source.refresh.log is a JSONL append-only file. Each line records:

{"ts": "2026-05-17T12:34:56Z", "src": "code/server.mjs", "state": "locally-modified", "decision": "keep-mine"}

The journal exists for two reasons:

1. Partial-apply recovery. If the refresh is interrupted mid-loop (Ctrl-C, crash, machine reboot), re-running --refresh reads the journal and resumes where it stopped.
2. Audit. Operators can grep the journal to see which files were touched and why.

The journal is rotated by file size (>1MB triggers rename to .gbrain-source.refresh.log.1) and ignored by --refresh's own scan (the journal is host-only metadata, not a managed file).

Concurrent refresh guard

--refresh acquires an advisory file lock at <target-repo>/services/voice-agent/.gbrain-source.refresh.lock for the duration of the run. Concurrent --refresh invocations on the same host repo fail-fast with "refresh already in progress."

CLI surface

gbrain integrations install agent-voice --target <repo> --refresh
gbrain integrations install agent-voice --target <repo> --refresh --dry-run     # report-only
gbrain integrations install agent-voice --target <repo> --refresh --auto take-theirs   # non-interactive
gbrain integrations install agent-voice --target <repo> --refresh --auto keep-mine     # bias toward operator's edits

--auto <decision> applies the named decision to ALL locally-modified files without prompting. Useful for CI lanes that want either "always take upstream" or "always preserve local" without operator interaction.

What this v0 deliberately skips

• Conflict resolution for files that exist in both manifests but at different paths (treated as add+delete).
• Concurrent edits on the SAME file mid-refresh (the advisory lock + per-file atomic write covers this).
• Semantic merges (we offer file-level diff only; no per-hunk picking).
• Manifest schema migration (v0.1.0 → v0.2.0 changes are handled by the install command refusing to refresh old manifests and asking the operator to re-install).

Each of those is a follow-up TODO.