@dmsdc-ai/aigentry-telepty 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,391 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
+## [Unreleased]
+
+## [0.4.5] - 2026-05-26
+
+### Fixed — Stale-daemon, restart-recovery, force-bypass, codex matcher (tasks #469 #470 #471 #472)
+
+- **#469 — npm postinstall hook restarts a stale daemon (`scripts/postinstall.js`).**
+  `npm install -g @dmsdc-ai/aigentry-telepty@X` previously overwrote files but
+  never signalled the running `telepty-daemon`, so the daemon kept executing
+  the previously-loaded code (observed: PID 3222 ran 22 days through 4
+  upgrades). The new postinstall script reads `~/.telepty/daemon-state.json`,
+  compares the running daemon's reported version to the just-installed
+  `package.json` version, and on mismatch invokes the existing
+  `cleanupDaemonProcesses()` primitive plus a detached respawn. Skips on
+  `TELEPTY_SKIP_POSTINSTALL=1` and on non-global installs
+  (`npm_config_global!=='true'`).
+- **#470 — daemon restart re-bootstraps existing sessions
+  (`daemon.js` `runStartupBootstrapRestore()`).** After a daemon restart,
+  persisted-and-restored sessions remained `ready:false` indefinitely because
+  the bootstrap prompt-symbol probe only fired on owner-WebSocket reconnect.
+  On startup, each restored gated session whose `ownerPid` is still alive is
+  now actively probed (cmux path) or optimistically marked ready (non-cmux
+  path), with the chosen reason recorded for log attribution. Sessions whose
+  owner process is dead remain unready, matching the prior unready semantics.
+- **#471 — `force: true` bypasses the bootstrap gate (`daemon.js:1969`).**
+  The per-request `force` escape hatch (`cli.js --submit-force`,
+  `TELEPTY_SUBMIT_FORCE_DEFAULT=1` from 0.4.4) was parsed correctly but the
+  bootstrap gate enqueued it and returned 504 long before the force-bypass
+  block at L1998 could run. Surgical 1-line condition edit: gate fires only
+  when `!force`. The force-bypass code path is now exercisable as documented.
+- **#472 — codex prompt-symbol matcher normalized across environments
+  (`src/prompt-symbol-registry.js`).** On real cmux captures the codex `›`
+  glyph tail-renders on the same row as the model-status footer and DECRQM /
+  cursor-position-query fragments (`>4;0m>7u`, `0 q`) leak into the screen
+  buffer, so the prior strict line-leading scan permanently missed and the
+  session stuck at `ready:false`. New tolerant detector: (1) modal-UI
+  anti-pattern guard for resume picker, first-run directory-trust prompt and
+  generic press-enter-to-continue modals (treated as NOT ready); (2)
+  multi-signal match on `"OpenAI Codex (v"` plus `/gpt-[0-9.]+\s+\w+\s+fast/`
+  anywhere on the screen; (3) legacy strict line-leading scan preserved as a
+  back-compat fallback. `awaitPromptSymbol` now emits a single
+  `[bootstrap] <cli> ready via: <reason>` log line on stabilize, paired with
+  the #470 optimistic-ready logging for unified debuggability.
+
+### Notes — 0.4.5
+
+- **Tests** — `npm test` passes 416 / 416 (was 411 / 411 in 0.4.4; +5 new
+  cases in `test/release-0.4.5-bugfixes.test.js` covering #469/#470/#471/#472
+  including env-resistance regression guard on the existing noforce test).
+- **Snyk Code SAST** — all newly authored or modified JS files
+  (`scripts/postinstall.js`, `src/prompt-symbol-registry.js`,
+  `src/submit-gate.js`, new `daemon.js` line ranges, and
+  `test/release-0.4.5-bugfixes.test.js`) report 0 findings. The 55
+  pre-existing repo-wide findings in unchanged code are tracked separately as
+  task #474 (security cleanup track) and are not part of this release.
+- **Out of scope, tracked separately** — task #473 (session-ID reuse → stale
+  command metadata) is queued for a 0.4.6 dispatch and is not addressed here.
+
+## [0.4.4] - 2026-05-25
+
+### Added — TELEPTY_SUBMIT_FORCE_DEFAULT env var (task #453)
+
+- **Environment default for forced submit** —
+  `TELEPTY_SUBMIT_FORCE_DEFAULT=1` makes `telepty inject --submit` behave as
+  if `--submit-force` was passed, without changing behavior for users who leave
+  the env var unset. Accepted truthy values are `1`, `true`, `yes`, and `on`
+  after whitespace trimming and case normalization.
+- **Per-call opt-out** — `telepty inject --submit --no-submit-force ...`
+  restores the normal gated submit behavior even when the environment default
+  is enabled. Explicit `--submit-force` remains valid and wins when supplied.
+- **Automation caveat** — this is intended for orchestrators that already know
+  their targets are real, initialized REPLs. It bypasses the safety gate that
+  prevents submit during target boot, avoiding the transient 504
+  `bootstrap_not_ready` path where text lands in the input box but Enter is not
+  sent.
+- **Observability** — env-driven calls emit
+  `[telepty inject] submit-force=env-default (TELEPTY_SUBMIT_FORCE_DEFAULT=1)`
+  to stderr before posting `/submit`.
+
+### Notes — TELEPTY_SUBMIT_FORCE_DEFAULT env var
+
+- **Test suite** — `npm test --silent` passes 403 / 403, including the new
+  `test/inject-submit-force-env.test.js` coverage for env-off, env-on,
+  `--no-submit-force`, explicit `--submit-force`, and value normalization.
+- **Snyk SAST** — the requested `snyk_code_scan` MCP tool was not available in
+  this session, so the installed Snyk CLI was used. After replacing the new
+  localhost HTTP fixture with a loopback `net` test server and generating the
+  test auth token at runtime, `test/inject-submit-force-env.test.js` has 0
+  findings and the changed `cli.js` line ranges have 0 findings. The full repo
+  CLI scan still reports the pre-existing baseline findings in legacy `cli.js`,
+  `daemon.js`, existing HTTP test fixtures, and `scripts/bridge-phase1.js`. No
+  suppressions were added.
+
+### Added — Idle session cleanup (issue #34)
+
+- **Idle visibility in `telepty list`** — session rows now append
+  `💤 idle (Xh Ym)` when `lastActivityAt` is more than 60 seconds old.
+  `telepty list --json` preserves `lastActivityAt` and adds
+  `idle_seconds` for machine consumers.
+- **Transport-agnostic lifecycle helpers** — `src/lifecycle.js` centralizes
+  duration parsing, idle-victim selection, older-than cleanup selection, and
+  PTY/process-level teardown. It uses native POSIX signals and the existing
+  Windows `taskkill` helper; it does not call cmux or any workspace-host API.
+- **`telepty kill <id> [--force] [--timeout <sec>]`** — graceful teardown
+  sends SIGTERM, waits up to the configured timeout, then escalates to
+  SIGKILL. `--force` sends SIGKILL immediately. Successful teardown removes
+  the daemon registry entry and session socket artifacts.
+- **Opt-in idle TTL** — daemon config loads `~/.telepty/config.json` or a
+  simple `config.yaml` / `config.yml` with `idle_ttl_default` (`off` by
+  default). `telepty allow --idle-ttl <duration|off>` stores a per-session
+  override. The daemon reaper emits a `tracing` event with
+  `action: "idle_ttl_auto_kill"` before auto-teardown.
+- **`telepty clean --older-than <duration> [--idle] [--dry-run]`** — default
+  ghost-only cleanup remains unchanged. The new opt-in path removes sessions
+  older than the threshold by `createdAt`, or by `lastActivityAt` when
+  `--idle` is set; `--dry-run` reports targets without deleting them.
+
+### Notes — Idle session cleanup
+
+- **Test suite** — `npm test` passes 397 / 397, including transport-agnostic
+  lifecycle coverage for headless and cmux-backed fixtures.
+- **Snyk SAST** — the requested `snyk_code_scan` MCP tool was not available in
+  this session, so the installed Snyk CLI was used. New standalone files
+  (`src/lifecycle.js`, `src/config-file.js`, and the new lifecycle tests)
+  scan with 0 findings. Scanning changed legacy entrypoints (`daemon.js` and
+  `cli.js`) still reports the repo's pre-existing baseline findings
+  previously noted for Phase 2: CLI path-traversal / command-injection flows
+  and daemon route-level prototype-pollution / throttling / command-execution
+  warnings. No suppressions were added.
+
+### Added — Phase 5a-prime (task #430 P5a-prime)
+
+- **`crates/telepty-cross-machine/`** — standalone Rust library plus
+  `telepty-cross-machine-bin` for manual HTTP peer operations only. Scope is
+  deliberately reduced from the two rejected Phase 5 drafts: no JS bridge, no
+  subprocess envelope contract, no outbox queue, no npm distribution, no SSH
+  transport, and no `cli.js` / `daemon.js` / `cross-machine.js` changes. This
+  follows the review basis in
+  `docs/reports/2026-05-24-phase5-spec-codex-review.md` and
+  `docs/reports/2026-05-24-phase5a-spec-codex-rereview.md`, which identified
+  bridge-consumed binary contracts as the unstable surface.
+- **Manual HTTP subcommands** — `connect-http`, `list-peer-sessions`,
+  `inject-peer`, `list-peers`, and `remove-peer`. `connect-http` probes
+  `/api/health`, treats `/api/meta` as non-fatal, persists token-backed HTTP
+  peers to `~/.telepty/peers.json`, and prints human-friendly status. List
+  commands support free-form `--json` output without an envelope contract.
+  `inject-peer` fails fast on unreachable peers; there is no queueing.
+- **Backward-compatible `peers.json` handling** — missing `transport` defaults
+  to SSH and round-trips without injecting a `transport` field, preserving the
+  JS-era legacy schema used by the SSH path. HTTP operations on SSH peers exit
+  4 with the explicit JS-path diagnostic required by Phase 5a-prime.
+- **Addressing and atomic-write parity** — Rust host parsing mirrors
+  `host-spec.js` URL stripping, embedded-port, and IPv6 behavior. Peer updates
+  use the fsync-backed `tmp + fsync(tmp) + rename + fsync(parent_dir)` pattern
+  copied from `crates/telepty-supervisor-core/src/manifest.rs`.
+- **Build metadata** — `build.rs` embeds git hash, dirty flag, and build
+  timestamp. `telepty-cross-machine-bin --version` prints
+  `telepty-cross-machine 0.0.1 (<git-hash>[, dirty])`.
+
+### Added — Phase 2 Node↔Rust IPC bridge (task #430 P2)
+
+- **`src/bridge/supervisor-ipc.js`** — Node `BridgeClient` speaking NDJSON
+  over the per-session UDS (`~/.telepty/sessions/<sid>/supervisor.sock`).
+  Surface: `connect(socketPath)` → client; `send(frame)` fire-and-forget;
+  `request(frame, {timeoutMs})` with trace_id correlation (resolves on
+  matching `pong`, rejects on matching `error` with the supervisor's
+  `ERR_*` code preserved, rejects `ERR_TIMEOUT` on drift); `subscribe({sid,
+  signal})` returning an `AsyncIterator<Frame>` that respects `AbortSignal`
+  and `iterator.return()` for clean unsubscribe; `close()` idempotent and
+  rejects any pending requests with `ERR_SUPERVISOR_GONE`. Per synthesis
+  ADR §6.2 (B3), `trace_id` is auto-filled for kinds the supervisor
+  mandates it on (`inject`/`output`/`signal`/`kill`/`delete`); pong
+  reflects ping `trace_id` so correlation works without server-side
+  per-client state. Malformed inbound lines surface as synthetic
+  `ERR_BAD_FRAME` to subscribers — the connection survives garbage so a
+  later-good frame still flows.
+- **`src/bridge/j3-shim.js`** — 0.3.x→NDJSON translator covering the P2
+  subset (`inject` / `output` stream / `list`). `inject(sid, prompt, opts)`
+  opens a one-shot connection, sends an inject frame, watches 150 ms for a
+  trace_id-correlated `error` frame (catches B3 / `ERR_DUPLICATE_OP` /
+  `ERR_SHUTTING_DOWN`), and returns `{ success, trace_id, code?, error?
+  }`. `output(sid, {fromSeq, signal})` is an async generator yielding
+  `{ data, seq }` per `Frame::output` and a final `{ exit, ... }` on
+  `shutdown_drain`; consumer-driven cancellation via `AbortSignal` or
+  `break`. `list()` scans `~/.telepty/sessions/*/manifest.json` and
+  surfaces only `ready` / `draining` sessions (tombstones excluded — they
+  lack a usable socket; operators still see them via
+  `telepty-supervisor-bin --list`). Sessions root is resolved lazily so
+  `TELEPTY_SESSIONS_DIR` redirects work without re-requiring the module.
+- **`src/bridge/supervisor-launcher.js`** — per-session Rust supervisor
+  process lifecycle. `resolveBinary({env})` chains
+  `TELEPTY_SUPERVISOR_BIN` (env override) → `./target/release/telepty-
+  supervisor-bin` (repo-relative) → `./target/debug/...` → `which
+  telepty-supervisor-bin` (PATH) and throws `ERR_BIN_NOT_FOUND` otherwise.
+  `spawn({sid, argv, cwd?, binary?, env?, stdio?})` shells out to the
+  binary with `stdio: ['ignore', 'ignore', 'pipe']` (default) so the
+  supervisor's M1/M2 stdout PTY-mirror doesn't bleed into the parent.
+  `waitReady(sid, {timeoutMs, pollMs})` gates on BOTH manifest status
+  (`ready`/`draining`) AND `fs.existsSync(socket)` — supervisor.rs writes
+  the manifest *before* `ipc::bind_socket`, so a manifest-only gate races
+  the bind; checking both closes the window without touching the
+  supervisor crate. `isAlive(sid)` cross-checks manifest pid via
+  `process.kill(pid, 0)`.
+- **`cli.js` minimal-touch wiring** (Rule 29 surgical, +27 LOC, no
+  refactor of adjacent code):
+  - `cmd === 'list'` (L915): merges `bridgeShim.list()` into the daemon-
+    discovered session set, de-duplicated by `id`. Daemon entries remain
+    source-of-truth when both surfaces report the same session; bridge
+    entries fill the gap when daemon is down. Wrapped in a defensive
+    `try/catch` so any bridge failure leaves the daemon list intact.
+  - `cmd === 'inject'` LOCAL path (L1755): bridge-first attempt when
+    `!useSubmit && bridgeShim.findSupervisorManifest(target.id)` is
+    truthy. On bridge success, prints the existing
+    `✅ Context injected successfully into '...' (bridge).` line and
+    returns; on bridge failure, falls through to the unchanged daemon
+    HTTP path so caller-visible behavior never degrades. The gated
+    `--submit` semantics (render-gate / retry / `--submit-force`) stay
+    on `daemon.js` for the migration window — P2 wire does not carry
+    render-gate yet.
+- **`cross-machine.js` UNTOUCHED** — P2 scope is local bridge only;
+  remote SSH / HTTP transport stays on the existing path. P3+ owns the
+  remote→bridge story.
+
+### E2E acceptance — `telepty spawn → inject → output` works with daemon.js stopped
+
+- `test/bridge-e2e.test.js` drives the supervisor binary directly through
+  `supervisor-launcher` + `j3-shim` in an isolated `HOME` so the live
+  daemon (if any) is never touched. The headline test launches a real
+  `cat -u` under the supervisor, subscribes to the output stream, injects
+  `ping-echo\n`, and asserts the echo arrives — proving the bridge alone
+  is sufficient for the primary three operations per dispatch §2.4. The
+  test self-skips with a clear hint when
+  `target/release/telepty-supervisor-bin` is absent (binary not built
+  yet), keeping CI without Rust toolchain green.
+
+### Notes — Phase 2 bridge
+
+- **No new npm dependencies** (Constitution §17 무의존). NDJSON parsing
+  via `readline.createInterface` from the Node stdlib; UDS connection via
+  `net.createConnection({ path })`; UUIDs via `crypto.randomUUID()`. Adds
+  zero packages to `package.json` `dependencies`.
+- **Test suite** — `npm test` 375 / 375 pass in ~24 s (343 baseline
+  preserved per Rule 29 + 32 new bridge tests: 14 `BridgeClient` units,
+  14 `j3-shim` units, 4 E2E). Test file ratio is ~1:1 with prod LOC
+  (~787 prod / ~797 tests).
+- **Snyk SAST** — `snyk_code_scan` on `src/bridge/` + new test files →
+  **0 findings**. Pre-existing `cli.js` findings (3× path-traversal on
+  CLI arg → `fs.readFileSync` / `fs.readdirSync` at L2345/L2347/L2656;
+  2× command-injection on CLI arg → `execSync` / `node-pty.spawn` at
+  L471/L1116) are unchanged by this work — they live in dataflows
+  unrelated to the L915/L1755 bridge insertions and are tracked
+  separately (consistent with the v0.4.3 baseline). No new Snyk findings
+  attributable to this phase.
+- **Path budget** — bridge prod 787 LOC + bridge tests 797 LOC =
+  ~1.6 kLOC, well within the dispatch envelope (bridge ~400-700 + shim
+  ~200-400 + tests ~300-500). cli.js delta is +27 LOC pure additions
+  with no edits to existing lines, satisfying the minimal-touch
+  directive.
+- **Cross-platform** — UDS path is POSIX-only in P2 (Windows native
+  pipe = P4 per dispatch §2). Bridge unit tests and E2E gracefully
+  skip on `process.platform === 'win32'`; the launcher still resolves
+  the binary path on Windows so the eventual P4 wiring has a stub to
+  extend.
+
+### Carry-overs — Phase 2
+
+1. **`telepty spawn` cli command bridge wiring** — out of P2 scope per
+   dispatch §Goal item 4 ("inject / output / list paths"). P3 owns the
+   refactor that lets `telepty spawn` route through
+   `supervisor-launcher.spawn` for supervisor-managed sessions.
+2. **Render-gated `--submit` over bridge** — daemon.js stays as the
+   submit gate for the migration window. Bridge inject currently
+   appends a literal `\r` to the data (matching the legacy
+   `no_enter: false` default) without REPL readiness detection.
+3. **Single-binary `telepty supervisor` mode** — P2 still spawns the
+   `telepty-supervisor-bin` standalone bin. The `telepty supervisor`
+   subcommand mode per orchestrator decision §6.6 A is post-P2.
+
+### Added — Phase 1 supervisor-core-finish (task #430 P1)
+
+- **A5 detach/reattach via UDS reconnection + log offset replay** —
+  `wire::Kind::Resume` frame with optional `from_seq: u64` lets a
+  reconnecting client request replay of `Output` frames whose `seq` is
+  greater than `from_seq` from `~/.telepty/sessions/<sid>/log.jsonl`
+  before subscribing to the live broadcast. Replay is per-connection
+  sequential (handler-local) — no broadcast race. Seq-less audit
+  frames (`shutdown_drain`) are forwarded unconditionally so a late
+  reattach observes terminal state.
+- **A7 list discovery via filesystem manifest scan** —
+  `manifest::scan_sessions()` walks `~/.telepty/sessions/*/manifest.json`
+  with atomic per-file reads; missing / unparseable manifests are
+  skipped (never panics). New `telepty-supervisor-bin --list` flat
+  flag emits a JSON array of `Manifest` to stdout. Output shape is
+  the **supervisor-owned** view; the legacy `telepty list --json`
+  daemon view will be reconciled by the P3 cli refactor (per dispatch
+  §6.1). `--list` is mutually exclusive with run-mode argv.
+- **A8 delete graceful drain integration test** —
+  `tests/delete_drain.rs` end-to-end (no goldens): graceful (SIGTERM)
+  and forced (SIGKILL) variants both assert manifest unlinked + socket
+  unlinked + `log.jsonl` contains `shutdown_drain` with correct
+  `exit_reason` + supervisor exits within 3 s. Production code already
+  existed in `supervisor::run` (kill_outcome → unlink_clean branch).
+- **B3 trace_id enforcement extended to signal/kill/delete** —
+  `wire::validate_incoming` now rejects `Kind::Signal`, `Kind::Kill`,
+  `Kind::Delete` lacking `trace_id` with explicit error codes
+  (`signal_missing_trace_id`, `kill_missing_trace_id`,
+  `delete_missing_trace_id`) per C3 spec §1002 audit linkage
+  (`kind:"signal"` event matches originating injector trace_id;
+  `kind:"shutdown_drain"` carries parent_trace_id). Rejection reason
+  is ALSO appended to `log.jsonl` so the audit trail captures *why* a
+  frame was rejected even if the client disconnects before reading
+  the error response.
+- **F3 atomic manifest write contract test** —
+  `tests/atomic_manifest.rs` (5 tests). Headline test
+  `concurrent_readers_never_observe_partial_json` runs 1 writer thread
+  + 6 reader threads × 800 ms; readers always see a complete-old or
+  complete-new manifest, never partial JSON (the rename-atomicity
+  guarantee). Plus golden tests for `.json.tmp` cleanup, missing-
+  parent-dir creation, `unlink_clean` idempotency, and tombstone
+  audit-field roundtrip.
+- **G3 audit trail expansion** — `dispatch_ingest` now logs each
+  validated ingest event (`Inject` / `Signal` / `Kill` / `Delete`) to
+  `log.jsonl` right after `validate_incoming` passes. Ping is
+  intentionally skipped (heartbeat noise). Validation rejections are
+  also logged (closes the silent-drop gap from earlier milestones).
+  `audit.rs` was extended (single module per Constitution §1
+  lightweight) rather than fragmenting into a new audit/ submodule.
+  R4 TelemetryEvent translation deferred to the P3 cli bridge per
+  orchestrator Phase 4 decision.
+- **§8.A1 Normal termination contract test** —
+  `tests/normal_termination.rs` (2 tests). Covers child exits 0
+  (assert `exit_reason: normal`, `exit_code: 0`, escalated false,
+  manifest unlinked) and nonzero-but-natural exit (`sh -c 'exit 7'`
+  — assert exit_code propagated; `Normal` is the exit *mechanism*,
+  not the exit *code*).
+
+### Performance — E1 local-inject latency bench
+
+- New `crates/telepty-supervisor-core/benches/inject_e1.rs` custom
+  harness (no criterion — Constitution §17 no new Rust deps).
+  `[[bench]] harness = false`. Run with `cargo bench --bench inject_e1`.
+  100 warmup + 1000 measured roundtrips through real supervisor
+  wrapping `cat`.
+- **E1-p50: 0.025 ms** (p90 0.057 ms, p99 0.091 ms) on
+  macos/aarch64 / Mac16,8 / Apple M4 Pro — **40× under the 1 ms
+  target**.
+- Exit code 0 iff p50 < 1 ms (CI-gateable).
+
+### Notes — Phase 1 supervisor-core-finish
+
+- **No new Rust deps** (Constitution §17). `tokio` `fs` feature
+  enabled in workspace deps (feature flag only). `serde_json` added
+  to `telepty-supervisor-bin` (was already a workspace dep).
+- **Rule 29 surgical** — changes scoped to
+  `crates/telepty-supervisor-core/` (src + tests + benches) and
+  `crates/telepty-supervisor-bin/`. No daemon.js / cli.js changes
+  (those land in P2/P3). No Windows code paths (P4 scope; cargo
+  features can gate but no implementation in this phase).
+- **Tests** — 42 / 42 pass (23 baseline preserved + 19 new):
+  - Unit: +4 wire B3 (signal/kill/delete trace_id), +2 audit, +1
+    scan_sessions
+  - Integration: +3 reattach_replay (A5), +2 delete_drain (A8), +5
+    atomic_manifest (F3), +2 normal_termination (§8.A1)
+- **Snyk SAST** — `snyk_code_scan` on `crates/` → 0 findings across
+  both crates. Run at each phase boundary (Phase 4+).
+- **§8.A contract test parity** (per C3 spec
+  `docs/specs/2026-05-10-supervisor-c3-kill-gate-spec.md` §8.A): 7
+  of 13 Bucket-A scenarios covered + 2 extras (A5 reattach, F3
+  atomic) + 4 correctly deferred (Windows = P4 / Bucket B =
+  controlled-host out of Phase 1 spike scope). **2 follow-up
+  carry-overs documented**: §8.A3-tree (grandchild-cascade
+  killpg semantics — code already correct; explicit fixture
+  needed) and §8.A-reactor-stall (single-thread reactor
+  non-blocking invariant — code-review-only invariant; runtime
+  probe optional).
+- **Sources of truth** — the synthesis ADR referenced in dispatch
+  (`docs/adr/2026-05-10-telepty-l2-architecture-q-prime-bis.md`)
+  and 6-phase plan (`docs/reports/2026-05-23-telepty-l2-supervisor-plan.md`)
+  live in the orchestrator repo, not visible from this repo.
+  Per Phase 1 CLDR + orchestrator hybrid (b)+(c) decision, this
+  work derives §19.2 contract requirements from the local
+  `docs/specs/2026-05-10-supervisor-c3-kill-gate-spec.md` (which
+  the code already cited as `SPEC-C3-r1`) plus the dispatch text
+  itself.
+
 ## [0.4.3] - 2026-05-23
 
 ### Fixed

package/README.md

@@ -68,6 +68,23 @@ telepty broadcast "status report"
 | `telepty layout [grid\|tall\|stack]` | Arrange kitty windows |
 | `telepty update` | Update to latest version |
 
+## Environment variables
+
+| Variable | Values | Default | Description |
+|----------|--------|---------|-------------|
+| `TELEPTY_SUBMIT_FORCE_DEFAULT` | `1`, `true`, `yes`, `on` to enable; unset, `0`, or `off` to disable | unset | Makes `telepty inject --submit <id> "text"` behave as if `--submit-force` was passed. |
+
+`TELEPTY_SUBMIT_FORCE_DEFAULT=1` is for orchestrators and automation that
+already know their targets are real, initialized REPLs. It avoids the transient
+504 `bootstrap_not_ready` path where injected text lands in the target input box
+but the render-gated submit refuses to press Enter while the target session is in
+a temporary working state.
+
+This bypasses the safety gate that protects sessions still booting. Set it only
+when you understand that trade-off. Use `--no-submit-force` on a specific
+`telepty inject --submit` call to restore the gated behavior even when the
+environment default is enabled.
+
 ## Cross-Machine Sessions
 
 telepty auto-discovers sessions across your Tailnet. All commands (`list`, `attach`, `inject`, `rename`, `multicast`, `broadcast`) work seamlessly across machines.