# shell/ — nash, the Nucleic agent shell

Design doc: [docs/NASH.md](../docs/NASH.md). Vendored fork base:
[`third_party/brush/`](../third_party/brush/) (brush, pinned at
`brush-shell-v0.4.0`; fork patches are marked with `// nash:` comments).

Status (NASH.md): **M0–M2 complete**; M3's image + host work ships via narOS N2/N3 —
`naros-agent` bakes the `/bin/sh` divert and `Project.swift` pins it — with the M3
*gates* (in-image corpus parity, <3% overhead, a clean dogfood week) still pending.

- `nash/` — the shell binary. More than the M0 embedding now: it loads the trusted,
  root-owned operator policy (`policy.rs`, NASH.md §4.3 — kill switch, real-bash
  target, `require_observation`), installs the `nash-observe` gate, flushes events at
  exit, and applies the compat fallback for `-c` input brush can't parse, deferring to
  brush for everything else.
- `nash-observe/` — shipped: the `brush_core::gate::Gate` impl, shell-batch event model,
  data-flow taps with caps/redaction, near-live batching, and the transport chain (unix
  socket → HTTP → JSONL spool). Events reach the app's feed and land durably in the
  `nash_event` table (`GRDBMetadataStore+NashEvents`).
- `naros-init/` — narOS PID-1 supervisor for container surfaces (NAROS.md §5): reaps
  zombies, forwards SIGTERM/SIGINT, supervises a primary command as the container
  entrypoint (`naros-init -- CMD …`, exiting with its status) or acts as the keepalive
  when given none, and under `NAROS_BRIDGE=1` also restarts the control bridge with
  backoff. Shipped as a Debian package by `os/packages/`.
- `corpus/` — transcript-replay compat harness: `replay.py` runs every command
  in `corpus.jsonl` under bash and nash in identical fresh workspaces and diffs
  exit/stdout/filesystem (stderr reported separately). Divergences are tracked
  in `corpus/DIVERGENCES.md`.

Build & test:

```sh
cargo build --release                      # binary: target/release/nash
python3 corpus/replay.py --nash <path>     # M0/M3 gate: >= 99% parity
```