POSIX Kernel Specification

Abstract

This document specifies the POSIX-shaped semantics of the ostk kernel: a userspace coordination kernel whose on-disk surface (.ostk/) and process model are direct analogs of POSIX primitives. It defines the deadline contract on every blocking operation, the ownership record carried by every persistent artifact, the subreaper and supervisor lifecycle, the canonical signal table for cross-process coordination, the anchor-exclusivity invariant, and the handle-generation discipline that makes reused identifiers safe. The document is normative for the implementations of these properties shipped in ostk 4.5.0; properties not yet enforced by the implementation are listed separately in Appendix A as future work.

Status of This Memo

This document specifies behaviors that the ostk 4.5.0 reference implementation enforces today. It is a stable specification: revisions follow the procedure described in Section 10. Each normative requirement names an implementation site or test in the ostk source tree; readers verifying conformance can locate enforcement directly.

Properties that the implementation does not yet enforce, or enforces only partially, are listed in Appendix A and are explicitly non-normative. A future version of this document may promote those properties to normative status when the implementation catches up; conformance to this document does not require them.

Copyright Notice

Copyright (c) 2026 the ostk project. Distributed under the same terms as ostk itself. This specification may be reproduced and distributed in full, with copyright notice and disclaimer preserved.

Table of Contents

• 1. Introduction
  • 1.1. Requirements Language
  • 1.2. Terminology
  • 1.3. Document Structure
• 2. Architecture Overview
• 3. Process Model
  • 3.1. Anchors and Agents
  • 3.2. Lifecycle
  • 3.3. Process Identity
• 4. Invariants
  • 4.1. Invariant I: Bounded Wait
  • 4.2. Invariant II: Owned State
  • 4.3. Invariant III: Subreaper
  • 4.4. Invariant IV: Root Namespace Isolation
  • 4.5. Invariant V: Signal Table Closure
  • 4.6. Invariant VI: Anchor Exclusivity
  • 4.7. Invariant VII: Handle Lifetime Uniqueness
• 5. Syscall Surface
• 6. Examples
• 7. Conformance
• 8. Security Considerations
• 9. References
  • 9.1. Normative References
  • 9.2. Informative References
• 10. Revision Procedure
• Appendix A. Non-Normative Notes (Future Work)

1. Introduction

ostk is a userspace coordination kernel for fleets of LLM agents sharing a working filesystem. It re-implements many POSIX primitives under different names: an agent is a process, an alias is a pid, an audit row is a syscall trace, an event channel is a pipe, anchor.lock is a flock, an Agentfile is an exec image, dispatch is read/write, a session is a controlling terminal.

What ostk inherits from POSIX in name, it MUST also inherit in guarantee. POSIX delivers two cooperating layers below userspace: a correctness substrate (bounded waits, owned state, dead-process reaping, namespace isolation under test) and a composability layer (every resource has a path and a handle, every process has identity, every coordination is a numbered signal, every error is structured). Userspace inherits none of these by default.

This document specifies the invariants ostk imposes to obtain those layers, the supporting mechanisms that implement them, and the conformance criteria by which an implementation may be tested.

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Throughout this document, "the kernel" refers to the ostk kernel substrate (the in-process library and the supervising daemon), and "an implementation" refers to a build of the ostk source tree claiming conformance to this document. Statements without RFC 2119 keywords are descriptive.

1.2. Terminology

Owner.

The process — identified by (pid, started_at, build_id, host) — that wrote a piece of .ostk/ state.

Reap.

Atomic removal of state whose owner is dead, via rename(2) into the graveyard followed by deferred unlink.

Anchor.

The single per-project-root ostk daemon process holding .ostk/anchor.lock.

Supervisor.

A process (ostk init, launchd, or systemd) that owns a listening socket and is responsible for orphan reaping and anchor fencing.

Kernel RPC.

Any call into the ostk kernel from a client (CLI, MCP server, embedded agent loop, TUI).

Signal.

A numbered coordination primitive from the closed table defined in Section 4.5. ostk signals are NOT OS signals; they are envelope-level coordination delivered over the kernel UDS.

Handle generation.

A monotonic counter (gen) appended to every reusable handle ID such that (id, gen) uniquely identifies a resource instance across its entire lifetime.

Fencing token.

Monotonic token returned by the anchor on handle acquisition; subsequent operations that present a stale token are rejected.

1.3. Document Structure

Section 2 sketches the architecture. Section 3 defines the process model. Section 4 enumerates seven normative invariants. Section 5 specifies the syscall-shaped surface. Section 6 contains worked examples. Section 7 defines conformance. Section 8 lists security considerations. Section 9 collects references. Section 10 describes the revision procedure. Appendix A captures non-normative notes and future work.

2. Architecture Overview

An ostk deployment on a single host consists of:

• A project root — a directory containing a .ostk/ subdirectory, which holds all kernel state.
• An anchor — the single ostk daemon process per project root, holding .ostk/anchor.lock and serving kernel RPCs over a Unix domain socket.
• Zero or more agents — processes spawned under the anchor that perform work and write state.
• An optional supervisor (ostk init) — a long-running process that runs the subreaper loop, fences anchor-lock losers, and adopts orphaned agents. The subreaper role is also the boot-time scope of the anchor itself when no supervisor is present.

All kernel state is path-addressable under .ostk/. All cross-process coordination crosses one of two boundaries: the anchor's UDS (for kernel RPCs) or the journal (an append-only audit chain at .ostk/journal.jsonl). The kernel is auditable with jq, grep, and git; this is a design constraint, not an accident.

3. Process Model

3.1. Anchors and Agents

An implementation SHALL ensure that at most one anchor process holds .ostk/anchor.lock at any time per project root. Anchor lock acquisition is non-blocking (flock(LOCK_EX | LOCK_NB)); a process that observes the lock held SHALL either fail with a structured error or, where a supervisor is running, be fenced by the supervisor. Section 4.6 (Invariant VI) makes this normative.

Agents are spawned by the anchor and recorded in .ostk/fleet/. Each spawned agent has a unique alias and an AgentHandle carrying its identity. The relationship between alias, handle, and the underlying process is governed by Invariants II and VII.

3.2. Lifecycle

Each agent passes through a documented lifecycle. An implementation SHALL emit an audit row at each transition:

• spawning → spawned → running
• running ↔ frozen (entered on SIGFREEZE; exited on SIGRESUME)
• running → exiting → reaped

Signals delivered to an agent in state spawning SHALL be queued and dispatched on the transition to spawned. Signals delivered to an agent in state exiting or reaped SHALL return SignalTargetGone. SIGRESUME SHALL be dispatched immediately to an agent in state frozen; SIGKILL SHALL bypass the queue per its uncatchable semantics. See Section 4.5.

3.3. Process Identity

Every agent carries an Owner record — (pid, started_us, build_id, host) — that uniquely identifies the writing process across its entire lifetime, including across PID reuse. The pair (pid, started_us) defeats PID-reuse races: a recycled PID has a different proc_start_micros, so liveness checks fail closed.

The full Unix process-identity quad (pid, ppid, pgid, sid) is described as future work in Appendix A.1: the implementation currently records pid and ppid via the Owner record but does not yet thread pgid/sid through every audit row.

4. Invariants

An implementation conforming to this document SHALL satisfy each of the seven invariants in this section. Each invariant is given a short name, a normative statement, a non-normative rationale, a non-normative consequence (when violation has system-level impact), and one or more illustrative examples.

{
    "op":          "agents.spawn",
    "deadline":    "2s",
    "elapsed":     "2.013s",
    "holder":      {"pid":12345,"started_us":1761539600123456},
    "remediation": "kill 12345"
}

# ostk-owner v1 pid=<pid> started_at=<ISO8601> build_id=<hex16> host=<hostname>
# ostk-owner-end
<file content>

kill_zero(self.pid)
    && proc_start_micros(self.pid) == Some(self.started_us)

5. Syscall Surface

The kernel exposes a small set of structured errors and a deadline-bearing RPC contract. The error surface is normative; alternative implementations satisfying the same invariants MAY use different error names but MUST preserve the field semantics.

pub enum KernelError {
    Deadline(DeadlineError),                                          // §4.1
    StaleOwner { path, owner, remediation },                          // §4.2
    Unowned { path, remediation },                                    // §4.2 migration
    Reaped { path, owner, when },                                     // §4.3
    NoStateDir { remediation },                                       // §4.4
    StateDirCrossFilesystem { path, remediation },                    // §4.4
    SignalUnknown { name, table },                                    // §4.5
    SignalTargetGone { target, last_owner },                          // §4.5 lifecycle
    AnchorFenced { winner_pid, remediation },                         // §4.6
    AnchorEpochStale { client_epoch, server_epoch, remediation },     // §4.6
    HandleStale { handle_id, seen_gen, current_gen },                 // §4.7
    OperationRetryable { new_socket, new_epoch },                     // §4.6
}

The mapping from kernel-level requirements to underlying OS primitives is:

6. Examples

The examples in this section are illustrative. Exact CLI surface is governed by the kernel ABI and may evolve; see Section 1.2.

Example 1: reading state with a dead owner.

let raw = fs::read(&path)?;
let (header, body) = parse_owner_header(&raw)?;          // §4.2 parse
if !header.is_alive() {                                    // §4.2 check
    reap_one(&path)?;                                    // §4.2/§4.3 rename
    return Err(KernelError::Reaped { path, owner: header, when: now() });
}
Ok(body)

Example 2: bounded RPC with deadline.

let resp = client
    .call("agents.spawn", payload, Duration::from_secs(2))   // §4.1
    .await?;
verify_anchor_epoch(&resp)?;                                 // §4.6

Example 3: signal table inspection.

The closed table is exposed by the kernel; an unknown signal name returns a structured error including the canonical table:

SignalUnknown {
    name: "SIGFOO",
    table: [
        ("SIGCANCEL", 1), ("SIGREDIRECT", 2), ("SIGRELOAD", 3),
        ("SIGFREEZE", 4), ("SIGRESUME", 5),  ("SIGHUP", 6),
        ("SIGQUOTA", 7),  ("SIGBAIL", 8),    ("SIGSTOP", 9),
        ("SIGTERM", 15),  ("SIGKILL", 63),
    ],
}

Example 4: handle generation.

// Client cached alias "alpha" at gen=3.
match validate(&state_dir, "agent", "alpha", 3) {
    Ok(()) => /* still gen 3; safe to use */,
    Err(KernelError::HandleStale { seen_gen, current_gen, .. }) => {
        // resource was reaped and recreated; current_gen > seen_gen
    }
    Err(other) => return Err(other),
}

7. Conformance

An implementation conforms to this specification when it satisfies every normative (MUST / SHALL / REQUIRED) statement in Sections 1 through 5. Statements using SHOULD / RECOMMENDED are non-normative guidance; statements in Appendix A are non-normative future work and are not part of conformance.

Conformance is partitioned into two levels:

• Core Conformance. Sections 4.1 (Bounded Wait), 4.2 (Owned State), 4.3 (Subreaper), 4.4 (Root Namespace Isolation), and 4.7 (Handle Lifetime Uniqueness). The reference implementation enforces these in src/kernel/deadline.rs, src/kernel/ownership.rs, src/kernel/init_subreap.rs, src/util/paths.rs, and src/kernel/handle_gen.rs respectively.
• Extended Conformance. Sections 4.5 (Signal Table Closure) and 4.6 (Anchor Exclusivity). The reference implementation enforces these in src/kernel/signals.rs and src/kernel/anchor.rs respectively. Extended Conformance subsumes Core Conformance.

The journal verification primitive at ostk audit verify is the canonical conformance test surface for the audit-chain properties referenced in Sections 4.2 and 4.3: an implementation under test SHOULD be exercised against a synthetic incident, and ostk audit verify SHOULD return a clean result on the recovered state. The verification primitive is implemented at src/commands/journal.rs.

An implementation that claims conformance SHOULD list the source-tree paths that enforce each invariant in its release notes; readers verifying conformance can audit those paths directly.

8. Security Considerations

8.1. Threat Model.

This document specifies a single-host coordination kernel. The threat model assumes (a) the local user is trusted with respect to their own .ostk/; (b) other local processes outside the trust boundary may attempt to cause hangs, lock contention, or audit-chain corruption; (c) operating-system features (file permissions, process isolation, filesystem semantics) are reliable.

8.2. Properties This Specification Addresses.

• Resource exhaustion via hangs. The Bounded Wait invariant (Section 4.1) ensures every kernel operation has a deadline, eliminating the indefinite-block class.
• Stale-state corruption. Owned State (Section 4.2) ensures that any artifact whose creating process is dead is reaped before re-use. (pid, started_us) ownership defeats PID-reuse races.
• Test-substrate contamination. Root Namespace Isolation (Section 4.4) prevents test processes from corrupting the live .ostk/ by failing closed when an explicit root is not provided.
• Concurrent-anchor split-brain. Anchor Exclusivity (Section 4.6) ensures that at most one anchor holds the lock per project root; concurrent attempts are either rejected or fenced. Per-response anchor_epoch closes the zombie-anchor mid-stream window.
• Stale-handle confusion. Handle Lifetime Uniqueness (Section 4.7) ensures cached handle identifiers cannot silently address the wrong resource: HandleStale is raised on any post-reap reuse.

8.3. Properties This Specification Does NOT Address.

The following are out of scope and are addressed by other specifications, or are explicitly future work:

• Cross-host coordination. Federation across hosts requires a separate trust and transport model.
• Distributed consensus. No quorum protocol is specified; single-host guarantees only.
• Capability-pin escapes. Capability-pin enforcement and policy are documented in companion documents on the trust model and capability pins; this specification only requires that pin enforcement integrates with the audit journal.
• Audit-chain signing and key rotation. The journal hash chain is specified here; signing keys, rotation, and revocation are governed by the attestation envelope (OAE) specification, not this document.
• Identity spoofing within a single trust graph. Out of scope; the trust model document handles identity tier graduation and revocation.
• Replay attacks. The kernel relies on the journal's hash chain plus per-response anchor_epoch to detect replay across anchor rotations; cross-host replay is not in scope.
• Network attackers. No network surface is specified; clients connect to the kernel via local Unix domain sockets.

8.4. Known Gaps.

The full POSIX process-identity quad (pid, ppid, pgid, sid) is not yet enforced on every audit row (see Appendix A.1). Consumers that require process-group-level kill semantics SHOULD treat process-group operations as best-effort until that work lands. The Connection Continuity property described in Appendix A.3 is partially implemented as the OperationRetryable error variant; transparent client reconnection is not currently a kernel guarantee.

9. References

9.1. Normative References

• [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, https://www.rfc-editor.org/info/rfc2119.
• [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017, https://www.rfc-editor.org/info/rfc8174.
• [POSIX.1-2024] IEEE and The Open Group, "IEEE Standard for Information Technology — Portable Operating System Interface (POSIX) Base Specifications, Issue 8", IEEE Std 1003.1-2024.
• [ostk-source] ostk reference implementation, https://github.com/os-tack/ostk.ai. Sections cited above point at file paths in this tree.

9.2. Informative References

• Linux pidfd_open(2), pidfd_send_signal(2) — kernel 5.3+.
• FreeBSD / macOS kqueue(2), EVFILT_PROC with NOTE_EXIT.
• flock(2), fcntl(2) — advisory file locking.
• systemd.socket(5) and launchd.plist(5) — supervisor-owned listening sockets.
• FUSE: libfuse(3), the Rust fuser crate.
• Kleppmann, M., "How to do distributed locking" (2016) — fencing tokens.
• Plan 9 from Bell Labs — "everything is a file" namespace doctrine.
• FreeBSD capsicum(4) — capability-mode filesystem access.
• Companion ostk specifications: Kernel Specification, Five Laws, Coordination Primitives, Trust Model.

10. Revision Procedure

This document is versioned alongside the ostk reference implementation. A revision SHALL bump the document version, list the substantive changes, and (where the change is normative) cite the implementing change in the source tree. Revisions that promote an Appendix A entry to a normative section SHALL be accompanied by tests demonstrating enforcement.

Revisions that retract a normative requirement SHALL document the prior wording in an "Acknowledged Failure Modes" entry so the public record of the kernel's design errors remains intact.

Appendix A. Non-Normative Notes (Future Work)

This appendix collects properties described in the working draft that are not yet enforced by the ostk 4.5.0 reference implementation. Conformance to this document does not require any of the following. A future revision MAY promote these to normative sections.