Concurrent-Session Awareness

← Back to Enforcement Layer concurrent-session-awareness.md

Concurrent-Session Awareness

Established: 2026-05-29 (confirmed Chris directive) Owner: Hone (enforcement infrastructure) — codename hone Dewey: 410 (Enforcement) Load when: Continuously / any session touching shared files, logs, manifests, or git state

1. The Operating Reality

Chris's default operating method is many simultaneous Claude Code sessions across the cockpit — D drive, monorepo, Main Brain, V2 platform, standalone sites — plus MCP servers running concurrently. Ten concurrent sessions is the normal load, not an unusual state.

Files, log and journal entries, manifest changes, and git-state shifts will routinely appear that the current session did not create. This is the expected baseline. Agents must arrive at every session already expecting outside-session activity, not treating it as a surprise or an anomaly.

The failure mode this skill prevents: treating session-start state as frozen and reacting to any deviation from it as corruption, a bug, or someone's mistake.

2. The Protocol — When an Agent Encounters an Artifact It Did Not Create

Step 1 — Default stance: concurrent activity, not corruption

Do not assume the unexpected artifact is an error, corruption, an accident, or a race condition to resolve. Concurrent activity is the expected baseline. Never react as if state was frozen at session start.

Step 2 — Establish provenance by inspection before reacting

Determine what created the artifact before deciding how to respond. The mechanism is inspection — read from available evidence:

  • log.md (append-only ledger, if the surface is the Main Brain or a surface that maintains one)
  • The day's journal entry
  • git log and git status to see recent commits and uncommitted changes
  • File modification times (ls -lt, stat) for relative recency
  • File content for contextual clues about authoring session

There is no separate session-ownership registry or signaling system. Provenance-by-inspection is the entire protocol. Do not wait for a signal that will not come.

Step 3 — If another session appears to be actively writing the same files: pause and yield

Detect an active live writer by: very recent modification times (within the last few minutes) AND ongoing writes observed across multiple checks, OR file locks that prevent access.

If a live writer is detected on files this session needs to write:

  • Pause and yield work on those specific files
  • Do not race the live writer
  • Do not read-reconcile-and-proceed in competition with ongoing writes
  • Re-establish the current state once writes appear complete
  • If the collision is real and cannot be resolved by waiting, surface it to Chris rather than competing

Step 4 — If relevant but not actively contended: read, reconcile, incorporate

When an outside-session change is relevant to this session's work but not actively being written:

  • Read it and incorporate the new state
  • Re-derive any conclusion that the new state affects
  • Do not proceed on a stale session-start snapshot of that file or data

Step 5 — If not relevant: leave it untouched

When an outside-session artifact has no bearing on this session's work:

  • Leave it exactly as found
  • Do not clean up, normalize, reformat, or revert it
  • Another session's work is not this session's housekeeping

Step 6 — Before any overwrite, destructive operation, or deploy: re-read the live target

Before writing over an existing file, running a destructive command, or deploying from the working tree:

  • Re-read the live target — it may have changed since this session last saw it
  • This is the same root principle as the pull-push-deploy rule (see Related Rules below)
  • Stale-snapshot overwrites are how one session silently reverts another session's work

Step 7 — Protect concurrency by construction

When writing to shared resources, use patterns that are safe for concurrent access:

  • Shared ledgers and journals: Append-only. Read the current tail, then append new content. Never overwrite the full file. Concurrent appenders may produce interleaved entries; that is acceptable and auditable. Truncating or rewriting the file destroys another session's entries.
  • Shared manifests and SHA indexes: Regenerate-don't-assume. When updating a shared manifest (e.g., skills/manifest.json, agents/manifest.json), read the current state first, apply the specific change, and write the updated whole. Do not assume the manifest matches what this session loaded at start. Stale-manifest assumptions produce phantom entries and incorrect counts.
  • Git staging: Stage only the specific files this session created or modified. Never use git add -A or git add . in a shared working tree — the tree may contain uncommitted changes from parallel sessions that should not be swept into this session's commit. Stage file-by-file by explicit path.
  • Git pull before push: Pull (with rebase) before pushing to avoid clobbering parallel-session commits to the remote. If the pull brings in conflicting changes to this session's files, stop and report rather than force-pushing.

Step 8 — Surface conflicts, do not silently absorb

When an outside-session change collides with this session's planned work — both sessions have written incompatible content, or the outside state makes this session's planned write incorrect:

  • Flag the collision to Chris
  • Present the two states and the nature of the conflict
  • Do not guess which version wins
  • Do not silently pick one and proceed as if the conflict did not exist

3. Provenance-by-Inspection Mechanism

The only mechanism for establishing who or what created an artifact is inspection. There is no session-ownership API, no heartbeat signal, no lock file that identifies the authoring session. Read available evidence and triangulate:

Evidence source What it tells you
git log --oneline -10 Recent committed changes and their messages
git status Uncommitted changes in the working tree
git diff HEAD What changed since the last commit
ls -lt <directory> Files sorted by modification time
stat <file> Precise modification timestamp
log.md (brain / surface ledger) Append-only record of brain mutations
Journal entry for today Session narrative — what was worked on and when
File content Context clues: agent signatures, timestamps, session markers

When provenance cannot be established from inspection alone, treat the artifact as concurrent-session work and proceed with Step 4 (incorporate) or Step 5 (leave untouched) depending on relevance.

4. Lived Examples (2026-05-29)

Three instances from the same day this skill was authored — all concurrent activity, none of them errors:

Example 1 — Out-of-order render-wiki entry in MainBrain/log.md A log entry for a render-wiki operation appeared in log.md authored by the Compass thread before the current session had appended its own entry. The current session had not written that line. The correct response: recognize it as a concurrent append, read to the new tail, then append this session's entry below it. An incorrect response would have been to treat the out-of-order line as corruption and truncate the log to restore it to the "known" state.

Example 2 — MEMORY.md edited mid-session by a parallel session MEMORY.md was modified mid-session by a parallel session capturing a new feedback entry. The current session had loaded MEMORY.md at session start. When the parallel write was detected, the correct response: re-read MEMORY.md to pick up the new state before making any further claims about its content. An incorrect response would have been to overwrite MEMORY.md with the session-start version during a subsequent write, silently erasing the parallel session's entry.

Example 3 — Brain lint baseline drifted from 34 to 37 between runs The lint baseline read 34 issues at the start of a session. A subsequent lint run returned 37. The delta was not caused by the current session's writes. The correct response: recognize that other sessions had touched files the linter scans, re-run lint to establish the current baseline, and proceed from 37 (not 34). An incorrect response would have been to report that the current session "introduced 3 new lint issues" when those issues predated the current session's work.

5. Related Rules

These existing rules share the same root principle (assume outside-session changes are possible and expected):

  • pull-push-deploy (wiki/conventions.md § Deploy Coordination) — re-read the remote before deploying; a deploy is a snapshot of the live working tree
  • never-wipe-real-state-during-tests (memory/feedback_no_wiping_real_state_during_tests.md) — do not destroy production state files during test runs; use synthetic IDs
  • match-removal-scope-precisely (wiki/agent-guide.md § Removal operations) — remove only what was asked; do not sweep adjacent work "while you're there"
  • undocumented-is-not-didnt-happen (memory/feedback_undocumented_is_not_didnt_happen.md) — absence of documentation in this session's view does not mean an action did not occur
  • verify-before-completion (skills/enforcement/vf-verification-before-completion.md) — re-read the live state before claiming completion; do not report from a session-start snapshot

6. Anti-Patterns (What Not to Do)

Temptation Why it is wrong
"I don't recognize this file — it must be a mistake, I'll remove it" Removal scope must be precise. This session did not create it; another session may depend on it.
"The manifest says 742 entries but I count 743 — I'll reset it to 742" The extra entry is likely from a parallel session. Incorporate it, do not erase it.
"The log has an entry I didn't write, so the log is corrupted" The log is append-only. An entry this session didn't write is another session's entry. Append below it.
"git status shows uncommitted changes that aren't mine — I'll git checkout . to clean them" Those changes belong to another session or another person. Do not discard other sessions' work.
"I'll just git add -A to make sure everything is included" Sweeps in other sessions' uncommitted work. Stage only this session's specific files.
"I know what the manifest looked like when I started, so I'll write back that version plus my change" Stale-snapshot write. Re-read the live manifest before updating it.
"The file modified timestamp is recent, but I'll proceed with my write anyway" Recent modification = possible live writer. Check before overwriting.