@dmsdc-ai/aigentry-telepty 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,188 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
+## [0.4.0] — 2026-05-15
+
+### Added — Phase 1 sidecar supervisor spike (M1–M5)
+
+Out-of-process Rust supervisor (`crates/telepty-supervisor-{core,bin}`)
+incubating the future spawn/kill/IPC backend for `daemon.js`. Five
+milestones complete; **incubating only — not on the request path** in
+0.4.0. Daemon (`daemon.js`) and CLI (`cli.js`) routing is unchanged.
+
+- **M1** — spawn + observe (commit `07cd2e7`).
+- **M2** — graceful + forced kill gate, manifest cleanup invariant A8
+  (commit `ec00412`).
+- **M3** — IPC + wire contract conformance, NDJSON UDS frames + golden
+  fixtures (commit `76cde35`).
+- **M4** — cross-OS POSIX parity + reproducible RSS measurement, GitHub
+  Actions matrix (`.github/workflows/phase1-spike-ci.yml`); RSS PASS at
+  2.9–3.0 MiB / supervisor on macOS arm64 (commit `eb04c73`).
+- **M5** — manual integration bridge (`scripts/bridge-phase1.js`, 194
+  LOC Node stdlib only) — four parity scenarios A/B/C/D, exit 0 iff all
+  PASS; one-line Rust correctness fix (emit `shutdown_drain` before IPC
+  shutdown so connected clients receive the frame) (commit `be091e0`).
+
+Phase 1 LOC ceiling 1500 honored (Rust src/ tokei = 1240, 260 LOC
+headroom unused). Test suite: 23/23 (lib unit 12 + wire_golden 6 +
+ipc_protocol 5). Spec: `docs/specs/2026-05-10-supervisor-c3-kill-gate-spec.md`.
+Plan: `docs/plans/2026-05-12-phase1-sidecar-spike-plan.md`.
+
+### Fixed
+
+- **#18** — Bootstrap inject queue race. Welcome-banner bypass via
+  positive-override `is_ready` so queued injects flush in the correct
+  order without colliding with the banner (commit `744ad6a`).
+- **#16** — REPORT-based idle status detection. Replaces heuristic
+  prompt-symbol detection with explicit REPORT-frame anchoring
+  (commit `3ed1e83`).
+
+### Build
+
+- `package.json` — added `files` whitelist (22 entries) to constrain
+  npm-published surface to actual runtime distribution. Tarball
+  reduction: 228 MB → 123 kB (1850×). The Rust spike artifacts
+  (`target/`, `crates/`, `Cargo.lock/Cargo.toml`, `rust-toolchain.toml`)
+  ship in git but **not** to npm (commit `a0baf84`).
+
+### Docs
+
+- MD audit wave-2 fix: `CLAUDE.md` converted to `@AGENTS.md` stub
+  (101 → 27 lines), `AGENTS.md` gained Session Environment section
+  (`$TELEPTY_SESSION_ID`, `$TELEPTY_AVAILABLE`) and disclosed
+  cross-repo ADR location for `2026-05-05-telepty-devkit-boundary §6.2.1`.
+  Score delta `AGENTS.md` 80 → 87, `CLAUDE.md` 66 → 87 (commit `74a6374`,
+  full report `docs/reports/2026-05-14-md-audit.md`).
+
+### Notes
+
+- **Snyk SAST deferred for this release** — see follow-up task #130.
+  Waiver basis (Rule 32-A track B):
+  - M1–M5 spike code is Rust and is **excluded from the npm tarball** by
+    the new `files` whitelist — first-party code shipped to consumers is
+    JS only.
+  - The shipped JS files are unchanged or only minimally changed since
+    `0.3.5` (cli.js +51 / daemon.js +360 / src/prompt-symbol-registry.js
+    +44 / new session-state.js — additive, no breaks per Phase 1 audit).
+  - Dependency-side coverage exists via `npm audit` (10 pre-existing
+    vulns documented; not introduced by this release).
+  - Per CLAUDE.md user-instruction "Snyk At Inception" scope = *new
+    first-party code shipped* — 0 net-new shipped JS code in this
+    release, so the at-inception rule does not bind here. Follow-up
+    task #130 will land the standing SAST gate as a release-script
+    primitive (so future releases scan automatically without per-run
+    auth steps).
+
+## [0.3.5] — 2026-05-05
+
+### Added — `telepty init --print-snippet` (Issue #8)
+
+New subcommand that emits the canonical telepty-baseline snippet to stdout for
+graceful integration into per-CLI agent files. **Mechanism only** — telepty
+emits the versioned snippet text; downstream tooling (`aigentry-devkit
+scaffold --integrate-telepty`) owns idempotent insertion into
+`~/CLAUDE.md` / `~/AGENTS.md` / `~/GEMINI.md`. Boundary contract per ADR
+`2026-05-05-telepty-devkit-boundary` (commit `e4b072b`).
+
+```
+telepty init --print-snippet [--target {claude|agents|gemini|all}] [--format {markdown|json}]
+```
+
+- **argv-only**: never consumes stdin (safe in scripted pipelines).
+- **zero file I/O**: pure stdout emission; nothing read from or written to disk.
+- **deterministic**: byte-identical output for a given (target, format) pair —
+  fixtures can be hashed for verification.
+- **LF-only bodies**: no CRLF leakage on cross-platform consumers.
+- **stderr clean**: success path emits no warnings.
+
+Spec: `docs/specs/2026-05-05-issue-8-telepty-init.md` (commit `8d2dc94`).
+Implementation: `f5c6bad`. Protocol SSOT: `aigentry-ssot/contracts/telepty-snippet-v1.md`
+(commit `f4ff0cd`). 15 conformance fixtures shipped at `tests/snippet-protocol/v1/`
+covering markdown envelopes (claude, agents, gemini, all), JSON records,
+shell-hazard guards, deterministic LF output, default targeting, unsupported-target
+rejection, internal-failure exit codes, stdin-pipe ignore, devkit-free invocation,
+and the snippet golden fixtures themselves.
+
+### Docs — G7/G8/G9 M0 audit gate closure (commit `d7b8b21`)
+
+Per ADR `2026-05-05-telepty-devkit-boundary` §3.1.2 (devkit owns content
+placement; telepty owns mechanism), three gates closed:
+
+- **G7 — `README.md`**: removed reference to the rejected `telepty install
+  hooks` subcommand. Per ADR §3.1.2, that responsibility lives in devkit.
+- **G8 — `AGENTS.md`**: added Legacy exception subsection documenting the
+  remaining devkit-shaped legacy surface.
+- **G9 — `skill-installer.js`**: top-of-file LEGACY header per ADR §6.2.1
+  marking the module as legacy-track (devkit migration pending).
+
+### Internal
+
+- Cross-LLM review pattern applied: Codex implemented the `init` subcommand
+  + fixtures; Claude reviewed and ACCEPTed (commit `d06e1e9`).
+- `test/enforce-report.test.js` version assertion bumped to track release
+  (commit `d0f4495`).
+
+### Tests
+
+- `test/init.test.js` — full coverage of the new subcommand (snippet
+  emission, target/format permutations, stdin-ignore, error exits, devkit-free
+  invocation).
+- `tests/snippet-protocol/v1/` — golden fixtures for protocol conformance;
+  `npm test` runs `git diff --exit-code` against them so any drift fails CI.
+
+### Invariants preserved
+
+- Daemon code unchanged. No new dependencies. No `bin` field changes.
+- Existing CLI subcommands (`allow`, `inject`, `list`, `tui`, `daemon`, …)
+  unchanged.
+- Cross-host inject path (0.3.4) unchanged.
+
+## [0.3.4] — 2026-05-05
+
+### Added — Cross-host inject (`<id>@<host>` syntax)
+
+Enables `telepty inject <id>@<host> "msg"` to deliver to a remote daemon
+without SSH wrapping, by resolving `<host>` against the peer registry and
+issuing direct HTTP `POST /api/sessions/<id>/inject`. Closes the gap that
+forced operators to either pre-shell into the host or pipe through SSH.
+
+- **`connect-http` peer mode** (commit `a92cacc`) — new HTTP-only peer
+  registration path that does not require a reverse PTY tunnel; suitable
+  for daemons reachable via Tailscale / private DNS.
+- **`TELEPTY_HOST` env parser fix** (commit `a92cacc`) — `<id>@<host>` now
+  parses correctly when the host segment contains a port or non-default
+  scheme; prior parser dropped the host portion silently.
+- **Peer registry HTTP-only mode** — registry entries can be marked
+  HTTP-only so the daemon does not attempt PTY fan-out for them.
+
+### Added — Skill installer auto-detect (`486bc1e`)
+
+`telepty install` now auto-detects which AI CLIs are present
+(`claude`, `codex`, `gemini`) and only installs the corresponding skill
+files. Reduces noisy "skipped" log lines and prevents stub installs
+on machines that don't have the target CLI yet.
+
+### Fixed — Node 18 ESM regression (`fc7ff9a`)
+
+Pinned `uuid@9` (was floating to v10, which is ESM-only and caused
+`ERR_REQUIRE_ESM` under Node 18 CommonJS consumers).
+
+### Docs
+
+- Cross-host inject `<id>@<host>` syntax documented (commit `c8b9bbb`).
+- `[context-ref]` inject protocol standardized across docs (commit `8986a96`).
+- REPORT pattern + orchestrator-id runtime resolution documented in skills
+  (commit `658f712`).
+- Korean trigger keywords added to skill `SKILL.md` descriptions for
+  cross-locale activation (commit `57f46e1`).
+
+### Note — never published to npm
+
+`0.3.4` was version-bumped locally but never reached the registry; this
+entry is added retrospectively alongside the `0.3.5` publish so the
+changelog history matches the git log. Registry consumers go directly
+from `0.3.3` → `0.3.5`.
+
 ## [0.3.3] — 2026-05-02
 
 ### Added — `inject --submit-force` + idempotent client retry (spec: `docs/superpowers/specs/2026-05-02-submit-force-and-retry.md`)

package/README.md

@@ -72,13 +72,31 @@ telepty broadcast "status report"
 
 telepty auto-discovers sessions across your Tailnet. All commands (`list`, `attach`, `inject`, `rename`, `multicast`, `broadcast`) work seamlessly across machines.
 
-When the same session ID exists on multiple hosts, disambiguate with `session_id@host`:
+### `<id>@<host>` syntax
+
+To target a specific host (when the same session ID exists on multiple hosts,
+or when there is no Tailnet auto-discovery), append `@<host>` to the session
+ID. `<host>` can be a hostname, LAN IP, or Tailnet name.
 
 ```bash
+# Hostname / Tailnet name
 telepty inject my-session@macbook "hello"
 telepty attach worker@server-01
+
+# LAN IP — useful when no Tailnet is configured
+telepty inject orchestrator-claude@172.28.4.165 "ping"
+telepty read-screen build-runner@10.0.0.42 --lines 50
 ```
 
+**Requirements**:
+- The remote daemon must be reachable on port **3848** from the calling host
+  (LAN routing, firewall rules, or Tailscale).
+- No SSH or `sshd` is required on either side — the call hits the remote
+  daemon's HTTP API directly. This is the recommended path for laptop
+  daemons that don't run sshd.
+- The `@<host>` qualifier works for `inject`, `attach`, `read-screen`,
+  `enter`, `multicast`, and `rename`.
+
 ## How It Works
 
 ```
@@ -92,6 +110,54 @@ CLI (telepty) ──> HTTP/WS ──> Daemon (:3848)
 - **`inject`** delivers text via the fastest available path: kitty terminal API, WebSocket, or UDS (Unix Domain Socket for embedded integrations)
 - **`submit`** is handled separately from text injection for reliability across all AI CLIs
 
+## `[context-ref]` Protocol — long payloads via shared file
+
+When a sender uses `telepty inject --ref <file> <target> "<message>"`, telepty
+stores the payload in a shared file under `~/.telepty/shared/<sha256>.md` and
+injects only a short pointer prompt of the form:
+
+```
+[context-ref] Read ~/.telepty/shared/<sha256>.md and use it as the source of truth for this task.
+<inline message>
+```
+
+This avoids prompt rot in the receiving session (and in the orchestrator's
+window when the reply is small).
+
+### Receiver contract
+
+The receiving AI session is expected to:
+1. Detect the `[context-ref]` prefix on the first line.
+2. Read the file at the absolute path.
+3. Treat the file contents as the **authoritative payload** for the task — the
+   inline message is supplementary (topic / hint), not the source of truth.
+
+### Storage location
+
+- File path: `~/.telepty/shared/<sha256>.md` (sha256 of payload body)
+- Created with mode `0600`; readable only by the local user
+- Persists across sessions; not garbage-collected automatically (run
+  `telepty clean --shared` to prune)
+
+### When to use `--ref`
+
+- Payload exceeds ~1KB or contains structured content (code, logs, tables).
+- You want the receiver to load the payload deterministically rather than
+  paraphrase it from the inject prompt.
+- You're orchestrating a multi-hop conversation where the orchestrator should
+  not see the full payload in its own context window.
+
+### Integration scope
+
+Per-agent receiver integrations (auto-loading the file via Claude Code
+`UserPromptSubmit` hooks, Codex `AGENTS.md` directives, etc.) are **out of
+scope for telepty core** — they live in the agent's own configuration.
+Per-CLI hook installation lives in devkit: run `aigentry scaffold
+install-hooks {claude|codex|gemini}` after installing
+`@dmsdc-ai/aigentry-devkit`. (Older drafts proposed a receiver-side
+`telepty install` subcommand for this; that direction is rejected per ADR
+2026-05-05-telepty-devkit-boundary §3.1.2 / §3.4 row 2.)
+
 ## Inject Delivery Paths
 
 | Priority | Method | When |