@dmsdc-ai/aigentry-telepty 0.1.98 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,326 @@
+# Changelog
+
+All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
+
+## [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`)
+
+Closes task #347. Two opt-in CLI knobs on `telepty inject` for cases where
+the 0.3.2 prompt-symbol gate has a transient render mismatch (autocomplete
+dropdown open, cursor moved, mid-paste race) and the 504 fall-through
+forces the human user to press Enter manually.
+
+- **`--submit-force`** — passes `force: true` to `POST /submit`. Skips
+  both Layer 3 (prompt-symbol) and Layer 1 (state-gate) and dispatches
+  Enter once via the existing `terminalLevelSubmit` chain (kitty → cmux
+  → PTY). Daemon-side `force` semantics already shipped in 0.3.1 for
+  `telepty send-key`; this just plumbs the flag through inject.
+- **`--submit-retry N`** (default 1, clamp [0, 3]) — on a 504 response
+  with a retry-safe reason, wait 300 ms and retry the same `/submit`
+  request up to N times. Retry-safe reasons (idempotent re-fire is
+  guaranteed because the body is verifiably still in the input box):
+
+  | Reason | Source |
+  |---|---|
+  | `gated_dispatch_unconsumed` | `daemon.js:1680` (verify said body still visible after best-effort dispatch) |
+  | `gate_timeout` | reserved (Layer 1 plain timeout — falls through to dispatch in 0.3.1+, not currently a 504 source) |
+  | `no_prompt_symbol_seen` | reserved (Layer 3 timeout — currently never emits 504) |
+
+  Hard-fail reasons (`session_dead`, `session_error`, `session_restarting`,
+  `no_state`, `no_state_manager`) and any non-504 status (4xx) **never**
+  trigger client-side retry — re-firing won't recover.
+
+- **Default behavior preserved**: a bare `telepty inject --submit ...`
+  call now retries once on a retry-safe 504. This is a strict improvement
+  over 0.3.2 (which surfaced a warning and required manual `send-key`)
+  and remains backward-compatible because retry only fires when the
+  server tells the client the dispatch demonstrably did not land.
+
+### Tests
+
+- `test/inject-submit-flags.test.js` (NEW, 9 tests) — mock-daemon
+  coverage:
+  - `--submit-force` adds `force:true` to `/submit` body; success line
+    renders `[forced]` tag.
+  - bare `--submit` does NOT add `force` to body.
+  - default `--submit-retry 1` retries once on `gated_dispatch_unconsumed`
+    504 then succeeds; output contains `[retry 1/1]`.
+  - `--submit-retry 2` exhausts to 3 calls then prints
+    `Submit gated-timeout … after 3 attempts`.
+  - `--submit-retry 0` makes exactly 1 call, no `[retry`.
+  - `session_dead` 504 → no retry even with `--submit-retry 3`.
+  - `no_state` 504 → no retry even with `--submit-retry 3`.
+  - `--submit-force --submit-retry 2` preserves `force:true` across retries.
+  - 500 error → no retry, prints to stderr.
+- `test/enforce-report.test.js` — version assertion 0.2.0 → 0.3.3.
+- All 174 existing tests pass unchanged.
+
+### Invariants preserved
+
+- Daemon code unchanged. `force:true` and the gate layers behave exactly
+  as in 0.3.2.
+- `telepty send-key` unchanged.
+- `telepty enter` unchanged.
+- `telepty inject --ref` (no `--submit`) unchanged.
+- Cross-machine remote inject path unchanged (the SSH branch in `cli.js`
+  bypasses the new flags by design — remote daemons handle their own
+  submit semantics).
+- Exit code on soft failure (504) remains 0; orchestrator scripts that
+  check for non-zero exits are unaffected.
+
+## [0.3.2] — 2026-04-26
+
+### Added — Layer 3 prompt-symbol render gate (spec: `docs/superpowers/specs/2026-04-26-prompt-symbol-render-gate.md`)
+
+Strictly additive layer above the 0.3.1 `sessionStateManager` gate. Closes
+the recurring "Enter not applied on freshly-spawned `claude`/`codex`" trap
+by directly observing the rendered terminal screen for a per-CLI prompt
+symbol — the only deterministic ready-signal these TUIs expose to external
+automation (no OSC 133, no exit-on-prompt, no socket signal).
+
+- **`src/prompt-symbol-registry.js`** (NEW) — per-CLI prompt-symbol catalog:
+
+  | CLI | Symbol | Codepoint | UTF-8 | Geometry sanity |
+  |---|---|---|---|---|
+  | `claude` | `❯` | U+276F | `E2 9D AF` | sandwiched between U+2500 (`─`) horizontal-rule borders |
+  | `codex` | `›` | U+203A | `E2 80 BA` | model footer (`gpt-N…`) within 2 lines below |
+  | `gemini` | `*` | U+002A | `2A` | bracketed by U+2580 (`▀`) above / U+2584 (`▄`) below |
+
+  `lookup(command)` normalizes path + args (`/usr/local/bin/claude --resume`
+  → claude entry; `codex resume` → codex entry). Unknown CLIs return `null`,
+  causing the gate to skip cleanly via `unknown_cli`.
+
+- **`src/submit-gate.js` `awaitPromptSymbol(session, opts)`** (NEW) — polls
+  `cmux read-screen --workspace <id> --lines <n>` (default 30) every
+  `pollIntervalMs` (default 150 ms) and resolves only when the symbol has
+  been stably detected for ≥ `stabilityMs` (default 200 ms). Bounded by
+  `timeoutMs` (default 8000 ms; clamp [500, 30000]). Resolves cleanly with
+  one of:
+  - `{ ready: true, last_seen_at, waited_ms }`
+  - `{ ready: false, reason: 'no_screen_primitive', waited_ms: 0 }` (non-cmux backend)
+  - `{ ready: false, reason: 'unknown_cli', waited_ms: 0 }`
+  - `{ ready: false, reason: 'no_prompt_symbol_seen', waited_ms }` (timeout, fall through)
+  Pure helper: `now`/`sleep`/`readScreen`/`registry` are all injectable for
+  deterministic tests (fakeClock harness from `verifyBodyConsumed`).
+
+- **`daemon.js` POST /submit** — Layer 3 runs immediately before Layer 1
+  on the gated path. Result threaded into success and 504 response bodies
+  as optional `prompt_symbol: { found, waited_ms, [reason], [last_seen_at] }`.
+  **Never emits its own 504** — best-effort fall-through to Layer 1, which
+  retains all existing 0.3.1 outcomes (success / `gated_dispatch_unconsumed`
+  / hard-fail). Per-request bypass via `{ "prompt_symbol_gate": false }`
+  (Layer 3 only); `force:true` and `TELEPTY_SUBMIT_GATE=off` continue to
+  bypass BOTH layers.
+
+### Tests
+
+- `test/prompt-symbol-registry.test.js` (NEW) — registry coverage with
+  inline cmux read-screen fixtures: claude/codex/gemini detect on idle
+  screens, banner-stage rejection (no border geometry), history-echo
+  disambiguation (LAST occurrence anchored), `lookup()` path/args
+  normalization + case-insensitivity + unknown/null inputs, `byteSeq`
+  matches `Buffer.from(symbol, 'utf8')`.
+- `test/submit-gate.test.js` (extended) — `awaitPromptSymbol` covers:
+  non-cmux → `no_screen_primitive`; missing workspace → same; unknown CLI
+  → `unknown_cli`; stable claude/codex screen → ready after `stabilityMs`;
+  empty `readScreen` returns → `no_prompt_symbol_seen` after `timeoutMs`;
+  symbol-then-disappear → stability streak resets; injected registry
+  override is honored; `readScreen` receives `(workspaceId, tailLines)`.
+
+### Invariants preserved
+
+- All 32 existing `test/submit-gate.test.js` tests pass unchanged.
+- `force: true` and `TELEPTY_SUBMIT_GATE=off` bypass BOTH layers.
+- Layer 1 hard-fail short-circuits (`session_dead`/`error`/`restarting`/
+  `no_state`/`no_state_manager`) still emit 504; Layer 3 never adds a new
+  504 source.
+- `inject --ref` (no `--submit`) path unchanged.
+- aterm / non-cmux backends skip Layer 3 cleanly via `no_screen_primitive`.
+- Cross-machine remote inject unchanged: Layer 3 runs only on the daemon
+  with cmux access; remote daemons fall through.
+- Response shape additive — `prompt_symbol` is an optional field; existing
+  callers ignore unknown JSON keys.
+
+## [0.3.1] — 2026-04-26
+
+### Fixed — submit-gate regression cluster (spec: `docs/superpowers/specs/2026-04-26-submit-gate-fixes-v2.md`)
+
+Three regressions surfaced post-`0.3.0` against fresh-spawned `claude`/`codex`
+sessions where the gate's strict thresholds and timeout-abandon path made the
+new `/submit` endpoint less reliable than the pre-`0.3.0` blind retry on cold
+REPLs. All three fixes ship in this single patch.
+
+- **δ-fix-2 — `send-key` bypass (P0).** `POST /api/sessions/:id/submit` now
+  accepts `{ "force": true }` to skip the render-readiness gate and verify
+  step, dispatching once via the existing kitty/cmux/PTY chain. `cli.js`
+  `send-key` always sets `force:true`, restoring the manual Enter override.
+  Response shape additive (`forced:true`); existing callers unaffected.
+- **δ-fix-3 — gate threshold relaxed 0.85 → 0.5 (P1).** `sessionStateManager`
+  emits IDLE `confidence=0.6` when neither OSC 133 nor a shell-prompt pattern
+  matches (`session-state.js:380`) — the dominant case for AI-CLI TUIs whose
+  Unicode-box input line bypasses `PROMPT_PATTERNS`. Default `minConfidence`
+  lowered to `0.5` (below the 0.6 silence-fallback with margin); per-request
+  override `min_confidence` body field accepted (clamped `[0, 1]`).
+- **δ-fix-4 — timeout extension + best-effort dispatch on timeout (P1).**
+  Default `gate_timeout_ms` raised `5000 → 10000` (upper clamp `15000 →
+  30000`) to cover empirical `claude` ready window (3-6 s on fresh spawn).
+  On a plain `timeout` reason, `/submit` now dispatches anyway and verifies
+  body consumption — the pre-`0.3.0` blind dispatch is restored as a fallback
+  while keeping the new honesty signal: 504 only fires when
+  `verifyBodyConsumed` confirms the body is still in the input box (new
+  `reason: 'gated_dispatch_unconsumed'`). Dispatch-on-timeout success path
+  adds `gated_dispatch_after_timeout: true` (additive).
+  Hard-fail reasons (`session_dead`/`error`/`restarting`/`no_state`) still
+  short-circuit to 504 immediately.
+
+### Invariants preserved
+
+- `inject --submit` warm-session reliability ≥99% target (gate short-circuits
+  at conf≥0.85 still passes after default drops to 0.5).
+- 504 still emitted in true-fail case (after best-effort dispatch + verify
+  reports `still_visible`).
+- `TELEPTY_SUBMIT_GATE=off` daemon-wide escape hatch preserved.
+- `inject --ref` (no `--submit`) path unchanged.
+- 22/23 existing `test/submit-gate.test.js` tests pass unchanged; one test
+  (line 185-193) updated to preserve the below-threshold-rejection semantic
+  with literals shifted away from the new 0.5 default.
+
+## [0.3.0] — 2026-04-26
+
+### Added — render-gated submit (specs: `docs/superpowers/specs/2026-04-26-inject-submit-enter-reliability.md`)
+
+- **`src/submit-gate.js`** — pure helpers exported for unit tests:
+  - `awaitReplReady(sessionId, stateManager, opts)` — waits for the target REPL
+    to reach an input-ready state (`idle` or `waiting`) with confidence ≥ 0.85
+    before Enter is fired. Bounded by `timeoutMs` (default 5000).
+  - `verifyBodyConsumed(session, bodyText, opts)` — polls the session's
+    `outputRing` for the inject body to disappear from the input box,
+    confirming Enter was actually consumed by the REPL (default 1500 ms,
+    200 ms interval). Optimistic when body never visible (ANSI/wrap edge).
+  - `isReady`, `isFailed`, `READY_STATES`, `FAIL_STATES` — test surface.
+- **POST `/api/sessions/:id/submit`** rewritten to use the gate by default.
+  Flow: gate on REPL readiness → dispatch via existing kitty/cmux/PTY chain →
+  verify consumption (when caller passes `injected_body`) → bounded retry.
+  Response now includes `gated`, `gate_wait_ms`, `verify` (when applicable).
+- **HTTP `504 gate_timeout` response** on `/api/sessions/:id/submit` when the
+  REPL never readies for input within `gate_timeout_ms` (default 5000).
+  This is **why this is a minor bump** — consumers may need to handle the new
+  status code. 504 (Gateway Timeout) is the correct semantic versus 408 or
+  reused 503 — the daemon acted as a gateway to the upstream REPL and the
+  upstream did not respond in time.
+- **CLI `inject --submit`** now passes `injected_body` to the daemon for
+  consumption verification, removed the legacy 500 ms blind sleep
+  (gate handles timing), and treats 504 as a soft failure (logs a clear
+  remediation hint, exits 0 — orchestrator scripts depend on exit 0 for
+  recoverable conditions).
+- New body fields accepted by `/submit`: `injected_body`, `gate_timeout_ms`,
+  `verify_timeout_ms`. Existing `pre_delay_ms` / `retries` / `retry_delay_ms`
+  remain accepted for back-compat.
+- **`TELEPTY_SUBMIT_GATE=off`** env var — escape hatch to revert to the 0.2.x
+  blind retry path for parity testing or rollback.
+
+### Changed
+
+- POST `/api/sessions/:id/submit` is no longer open-loop. Default behavior
+  is gated; legacy blind retry preserved only behind `TELEPTY_SUBMIT_GATE=off`.
+- CLI `✅ Submitted via <strategy>` line now optionally appends
+  `[gate <N>ms]` when the gate had to wait. Default-on; pre-existing
+  format preserved when gate fast-paths (warm sessions).
+- `bus` event `submit` now carries optional fields `gated`, `gate_wait_ms`,
+  `verify` (additive — consumers ignore unknown fields).
+
+### Fixed
+
+- Root cause: `/submit` previously fired Enter open-loop with a ~2.1 s
+  blind retry budget while a fresh `claude` REPL needed 3–6 s to render
+  (welcome banner, trust dialog, prompt setup). The legacy retry loop
+  also discarded `terminalLevelSubmit`'s return value, so the reported
+  `(N attempts)` count did not reflect verified dispatches. The new
+  gate observes the existing `sessionStateManager` (`idle` / `waiting`
+  with confidence ≥ 0.85) before dispatch, eliminating the race.
+- Recurring orchestrator UX trap (parallel to #329 Track E27) where
+  every `inject --submit` required a manual `sleep N && telepty send-key
+  <id> enter` follow-up. Spec target: ≥ 99% on a 100× spawn-and-inject
+  E2E harness (current baseline ~0%); E2E harness execution is dispatched
+  to the builder (out of scope for this commit).
+
+### Tests
+
+- `test/submit-gate.test.js` — 23 new unit tests (all pass) covering
+  `awaitReplReady` fast-paths, transition resolution, timeout, fail-state
+  short-circuits; `verifyBodyConsumed` happy-path / optimistic / timeout /
+  empty / no-ring / whitespace normalization / ANSI strip / injectable
+  clock for deterministic timing.
+- Pre-existing test suite is unmodified; integration coverage of the new
+  endpoint behavior is delegated to the builder per SAWP scope.
+
+### Compatibility / migration
+
+- **Default behavior changes** for callers of `/api/sessions/:id/submit`:
+  responses now succeed only when the REPL reaches readiness within
+  `gate_timeout_ms`. Most callers will see equivalent or better behavior;
+  callers that depended on "best effort fire-and-forget" can opt out via
+  `TELEPTY_SUBMIT_GATE=off`.
+- `inject --ref` (without `--submit`), `telepty allow`, `telepty list`,
+  and `telepty send-key` semantics unchanged.
+- Aterm sessions unaffected (gate is bypassed via existing
+  `session.type === 'aterm'` guards).
+- No new external dependencies (Rule 17). No schema, persistence, or
+  state-machine changes (gate is read-only on `sessionStateManager`).
+
+## [0.2.0] — 2026-04-15
+
+### Added — REPORT enforcement (specs/enforce-report-spec.md)
+
+- **New bus event types** for observable REPORT lifecycle:
+  - `TASK_IDLE_NO_REPORT` — fires once on idle transition for inject-driven sessions
+  - `TASK_COMPLETE_WITH_REPORT` — fires when matching REPORT inject detected via reverse-match
+  - `TASK_BLOCKED_WITH_REASON` — fires on `STATUS: blocked` reply inject
+  - `TASK_DISMISSED` — fires on `STATUS: dismissed` inject OR via DELETE endpoint
+  - `TASK_DEAD_NO_REPORT` — fires when session dies with pending report (attaches `auto_summary`)
+- **New HTTP endpoints** on daemon:
+  - `GET /api/pendingReports/:id` — inspect pending report entry + optional auto_summary
+  - `DELETE /api/pendingReports/:id` — orchestrator-side dismissal; fires `TASK_DISMISSED`
+- **New module** `src/report-enforcement.js` exports pure helpers:
+  - `classifyReportPrompt(prompt)` — classify inject prompt by prefix
+  - `buildAutoSummary(session, opts)` — scrape last N non-blank lines from outputRing with ANSI stripping and secret redaction
+- **REPORT detection via reverse-match** in POST `/api/sessions/:id/inject`:
+  - An inject with `from=X` whose prompt starts with a REPORT prefix (`REPORT:`, `STATUS:`, `SPEC:`, `OWNER-DIAGNOSIS:`, `ENFORCE-SPEC:`, `ENFORCE-IMPLEMENTED:`, `LOG-FIX-SPEC:`, `LOG-FIX-IMPLEMENTED:`, `FIX-SPEC:`, `FIX-IMPLEMENTED:`, `SPEC-SYNC:`, `DIAGNOSIS:`) and whose recipient matches `pendingReports[X].source` fires the matching enforcement event.
+  - Prevents false positives: prefix alone is NOT enough; reverse-match to originating inject required.
+- **Auto-summary with secret redaction**:
+  - Strips ANSI via shared regex
+  - Filters blank lines
+  - Caps at `DELIBERATION_REPORT_AUTO_SUMMARY_LINES` (default 40) + `DELIBERATION_REPORT_AUTO_SUMMARY_MAX_BYTES` (default 4096)
+  - Redacts `api_key`, `password`, `token`, `secret` assignment patterns → `[REDACTED]`
+  - Attached to `TASK_DEAD_NO_REPORT` events and GET query responses
+
+### Changed
+
+- `sessionStateManager.onTransition` handler now fires the enforcement events above. Legacy `TASK_COMPLETE:` text-inject to source session is preserved during 0.2.x grandfather period.
+- Legacy auto-report paths (health-poll idle threshold + ready-WS signal) now coordinate via `pendingReports[id].idleNotified` flag to prevent double-fire.
+- `pendingReports[id]` schema extended with `awaitingReport: true`, `idleNotified: bool`, `idleAt: ISO8601`. Entry is now cleared only when REPORT arrives, session dies, or orchestrator dismisses.
+- Duplicate pendingReports overwrite now emits `[AUTO-REPORT] overwritten pending` warning.
+
+### Configuration (new env vars)
+
+- `DELIBERATION_REPORT_AUTO_SUMMARY_ON_QUERY` — bool, default `true`. Gates auto_summary on GET pendingReports.
+- `DELIBERATION_REPORT_AUTO_SUMMARY_LINES` — int, default 40. Max lines in auto_summary.
+- `DELIBERATION_REPORT_AUTO_SUMMARY_MAX_BYTES` — int, default 4096. Byte cap on auto_summary.
+
+### Deprecated
+
+- `reportTimeoutSecs` env var — emits deprecation warning if set. Removed in 0.3.x. Evidence (7.5s–649s task range) showed a default timer is arbitrary and prone to false timeouts; replaced with event-driven detection (idle + dead + explicit query).
+
+### Tests
+
+- `test/report-enforcement.test.js` — 28 new unit tests for `classifyReportPrompt`, `buildAutoSummary`, regex exports
+- `test/enforce-report.test.js` — 11 new integration tests for bus events and endpoints
+- Full suite: **170/170 passing** (131 pre-existing + 39 new)
+
+### Migration notes
+
+- **No orchestrator-side changes required** to benefit. New bus events flow passively; legacy `TASK_COMPLETE:` text-inject still fires.
+- Consumers that subscribe to the bus now see richer event types — optional to consume.
+- Orchestrators wanting to dismiss a pending report can use `DELETE /api/pendingReports/{id}`.
+- Orchestrators wanting on-demand summary can use `GET /api/pendingReports/{id}` (honors `DELIBERATION_REPORT_AUTO_SUMMARY_ON_QUERY`).

package/CLAUDE.md

@@ -65,10 +65,14 @@ npm version patch --no-git-tag-version && npm publish --access public
 - inject 시 발신자 session ID (`--from`)를 항상 포함
 - PTY `\r` 직접 의존 금지
 
-## 최근 주요 변경 (v0.1.58–0.1.62)
+## 최근 주요 변경 (v0.1.58–0.3.3)
 
 | 버전 | 변경 |
 |------|------|
+| 0.3.3 | inject `--submit-force` (gate bypass) + idempotent `--submit-retry` (default 1, retry-safe 504만). 클라이언트 측 변경, daemon 무수정. task #347. |
+| 0.3.2 | Layer 3 prompt-symbol 렌더 게이트 — claude/codex/gemini 별 prompt symbol을 cmux read-screen으로 polling. |
+| 0.3.1 | 게이트 임계값 0.85 → 0.5 완화 + dispatch-on-timeout best-effort + send-key force=true 우회 추가. |
+| 0.3.0 | Render-gated submit (sessionStateManager 기반). Enter 송신 전 REPL ready 검증. |
 | 0.1.62 | TUI 태스크 추적 — bus 이벤트에서 [태그] 자동 파싱, 세션별 상태 표시 |
 | 0.1.61 | reconnect 시 resize/\x0c 제거 (멀티터미널 깜빡임 수정) |
 | 0.1.60 | TUI P1 — s=start, k=kill, p=purge stale |

package/README.md

@@ -53,6 +53,9 @@ telepty broadcast "status report"
 | `telepty list [--json]` | List sessions across all discovered hosts |
 | `telepty attach [id[@host]]` | Attach to a session (interactive picker if no ID) |
 | `telepty inject <id[@host]> "text"` | Inject text into a session |
+| `telepty inject --submit <id> "text"` | Inject text and press Enter (render-gated, retries once on safe gate-timeout) |
+| `telepty inject --submit --submit-force <id> "text"` | As above, but bypass the gate (skip Layer 1/3 detection — opt-in escape hatch) |
+| `telepty inject --submit --submit-retry N <id> "text"` | Override retry count [0–3] on safe 504 (default 1) |
 | `telepty enter <id[@host]>` | Send Enter/Return to a session |
 | `telepty multicast <id1,id2> "text"` | Inject into multiple sessions |
 | `telepty broadcast "text"` | Inject into ALL sessions |

package/cli.js

@@ -1550,6 +1550,32 @@ async function main() {
     const useSubmit = submitIndex !== -1;
     if (useSubmit) args.splice(submitIndex, 1);
 
+    // Extract --submit-force flag (gate bypass; opt-in escape hatch).
+    // Mirrors `telepty send-key`'s force semantics: skip both Layer 3 and
+    // Layer 1 gates and dispatch Enter immediately. Safe only when the
+    // caller is confident the target REPL is ready (e.g., orchestrator is
+    // visibly idle). See specs/2026-05-02-submit-force-and-retry.md
+    const submitForceIndex = args.indexOf('--submit-force');
+    const submitForce = submitForceIndex !== -1;
+    if (submitForce) args.splice(submitForceIndex, 1);
+
+    // Extract --submit-retry N flag (default 1, clamp [0, 3]). On a 504
+    // gated-failure with a retry-safe reason (gate timed out and body is
+    // still in the input box → idempotent), wait 300ms and retry. Hard-fail
+    // reasons (session_dead/error/restarting/no_state) do NOT retry —
+    // re-firing won't recover and would be a wasted round-trip.
+    let submitRetries = 1;
+    const submitRetryIndex = args.indexOf('--submit-retry');
+    if (submitRetryIndex !== -1) {
+      const raw = Number(args[submitRetryIndex + 1]);
+      if (Number.isFinite(raw)) {
+        submitRetries = Math.min(Math.max(Math.floor(raw), 0), 3);
+        args.splice(submitRetryIndex, 2);
+      } else {
+        args.splice(submitRetryIndex, 1);
+      }
+    }
+
     // Extract --from flag
     let fromId;
     const fromIndex = args.indexOf('--from');
@@ -1638,23 +1664,84 @@ async function main() {
       const refSuffix = referencePath ? ` (ref: ${referencePath})` : '';
       console.log(`✅ Context injected successfully into '\x1b[36m${target.id}\x1b[0m'.${refSuffix}`);
 
-      // Terminal-level submit: POST /submit after text injection
+      // Terminal-level submit: POST /submit after text injection.
+      // Daemon-side render-gate handles timing (waits for REPL readiness),
+      // so the CLI no longer needs the legacy 500ms blind sleep. Pass the
+      // injected body so the daemon can verify it was consumed by the input
+      // box and bounded-retry once if not.
+      //
+      // 0.3.3: opt-in --submit-force (gate bypass) and idempotent client-side
+      // retry on retry-safe 504s. The retry guard is gate timeout + body
+      // still visible in the input box (verify.consumed=false) — re-firing
+      // an Enter that genuinely never landed cannot double-submit.
+      // See docs/superpowers/specs/2026-04-26-inject-submit-enter-reliability.md
       if (useSubmit) {
-        await new Promise(resolve => setTimeout(resolve, 500));
-        try {
-          const submitRes = await fetchWithAuth(`http://${target.host}:${PORT}/api/sessions/${encodeURIComponent(target.id)}/submit`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ pre_delay_ms: 600, retries: 2, retry_delay_ms: 500 })
-          });
-          const submitData = await submitRes.json();
-          if (submitRes.ok) {
-            console.log(`✅ Submitted via ${submitData.strategy}${submitData.attempts > 1 ? ` (${submitData.attempts} attempts)` : ''}.`);
-          } else {
-            console.error(`⚠️  Submit failed: ${formatApiError(submitData)}`);
+        const submitBody = {
+          injected_body: injectPrompt || '',
+          retries: 1,
+          retry_delay_ms: 500,
+          ...(submitForce ? { force: true } : {}),
+        };
+        const RETRY_DELAY_MS = 300;
+        const RETRY_SAFE_REASONS = new Set([
+          'gated_dispatch_unconsumed',
+          'gate_timeout',
+          'no_prompt_symbol_seen',
+        ]);
+        const maxAttempts = 1 + submitRetries;
+        let submitRes = null;
+        let submitData = null;
+        let attemptsMade = 0;
+        let lastError = null;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+          if (attempt > 0) {
+            await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+          }
+          attemptsMade = attempt + 1;
+          try {
+            submitRes = await fetchWithAuth(`http://${target.host}:${PORT}/api/sessions/${encodeURIComponent(target.id)}/submit`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(submitBody),
+            });
+            submitData = await submitRes.json();
+          } catch (submitErr) {
+            lastError = submitErr;
+            submitRes = null;
+            submitData = null;
+            break;
           }
-        } catch (submitErr) {
-          console.error(`⚠️  Submit failed: ${submitErr.message}`);
+          if (submitRes.ok) break;
+          if (submitRes.status !== 504) break;
+          const retryReason = submitData && typeof submitData.reason === 'string' ? submitData.reason : null;
+          if (!RETRY_SAFE_REASONS.has(retryReason)) break;
+        }
+        if (lastError) {
+          console.error(`⚠️  Submit failed: ${lastError.message}`);
+        } else if (submitRes && submitRes.ok) {
+          const gateNote = submitData.gated && submitData.gate_wait_ms > 0
+            ? ` [gate ${submitData.gate_wait_ms}ms]`
+            : '';
+          const lateNote = submitData.gated_dispatch_after_timeout
+            ? ' (dispatched-after-gate-timeout)'
+            : '';
+          const attemptsNote = submitData.attempts > 1 ? ` (${submitData.attempts} attempts)` : '';
+          const retryNote = attemptsMade > 1 ? ` [retry ${attemptsMade - 1}/${submitRetries}]` : '';
+          const forcedNote = submitData.forced ? ' [forced]' : '';
+          console.log(`✅ Submitted via ${submitData.strategy}${attemptsNote}${gateNote}${lateNote}${retryNote}${forcedNote}.`);
+        } else if (submitRes && submitRes.status === 504) {
+          // Soft failure: REPL never readied. Orchestrator scripts depend on
+          // exit 0 here — surface a clear remediation hint but do not exit
+          // non-zero.
+          const reason = (submitData && submitData.reason) || 'gate_timeout';
+          const lastState = (submitData && submitData.last_state) || 'unknown';
+          const retriesNote = attemptsMade > 1 ? ` after ${attemptsMade} attempts` : '';
+          const hint = submitForce
+            ? ''
+            : ` Try \`telepty inject --submit --submit-force ${target.id} ...\` or manual \`telepty send-key ${target.id} enter\`.`;
+          console.log(`⚠️  Submit gated-timeout (${reason}, last_state=${lastState})${retriesNote}.${hint}`);
+        } else {
+          console.error(`⚠️  Submit failed: ${formatApiError(submitData)}`);
         }
       }
     } catch (e) { console.error(`❌ ${e.message || 'Failed to connect to the target daemon.'}`); }
@@ -1719,7 +1806,13 @@ async function main() {
         process.exit(1);
       }
 
-      const res = await fetchWithAuth(`http://${target.host}:${PORT}/api/sessions/${encodeURIComponent(target.id)}/submit`, { method: 'POST' });
+      // send-key is a manual override — bypass the render gate via force=true.
+      // See: docs/superpowers/specs/2026-04-26-submit-gate-fixes-v2.md §3.1
+      const res = await fetchWithAuth(`http://${target.host}:${PORT}/api/sessions/${encodeURIComponent(target.id)}/submit`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ force: true }),
+      });
       const data = await res.json();
       if (!res.ok) { console.error(`❌ ${formatApiError(data)}`); return; }
       console.log(`✅ Key '${key}' sent to '\x1b[36m${target.id}\x1b[0m'. (strategy: ${data.strategy})`);