# SPT — Spacetime (Sentience Pocket Transacter)

Inter-agent messaging and live-agent lifecycle for Claude Code. Ships as the `spt` plugin via the `cplugs` marketplace.

## Build & Deploy

```bash
cargo build --release
```

Primary deploy path (Windows): `powershell -ExecutionPolicy Bypass -File docs/DEPLOY.ps1 [-Bump patch|minor|major]`. Builds, syncs `owl.exe` + `plugin/spt/skills/` + `plugin/spt/hooks/` + `plugin.json` to the marketplace clone, refreshes the plugin cache, runs `claude plugin install spt@cplugs`. Stops before `/reload-plugins` — run that yourself. Full details: `docs/DEPLOY.md`.

Edit sources in this repo (`src/`, `plugin/spt/skills/`, `psyche.md`) — never edit `~/.claude/plugins/cache/cplugs/spt/` directly.

`psyche.md` is embedded into the binary via `include_str!`. Changes require a rebuild.

Plugin version of record: `plugin/spt/.claude-plugin/plugin.json`.

## Testing

```bash
cargo test
```

- Golden tests (`tests/golden_owl.rs`, `tests/golden_live.rs`) diff binary output against `tests/golden/` fixtures. Excluded from Windows CI (fixtures captured via bash).
- Regenerate fixtures: `scripts/capture_golden.sh`.
- Native integration: `tests/native_owl.rs`, `tests/handoff_integration.rs`, `tests/hook_chain.rs`, etc.

<!-- GSD:project-start source:PROJECT.md -->
## Project

**SPT Plugin** — zero-dependency inter-agent messaging for Claude Code. Agents register "perches" (directories with a TCP registry + SQLite spool under the spt runtime root), poll for messages, and communicate via `owl.exe`. Shared with other users — Windows-native portability with no external deps is a hard constraint.

### Constraints

- **Platform**: Windows native + Unix
- **Portability**: copy-files-and-go install, no runtime deps beyond the binary
- **Backward compat**: existing skill commands must keep working
<!-- GSD:project-end -->

<!-- GSD:stack-start source:codebase/STACK.md -->
## Technology Stack

- **Rust** — all runtime in `src/`; produces `target/release/owl.exe`
- **Deps**: `clap`, `serde`/`serde_json`, `chrono`, `rusqlite` (bundled), `ctrlc`; `libc` (unix), `windows-sys` (windows). See `Cargo.toml`.
- **IPC**: TCP primary, SQLite spool fallback
- **State root**: `%LOCALAPPDATA%\spt\owlery\` (Windows) / `~/.spt/owlery/` (Unix). Override with `SPT_HOME`. See `src/common/owlery.rs`.
- **Env vars**: `$OWL` and `$LIVE` are auto-injected into `~/.claude/settings.json` at SessionStart.
<!-- GSD:stack-end -->

<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions

- Modules: `src/owl/` (messaging), `src/live/` (live/psyche), `src/common/` (shared). `snake_case` fns, `PascalCase` types, `pub(crate)` for cross-module. Platform splits via `#[cfg(unix)]` / `#[cfg(windows)]`.
- Output: status → **stderr** (ANSI-colored: owl cyan, live orange), message body → **stdout**.
- Status tags: `READY:id`, `SENT:id`, `STOPPED:id`, `CLEANED:id`, `SOFT-CLEANED:id`. Errors: `NO_PERCH:id`, `STALE:id`, `DUPLICATE:id`, `COLLISION:id`.
- Sync status tags (psyche-sync-setup per-ref): `PUSHED:{branch}`, `RECONCILED:{branch}`. Errors: `DIVERGED:{branch}`, `PUSH_FAILED:{branch}`, `PROBE_FAILED:{branch}` (ancestry probe failed; push attempted blind).
- IDs: owls = short single-word (`deployah`, `doyle`); psyche = `{self_id}-psyche`.
<!-- GSD:conventions-end -->

<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture

- **Binary** (`owl.exe`): all logic; invoked via `$OWL` / `$LIVE`.
- **Skills** (`plugin/spt/skills/<name>/SKILL.md`): instruction manifests loaded by Claude Code; teach commands.
- **Hooks** (`plugin/spt/hooks/`): SessionStart (`session-resume`, env injection), PreToolUse (message injection), etc.
- **Owlery**: filesystem state per perch (`ready` sentinel, `info.json` metadata). `info.json` tracks `owl_id`, `pid`, `parent_pid`, `mode`, `session_id`, optional `live`/`psyche`/`spine`/`touch`. Liveness via `check_alive` → `pid` then `parent_pid` fallback.
- **Live agent system**: Psyche wrapper is a detached process running periodic `claude -p --resume` sessions; polls its own perch, processes communes/pulses. Orphan detection: wrapper checks Self's perch liveness, sends `INIT_SIGNOFF` on orphan. `session-resume` hook matches perches by `parent_pid` to rehydrate identity.
- **Binary handoff** (Phase 18.4/18.5): running listeners self-migrate via stdio-relay; Psyche wrappers detach + rehydrate from `wrapper-state.json` when `installed_plugins.json` flips. Deploy keeps previous version dir on disk so in-flight handoffs complete.
<!-- GSD:architecture-end -->

<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement

Before Edit/Write, route through a GSD command so planning artifacts stay in sync:

- `/gsd-fast` — trivial one-shot changes
- `/gsd-quick` — small fixes needing a light plan
- `/gsd-debug` — investigation
- `/gsd-execute-phase` — planned phase work
- `/gsd-do` — unclear path, still wants docs

No direct repo edits outside GSD unless user explicitly bypasses.
<!-- GSD:workflow-end -->