From 041047601aa0bf384606dfc57968dc6012fce3f3 Mon Sep 17 00:00:00 2001
From: Oskar Kapala <oskar.kapala@gmail.com>
Date: Tue, 5 May 2026 17:25:50 +0200
Subject: [PATCH] add shared context lock

---
 README.md          | 23 +++++++++++++++++++++++
 codex_context.yaml |  8 ++++++--
 sync-context.sh    | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 923de6b..c5fa3c9 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,29 @@ This repository documents the current known state of the homelab.
 
 The documentation is based only on stated facts. Missing details are recorded as unknowns and need clarification.
 
+## Shared context sync lock
+
+`sync-context.sh` uses a git-tracked `.context.lock` file to serialize updates to `codex_context.yaml`.
+
+If `codex_context.yaml` has changes, the script:
+
+1. pulls with rebase
+2. aborts if `.context.lock` already exists and prints its contents
+3. creates `.context.lock` with `hostname`, `username`, and UTC `timestamp`
+4. commits and pushes the lock with message `lock shared context`
+5. validates `codex_context.yaml`, commits it, and pushes
+6. removes `.context.lock`, commits `unlock shared context`, and pushes
+
+If any step fails after lock creation, the script prints `Lock may need manual cleanup` and leaves the lock in place.
+
+Manual cleanup:
+
+1. inspect `.context.lock`
+2. confirm the owning host/user is no longer updating context
+3. remove the file
+4. commit `unlock shared context`
+5. push
+
 ## Current configuration
 
 - Main server hardware: Raspberry Pi 5
diff --git a/codex_context.yaml b/codex_context.yaml
index aaba8ba..4b6ea2e 100644
--- a/codex_context.yaml
+++ b/codex_context.yaml
@@ -2,9 +2,9 @@ SESSION_STATE:
   meta:
     goal: "Maintain compressed lossless session memory in ./codex_context.yaml"
     environment:
-      cwd: "/home/oskar/projects/homelab-codex-ws"
+      cwd: "/home/oskar/homelab-codex-ws"
       shell: "zsh"
-      date: "2026-05-03"
+      date: "2026-05-05"
       tz: "Europe/Warsaw"
   systems:
     S1:
@@ -100,6 +100,9 @@ SESSION_STATE:
     D40: "Created ./start-aider.sh and ./update-context.md on 2026-05-03. start-aider.sh runs from repo root, defaults OLLAMA_API_BASE to http://100.100.231.104:11434, uses model ollama/deepseek-coder:latest, and attaches ./codex_context.yaml via aider --read after confirming read-only support from local aider help. update-context.md documents shared context rules for Codex and Aider; scripts set executable."
     D41: "Startup 2026-05-03: read existing ./codex_context.yaml before task work, verified parity with user-provided SESSION_STATE, retained state, overwrote file."
     D42: "Aider is installed as a local coding assistant, but current local Ollama models are not reliable enough for context-file editing."
+    D43: "Startup 2026-05-05: read existing ./codex_context.yaml before task work, verified parity with user-provided SESSION_STATE, observed clean re-cloned repo on branch master, refreshed meta.environment for current workspace."
+    D44: "Updated ./sync-context.sh on 2026-05-05 to use git-tracked ./.context.lock around codex_context.yaml sync: abort and print lock contents if present; on context changes create lock with hostname/username/UTC timestamp, commit/push lock, validate YAML, commit/push context, then remove lock and commit/push unlock; failures after lock creation print 'Lock may need manual cleanup' and leave lock in place; no auto-merge conflict resolution."
+    D45: "Updated ./README.md on 2026-05-05 with shared context lock flow and manual .context.lock cleanup procedure."
   todos:
     T1: "For all future meaningful changes/decisions, update and overwrite ./codex_context.yaml."
     T2: "DONE: Commit current changes."
@@ -125,6 +128,7 @@ SESSION_STATE:
     T22: "DONE: Retry Aider setup on remaining hosts using corrected SSH targets pi@piha and ubuntu-4gb-hel1-1; both verified at aider 0.86.2."
     T23: "DONE: Add shared Codex/Aider context bootstrap scripts and update-context protocol doc."
     T24: "Use Codex for codex_context.yaml updates; use Aider only for simple code edits until a better local model/edit format is validated."
+    T25: "DONE: Add safe git-tracked shared context lock to sync-context.sh and document manual cleanup."
   issues:
     I1: "Tailscale DNS health warning: configured DNS servers unreachable."
     I2: "Preferred gateway path unavailable: 100.108.208.3:8080 connection failed."
diff --git a/sync-context.sh b/sync-context.sh
index 1d27956..f5d588e 100755
--- a/sync-context.sh
+++ b/sync-context.sh
@@ -3,6 +3,7 @@
 set -euo pipefail
 
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+LOCK_FILE=".context.lock"
 
 if [[ -z "$REPO_ROOT" ]]; then
   echo "Not inside a git repository" >&2
@@ -31,7 +32,39 @@ if git diff --quiet -- codex_context.yaml && git diff --cached --quiet -- codex_
   exit 0
 fi
 
+if [[ -e "$LOCK_FILE" ]]; then
+  echo "Shared context is locked:" >&2
+  cat "$LOCK_FILE" >&2
+  exit 1
+fi
+
+lock_created=0
+
+cleanup_note() {
+  if [[ "$lock_created" -eq 1 ]]; then
+    echo "Lock may need manual cleanup" >&2
+  fi
+}
+
+trap cleanup_note ERR
+
+printf "hostname: %s\nusername: %s\ntimestamp: %s\n" \
+  "$(hostname)" \
+  "$(id -un)" \
+  "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+  > "$LOCK_FILE"
+lock_created=1
+git add "$LOCK_FILE"
+git commit -m "lock shared context"
+git push
+
 python3 -c "import yaml; yaml.safe_load(open('codex_context.yaml'))"
 git add codex_context.yaml
 git commit -m "update shared context"
 git push
+
+rm -f "$LOCK_FILE"
+git add "$LOCK_FILE"
+git commit -m "unlock shared context"
+git push
+trap - ERR