Coordination Primitives
Coordination operates without message buses, active servers, or RPC. ostk projects state directly into the filesystem, managing concurrency via per-file generation checks, resolving collisions with mechanical merges, and routing interrupts using durable queues.
VFS: The Observation Substrate
The VFS is a FUSE filesystem owned by the daemon. It projects the daemon's live memory and registries as standard directories. Any tool (e.g., ls, cat, grep) can query kernel state directly without needing JSON-RPC parsers.
VFS_CLI_REFERENCE
# Mount at the default path (.ostk/vfs/) $ ostk vfs mount # Check mount status & owning daemon PID $ ostk vfs status declared: auto_mount: true mount_point: ~/.ostk/vfs actual: mounted: true owner: daemon owner_pid: 27060 # Cleanly unmount VFS overlay $ ostk vfs unmount # Clean up orphan FUSE mounts left by hard crashes $ ostk vfs unmount-stale
Directory Namespaces
Top-level namespaces map to distinct registries in the daemon memory:
needles/ Active work items and tickets. Subdirectories expose individual field values. decisions/ Historical decision logs, structured by slug. Documents justifications and timestamps. fleet/ Live agent registry enumerating active, stale, and dead agents. proc/ Detailed process table for active running workers. journal/ Append-only audit logs. Read to observe all kernel transactions. sys/ Kernel-internal caching states and graph index metrics. mem/ Working memory: context pages and capability pin boundaries. drivers/ Active device drivers and their declared capabilities. The Projection Lattice
To balance performance and token economy, the VFS exposes data at three distinct resolution layers:
A single property field. Ideal for tight agent polling loops and quick inline context.
$ cat .ostk/vfs/needles/1338/title
EPIC: Observation substrate over VFS namespace The complete JSON serialization of a single record.
$ cat .ostk/vfs/needles/1338/_object
{"id":1338,"title":"EPIC: Observation substrate...","priority":"P0","status":"open"} Enables directory walks, file searches, and piping.
$ ls .ostk/vfs/needles/ | wc -l
1413 Optimistic Concurrency Control (OCC)
Rather than locking files on open (which stalls parallel workflows), ostk uses monotonic generation counters and Compare-and-Swap (CAS) edits.
Every file's generation is tracked in .ostk/gen_table.jsonl. Successful writes increment the generation counter, providing an instant state signature.
A system-level flock(2) on .ostk/gen_table.lock wraps the generation lookup and modification loop. Concurrent writes are queued, avoiding lost updates.
On every generation bump, the pre-edit content is backed up to .ostk/shadows/<path_hash>/gen_<N>. This historic record is used to resolve conflicts if a subsequent write fails.
Write tools (like file:edit) pass the old content string. If the workspace version has changed, the write is blocked, triggering Hot PR conflict resolution.
Hot PR: Automated Merge Routing
When a write fails due to a mismatched generation signature, Hot PR attempts to merge the changes mechanically, without invoking expensive LLM rounds.
Edits occur in different, non-overlapping parts of the file. The kernel merges both changes automatically and silently.
Minor overlaps. The kernel computes a line rebase and returns a suggested edit call back to the agent for confirmation.
Large conflict. The write is rejected. The agent must re-read the file and manually re-apply its logic.
Peripheral Aware Digest & 304 Elision
Instead of querying files repeatedly, the agent checks the 5-line envelope appended to tool outputs. If a file is read unnecessarily, the kernel returns a 304 header.
[procs] Active peer agents and execution health. Enables cross-agent status checks. [presence] State glyph tracking arrivals and departures. [files] Modified file paths, generation tokens, and editing agent aliases. Unmodified files are omitted. [loadavg] Active tickets, P0 count, and pending messages. [meminfo] Token usage metrics and remaining context budget.
If an agent attempts to read an unmodified file (e.g. because it is missing from the [files] block), the kernel intercepts the operation and returns [304] path:gen=N (current). This avoids loading hundreds of lines of duplicate data into the context window.
Nudges: Cross-Boundary Interrupts
Nudges are durable, asynchronous messages pushed into an agent's next tool response context, bypassing the need for real-time IPC connections.
Local Nudges
Pushed into the local queue at .ostk/nudges/<agent-alias>.jsonl. The dispatch loop reads this queue on every step and appends pending messages into the target's next turn.
Cross-Host Nudges
Sent using the Files API, writing a nudge.uploaded event to the audit trail. Peer daemons scan the audit log, download the files, and insert them into their local queues.
Temporal Resiliency
Nudges are persistent on disk. If the daemon is restarted, the queue remains intact, ensuring that messages are not lost during kernel upgrades.
FUSE & VFS Operational Constraints
Because VFS relies on the host operating system's FUSE layers, operators should be aware of the following execution limits: