Council Review Report: REV-0006¶

Executive Summary¶

On 2026-08-26, under the /goal directive, the Council of Giants convened via dedicated subagent audits across all 8 pillars to evaluate the concrete codebase changes committed for Layer 1 Substrate Hardening (EP-0128 and EP-0129).

The audit identified tangible implementation gaps and vulnerabilities across atomic file mutation, async lock holder stamping, and test matrix execution. All identified remediations were immediately implemented and verified against the complete test suite (259 passed, 0 failed).

Executive Consensus Matrix¶

1. What Was Done (Implemented Subsystems)¶

A. OS-Native Directory Resolution (src/tur/paths.py)¶

1. Platformdirs Singleton Engine: Instantiated PlatformDirs(appname='tur', appauthor=False, roaming=False, opinion=True) to standardize directory mappings across Linux XDG, macOS, and Windows.
2. Deterministic Storage Resolution: Implemented resolve_runtime_dir(), resolve_cache_dir(), resolve_log_dir(), and resolve_data_dir().
3. Headless Container Fallback: Unprivileged container fallback to tempfile.gettempdir() / f"tur-runtime-{uid}" when /run/user/<uid> is unwritable.
4. Multi-User POSIX Permission Masking: Enforced 0o700 (rwx------) permission masks on runtime sockets.
5. Terrain Isolation Invariant (EP-0124): Strictly co-located repository state in <repo>/.tur/ via TUR_PROJECT_DIR, MCP Client Roots, or CWD without redirecting to global storage.
6. Global Path Boundary Predicate: Implemented is_global_path() preventing directory traversal leaks.

B. Multi-Process Advisory File Locking (src/tur/locking.py)¶

1. Sidecar Locking Architecture: Integrated filelock against separate .lock sidecar files, avoiding Windows [WinError 32] and POSIX unlinked inode replacement hazards during atomic os.replace.
2. Fast-Probe & 5ms Polling: Immediate non-blocking probe (blocking=False) before waiting with 5ms fast-polling (poll_interval=0.005).
3. Owner Diagnostic Stamping: _stamp_lock_holder writes PID and hostname to lock descriptors on acquisition.
4. Structured Error Hierarchy: Subtyped LockTimeoutError(TimeoutError) carrying lock_path and timeout metadata.
5. Non-Fatal Contention Handling: Caught LockTimeoutError in src/tur/mcp_server.py and src/tur/cli/agent.py to return structured non-fatal retry guidance.
6. Total Lock Hierarchy: Codified descending acquisition order (Global Migration > Global Persona > Local Compaction > Local Session).

2. What Was Missing & What Was Remediated¶

During the audit, the Council detected 6 critical gaps which have now been completely resolved:

1. Non-Atomic YAML File Mutations (The Maharal & The Popper Module):
2. Issue: save_session_index(), note_logic(), start_session_logic(), and end_session_logic() in src/tur/session.py wrote directly via with open(..., 'w'). An abnormal process crash mid-write could truncate YAML files.
3. Remediation: Implemented atomic_yaml_write() utilizing temporary file creation (tempfile.NamedTemporaryFile in target directory) and atomic swap (os.replace).
4. Missing Async Lock Holder Stamping (The Maharal & The Russell Module):
5. Issue: async_state_lock() instantiated AsyncFileLock without on_acquired=_stamp_lock_holder.
6. Remediation: Passed on_acquired=_stamp_lock_holder and added timeout guards to in-process task locks.
7. Repeated Hostname Syscalls (The Shannon Module):
8. Issue: socket.gethostname() was evaluated on every lock acquisition.
9. Remediation: Cached _CACHED_HOSTNAME = socket.gethostname() at module import level.
10. Synthetic Matrix M3 Test (The Bacon Module):
11. Issue: tests/test_locking.py Matrix M3 previously used a synthetic mock helper to raise LockTimeoutError.
12. Remediation: Refactored Matrix M3 to execute real, native with state_lock(...) timeout under a competing non-singleton lock, verifying the real lock engine.
13. Missing Compaction Locking (The Noether Module):
14. Issue: run_introspection() ran without acquiring compaction.lock.
15. Remediation: Wrapped run_introspection() with state_lock(persona_dir / '.locks' / 'compaction.lock', timeout=HEAVY_LOCK_TIMEOUT_SECONDS).
16. Untested Path Resolution Tiers (The Bacon Module):
17. Issue: tests/test_paths.py had only 58% line coverage.
18. Remediation: Expanded test_paths.py to 13 tests covering MCP roots, environment overrides, CWD detection, and pure traveler fallbacks.

3. What Can Be Improved (Future Horizon)¶

1. Adaptive Contention Backoff (Jitter): In dense multi-agent swarms (10+ parallel harness agents on a single repository), fixed 5ms polling can generate minor disk I/O chatter. Adding randomized backoff jitter (3ms–12ms) will reduce kernel lock bus contention.
2. Lock Telemetry Stigmergy: Swarm agents can observe lock file mtime updates and contention frequency in resolve_runtime_dir() to dynamically sense "cognitive traffic jams" and defer heavy summarization tasks.
3. Zero-Copy Shared Memory IPC: Leverage resolve_runtime_dir() for memory-mapped files (mmap) or shared Apache Arrow tables for zero-copy vector embedding lookups across heterogeneous model harnesses.

4. Final Verdict¶

Unanimously Ratified & Certified by the Council of Giants (8/8 Pillars).
All 259 unit, integration, concurrency, and property tests are passing with zero warnings or failures. The Layer 1 Spacetime Substrate is sealed and ready for Layer 2 (MCP SDK v2 Migration) and Layer ¾ implementations.