fix(terminal): refuse to submit a CLI prompt over an unsent composer draft

docs/reference/plugin-authoring.md

@@ -22,12 +22,12 @@ Leave `publisher` out. Orca names the publisher after where the plugin comes fro
 repository, lowercased (`acme` for `github.com/Acme/gleam-syntax`), so the plugin installs as
 `acme.gleam-syntax`. Nobody can choose a publisher name that is not theirs.
 
-| Installed from                | Publisher                                                     |
-| ----------------------------- | ------------------------------------------------------------- |
+| Installed from                    | Publisher                                                    |
+| --------------------------------- | ------------------------------------------------------------ |
 | The official or community catalog | the repository owner, set by the catalog in the entry's `id` |
-| Another catalog               | whatever that catalog's entry `id` says                       |
-| A Git URL                     | the URL's owner (`.` and `_` become `-`)                      |
-| A local or development folder | `local`                                                       |
+| Another catalog                   | whatever that catalog's entry `id` says                      |
+| A Git URL                         | the URL's owner (`.` and `_` become `-`)                     |
+| A local or development folder     | `local`                                                      |
 
 `publisher` is deprecated: Orca ignores it for catalog and Git installs. Leaving it out needs
 `engines.orca` of at least `>=1.4.246`, because older Orca requires the field and refuses a

skill-guides/orca-cli.md

@@ -229,6 +229,7 @@ Terminal rules:
 - Use `terminal read` before `terminal send` unless the next input is obvious.
 - `terminal read` returns accumulated output with escape sequences stripped, not the rendered screen, so anything that repaints (shells, progress bars, TUIs) reads as stacked fragments. Use `--screen` whenever the answer depends on what the terminal actually shows.
 - `--screen` and `--cursor` are mutually exclusive: a screen read is the current frame and has no history to page.
+- `terminal send --text ... --enter` into a Claude Code or Codex composer is refused while the composer holds unsent input (`accepted: false`, `refusedReason: pending-input`, `pendingInput: <draft>`), so a user's draft is never submitted with your text. Wait for the user to send or clear it; pass `--force` only when appending to that draft is intended.
 - Use `terminal send` only for direct terminal input or one-off prompts where no task state, inbox, or reply tracking is needed.
 - `accepted: true` proves input acceptance, not a started turn. Use the receipt's `turn_started` stage when submission proof is needed; never resend on silence.
 - A text-plus-Enter agent prompt is refused with `agent_prompt_blocked` while the agent shows a permission or trust menu. To answer the menu, send `--text` and `--enter` as separate commands.

src/cli/bundled-skill-guides.ts

@@ -641,6 +641,7 @@ const ORCA_CLI_MARKDOWN = [
   "- Use `terminal read` before `terminal send` unless the next input is obvious.",
   "- `terminal read` returns accumulated output with escape sequences stripped, not the rendered screen, so anything that repaints (shells, progress bars, TUIs) reads as stacked fragments. Use `--screen` whenever the answer depends on what the terminal actually shows.",
   "- `--screen` and `--cursor` are mutually exclusive: a screen read is the current frame and has no history to page.",
+  "- `terminal send --text ... --enter` into a Claude Code or Codex composer is refused while the composer holds unsent input (`accepted: false`, `refusedReason: pending-input`, `pendingInput: <draft>`), so a user's draft is never submitted with your text. Wait for the user to send or clear it; pass `--force` only when appending to that draft is intended.",
   "- Use `terminal send` only for direct terminal input or one-off prompts where no task state, inbox, or reply tracking is needed.",
   "- `accepted: true` proves input acceptance, not a started turn. Use the receipt's `turn_started` stage when submission proof is needed; never resend on silence.",
   "- A text-plus-Enter agent prompt is refused with `agent_prompt_blocked` while the agent shows a permission or trust menu. To answer the menu, send `--text` and `--enter` as separate commands.",

src/cli/handlers/terminal-send.ts

@@ -65,6 +65,7 @@ export const terminalSendHandler: CommandHandler = async ({ flags, client, cwd,
           ...(waitSubmitMs ? { waitSubmitMs } : {})
         }
       : {}),
+    ...(flags.get('force') === true ? { allowPendingInput: true as const } : {}),
     client: { id: 'orca-cli', type: 'desktop' }
   }
   const options = promptDeliverySupported
@@ -107,6 +108,7 @@ export const terminalSendHandler: CommandHandler = async ({ flags, client, cwd,
     formatTerminalSend
   )
   if (!result.result.send.accepted) {
+    // Why: callers chain `terminal send && ...`; a refusal must not read as delivered.
     process.exitCode = 1
   }
 }

src/cli/handlers/terminal.test.ts

@@ -446,6 +446,88 @@ describe('terminal send CLI', () => {
     expect(process.exitCode).toBe(1)
   })
 
+  it('passes --force through as allowPendingInput', async () => {
+    const call = vi.fn().mockResolvedValue({
+      result: {
+        send: {
+          handle: 'term-1',
+          accepted: true,
+          bytesWritten: 7,
+          prompt: {
+            requestId: '22222222-2222-4222-8222-222222222222',
+            stages: ['input_accepted', 'turn_started'],
+            provider: 'claude',
+            observation: 'supported',
+            processIncarnation: 'inc-1',
+            generation: 1,
+            baselineWorkingSequence: 0
+          }
+        }
+      }
+    })
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await TERMINAL_HANDLERS['terminal send']({
+      flags: new Map<string, string | true>([
+        ['terminal', 'term-1'],
+        ['text', 'review'],
+        ['enter', true],
+        ['force', true]
+      ]),
+      client: promptClient(call, true),
+      cwd: '/tmp/worktree',
+      json: true
+    })
+
+    expect(call).toHaveBeenCalledWith(
+      'terminal.send',
+      {
+        terminal: 'term-1',
+        text: 'review',
+        enter: true,
+        interrupt: false,
+        agentPrompt: true,
+        allowPendingInput: true,
+        client: { id: 'orca-cli', type: 'desktop' }
+      },
+      { terminalPromptPreflight: { runtimeId: 'runtime-current' } }
+    )
+  })
+
+  it('exits non-zero and reports the draft when the send is refused for pending input', async () => {
+    const call = vi.fn().mockResolvedValue({
+      result: {
+        send: {
+          handle: 'term-1',
+          accepted: false,
+          bytesWritten: 0,
+          refusedReason: 'pending-input',
+          pendingInput: 'Refactor the login page so that it'
+        }
+      }
+    })
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const previousExitCode = process.exitCode
+    try {
+      await TERMINAL_HANDLERS['terminal send']({
+        flags: new Map<string, string | true>([
+          ['terminal', 'term-1'],
+          ['text', 'status update'],
+          ['enter', true]
+        ]),
+        client: promptClient(call, true),
+        cwd: '/tmp/worktree',
+        json: false
+      })
+
+      expect(process.exitCode).toBe(1)
+      expect(String(log.mock.calls[0]?.[0])).toContain('"Refactor the login page so that it"')
+      expect(String(log.mock.calls[0]?.[0])).toContain('--force')
+    } finally {
+      process.exitCode = previousExitCode
+    }
+  })
+
   it('keeps text-only and bare Enter sends as direct terminal input', async () => {
     const call = vi.fn().mockResolvedValue({
       result: { send: { handle: 'term-1', accepted: true, bytesWritten: 1 } }

src/cli/help.ts

@@ -187,6 +187,11 @@ function formatCommandFlagHelp(flag: string, commandPath: string[]): string {
   if (command.startsWith('account ') && flag === 'agent') {
     return '--agent <id>           Account provider: opencode or devin'
   }
+  // Why: the shared --force help describes worktree removal; here it overrides the
+  // pending-input refusal that protects a user's unsent composer draft.
+  if (command === 'terminal send' && flag === 'force') {
+    return '--force                Append to unsent Claude Code/Codex composer input instead of refusing (pending-input)'
+  }
   if (flag === 'key' && command === 'computer hotkey') {
     return '--key <key-combo>      Modifier chord with one key, e.g. CmdOrCtrl+A'
   }

src/cli/root-help-text-secondary.ts

@@ -63,7 +63,7 @@ export const ROOT_HELP_TEXT_SECONDARY = [
   '  orca terminal list [--worktree <selector>] [--limit <n>] [--include-visual-layouts] [--json]',
   '  orca terminal show [--terminal <handle>] [--json]',
   '  orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--screen] [--json]',
-  '  orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--wait-submit <seconds>] [--retry-request <id>] [--json]',
+  '  orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--wait-submit <seconds>] [--retry-request <id>] [--force] [--json]',
   '  orca terminal wait [--terminal <handle>] --for exit|tui-idle [--timeout-ms <ms>] [--json]',
   '  orca agent launch --agent <id> [--worktree <selector>] [--prompt <text>] [--model <id>] [--effort <level>] [--focus] [--json]',
   '  orca terminal create [--worktree <selector>] [--title <name>] [--command <text>] [--shell <shell>] [--focus] [--json]',
@@ -97,6 +97,7 @@ export const ROOT_HELP_TEXT_SECONDARY = [
   '  --interrupt               Send as an interrupt-style input when supported',
   '  --wait-submit <seconds>   Observe this accepted prompt without resending it',
   '  --retry-request <id>      Resume the same durable prompt request after an ambiguous transport failure',
+  '  --force                   Append to unsent Claude Code/Codex composer input instead of refusing (pending-input)',
   '',
   'Terminal List Options:',
   '  --include-visual-layouts  Include tab and pane topology in JSON output',

src/cli/specs/terminal-send.ts

@@ -5,15 +5,16 @@ export const TERMINAL_SEND_COMMAND_SPEC: CommandSpec = {
   path: ['terminal', 'send'],
   summary: 'Send input to a live terminal',
   usage:
-    'orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--wait-submit <seconds>] [--retry-request <id>] [--json]',
+    'orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--wait-submit <seconds>] [--retry-request <id>] [--force] [--json]',
   allowedFlags: [
     ...GLOBAL_FLAGS,
     'terminal',
     'text',
     'enter',
     'interrupt',
     'wait-submit',
-    'retry-request'
+    'retry-request',
+    'force'
   ],
   notes: [
     "Without --enter, --text is written to the PTY verbatim, so control bytes pass through (Bash/Zsh: --text $'\\x1b' for Escape, $'\\x15' for Ctrl+U).",

src/cli/terminal-format.test.ts

@@ -89,6 +89,32 @@ describe('formatTerminalClose', () => {
 })
 
 describe('formatTerminalSend', () => {
+  it('reports delivered bytes only for an accepted send', () => {
+    expect(
+      formatTerminalSend({ send: { handle: 'term_1', accepted: true, bytesWritten: 9 } })
+    ).toBe('Sent 9 bytes to term_1.')
+    expect(
+      formatTerminalSend({ send: { handle: 'term_1', accepted: false, bytesWritten: 0 } })
+    ).toBe('Input refused by term_1.')
+  })
+
+  it('shows the unsent draft and the --force escape hatch for a pending-input refusal', () => {
+    expect(
+      formatTerminalSend({
+        send: {
+          handle: 'term_1',
+          accepted: false,
+          bytesWritten: 0,
+          refusedReason: 'pending-input',
+          pendingInput: 'fix the\nflaky test'
+        }
+      })
+    ).toBe(
+      'Refused: terminal term_1 has unsent input in its composer: "fix the\\nflaky test"\n' +
+        'Wait for the user to send or clear it, or re-run with --force to append to it.'
+    )
+  })
+
   it('exposes the provider and healthy delivery observation', () => {
     expect(
       formatTerminalSend({

src/cli/terminal-format.ts

@@ -174,6 +174,12 @@ function formatTerminalReadLimitedWarning(terminal: RuntimeTerminalRead): string
 }
 
 export function formatTerminalSend(result: { send: RuntimeTerminalSend }): string {
+  if (result.send.refusedReason === 'pending-input') {
+    return [
+      `Refused: terminal ${result.send.handle} has unsent input in its composer: ${JSON.stringify(result.send.pendingInput ?? '')}`,
+      'Wait for the user to send or clear it, or re-run with --force to append to it.'
+    ].join('\n')
+  }
   if (!result.send.accepted) {
     const reason = result.send.refusedReason ? `: ${result.send.refusedReason}` : ''
     return `Input refused by ${result.send.handle}${reason}.`

src/main/daemon/__fixtures__/claude-composer-draft.txt

@@ -0,0 +1 @@
+78[?25h[?25l[?2004h[?1004h[?2031h[>0q[?1049h[?1000h[?1002h[?1003h[?1006h]0;✳ Claude Code ▐▛███▛█Claude Codev2.1.246▝▜██████▀Opus 5 (1M context) with xhigh effort · Claude Max  ▝▝ ▝▝  /private/tmp/orca-fixture/repo✦ ultracode · xhigh effort + dynamic workflows for maximum thoroughness────────────────────────────────────────────────────────────────────────────────────────ultracode─❯ Try "fix typecheck errors"────────────────────────────────────────────────────────────────────────────────────────────────────⏵⏵ auto mode on (shift+tab to cycle) · ← for agents[?25h[?25l⚠1 MCP server needs authentication · run /mcp[?25h[?25l2s ned[?25h(B[?1000h[?1002h[?1003h[?1006h[?25lRefactor the login page sothatit[?25h[?25l[?25h