Headless · Pear Terminal / Bare · planned

Headless App

Pear Terminal / Bare · planned

Headless Overview

Not implemented yet. Planned as an always-on personal server that runs on a device the user owns (Raspberry Pi, mini PC, NAS) and acts as a durable personal peer — not a central cloud service.

Role

Run as a long-lived owned peer that persists the same Autobase/Corestore data model, helps devices reconnect, and later coordinates with relay/storage dongles.

First milestone

Create/join invites; expose peer count, sync state, base identity, and storage status; CLI for setup, status, invite, join, export, and shutdown; and a P2P owner-control command/event channel for trusted clients.

Capabilities (opt-in at setup)

Bootstrap helper, replication helper, storage helper, async message helper, notification/reconnect helper, and diagnostics helper — each chosen during first-run setup so the device only enables the roles the owner wants. Under the current substrate, content-access roles must be treated as trusted full-participant roles; blind storage/relay helpers should receive no list encryption key.

Security gates

Require pairing/auth for control operations and never expose raw control endpoints publicly by default. The owner-control admin channel needs signed per-device capabilities, replay protection, owner-authorized membership, and key-rotation design before implementation (see review findings C1–C3, H1).

Status: The listam-headless repository is currently empty. See the Multi-App Plan for owner-control, the co-invite flow, and the review findings (C1–C3, H1) that must be resolved first.
Verification

Testing

How an implementation agent tests the headless server and proves it interacts with mobile and desktop. See also the implementation plans and the security findings.

Unit

Backend service logic behind the Node runtime port (no BareKit globals); the apply reducer; owner-signed membership verification (C3); corruption quarantine/recovery (M4); redaction (M5).

Integration

CLI (setup/status/invite/join/export/shutdown); owner-control auth — signed accepted, unsigned/expired/replayed/out-of-scope rejected, capability scope, device revoke (H1); a blind helper never receives the encryption key (C2); queue/storage quotas.

Soak

A long-lived peer stays up for hours with bounded storage/queue; restart preserves identity, storage, and status.

How to run

node headless.mjs --storage <dir> --bootstrap <addr> from the listam-headless repo; script invite/join against a second headless or a desktop instance; runs headlessly in CI.

Interaction: Headless is the always-on peer central to the cross-instance matrix: mobile ↔ headless (stays online while mobile closed, accepts generated/edited/deleted content, reopen → sync), desktop ↔ headless content-operation sync, the 3-way convergence test, and the security rows — non-owner add-writer ignored (C3), blind-storage cannot decrypt (C2), owner-control replay rejected (H1).