Coordination Primitives
Shared local state makes coordination inspectable: durable records live on disk, selected live state can be projected through the VFS, and kernel-mediated CAS edits either compose safely or surface the conflict. Native writes still use ordinary filesystem and Git coordination.
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)
Kernel-mediated fs_ops edits use expected text as the direct CAS condition. A short-lived target-file lock serializes each mutation; generation history is consulted only when the expected text is no longer present.
Files written through tracked kernel paths receive monotonic entries in .ostk/gen_table.jsonl. Successful writes bump the generation; native and raw-shell writes do not automatically join that history.
An exclusive flock(2) on the target stays held while current bytes are checked and any successful mutation commits. The generation table uses its own shorter lock for metadata updates; it does not wrap the entire file mutation.
A successful tracked write records generation history and a shadow of the prior content. That recorded base is consulted on a later zero-match CAS request to distinguish a safe non-overlap from a nearby or structural conflict.
fs_ops passes the expected old text. Exactly one occurrence takes the direct path; more than one stops as ambiguous; zero occurrences alone trigger comparison against the recorded base.
When Expected Text Is Stale
If the expected text occurs zero times, ostk compares the request with the recorded base. The recovery path either prepares a deterministic non-overlapping merge, returns a nearby mechanical suggestion without writing, or reports a visible conflict.
The requested edit and intervening change do not overlap. The kernel can prepare and commit a deterministic merged result.
A deterministic rebase can be suggested to the agent for confirmation. The suggestion itself does not write.
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: