fix: run agent commands longer than the terminal's line limit

docs/next/website/src/content/docs/ja/troubleshooting.mdx

@@ -87,6 +87,29 @@ herdr
 
 サーバーを停止するとペインのプロセスも終了します。Herdr のペインは長時間動作するサーバーの macOS 起動コンテキストを継承するため、SSH やバックグラウンドジョブから起動されたサーバーは対話型 Keychain サービスにアクセスできないことがあります。詳細は [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) を参照してください。
 
+## ペインにコマンドではなく `. /…/staged-commands/…` が表示される
+
+フォアグラウンドのプログラムがカノニカルモードで読み取っている間、ターミナルが 1
+行で受け取れるバイト数には上限があります (macOS では 1024、Linux では 4096)。
+これを超えるとカーネルは行の残りを黙って破棄するため、長いコマンドは切り詰められ
+たまま送られ、実行されません。
+
+そのため `herdr agent start` は 512 バイトを超えるコマンドをプライベートなファイル
+に書き出し、それを実行する短い行を入力します。ペインに表示されるのがこの行です。
+ファイルは実行された時点で削除されます。これより短いコマンドはそのまま入力される
+ため、`--append-system-prompt` のような長い引数のときだけこの表示になります。
+
+この方式が使われるのは、Herdr が読み込み方を把握しているシェルだけです。`sh`、
+`bash`、`dash`、`zsh`、`ksh`、`mksh` は `.` を、`fish` は `source` を使います。
+`csh`、`tcsh`、`nu`、`elvish`、`xonsh` と Windows では、コマンドはそのまま入力され、
+行長制限を受けたままになります。
+
+`herdr pane send-text`、`herdr pane run`、ペインへの貼り付けで送ったテキストは
+そのまま文字として送られるため、引き続きターミナルの行長制限を受けます。シェルは
+見た目以上に頻繁にカノニカルモードになります。`bash` と `zsh` は実行するコマンド
+の間ずっとカノニカルモードに戻り、Ubuntu の `/bin/sh` である `dash` は一度も抜け
+ません。長いテキストはファイルに書き出し、そのファイルを実行してください。
+
 ## `herdr` コマンドが見つからない
 
 ターミナルを再起動して環境を読み込み直し、Herdr のインストール先が `PATH` に含まれていることを確認してください。パッケージマネージャー経由のインストールは、そのパッケージマネージャーから更新して公開する必要があります。[インストール](/ja/docs/install/#verify)を参照してください。

docs/next/website/src/content/docs/troubleshooting.mdx

@@ -87,6 +87,30 @@ herdr
 
 Stopping the server exits its pane processes. Herdr panes inherit the long-lived server's macOS launch context, so a server started through SSH or a background job may not have access to interactive Keychain services. See [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) for details.
 
+## A pane shows `. /…/staged-commands/…` instead of the command
+
+A terminal accepts only a limited number of bytes on a single input line while
+the foreground program is reading in canonical mode — 1024 on macOS, 4096 on
+Linux. Beyond that the kernel silently discards the rest of the line, so a long
+command would be delivered truncated and never run.
+
+`herdr agent start` therefore writes a command longer than 512 bytes to a
+private file and types a short line that runs it, which is what you see in the
+pane. The file is removed the moment it runs. Commands shorter than that are
+typed unchanged, so this only appears for long arguments such as
+`--append-system-prompt`.
+
+Only shells Herdr knows how to source in are staged this way: `sh`, `bash`,
+`dash`, `zsh`, `ksh` and `mksh` use `.`, and `fish` uses `source`. In `csh`,
+`tcsh`, `nu`, `elvish` and `xonsh`, and on Windows, the command is typed
+unchanged and remains subject to the limit.
+
+Text sent with `herdr pane send-text`, `herdr pane run`, or pasted into a pane
+is delivered literally and is still subject to the terminal's line limit. Shells
+are in canonical mode more often than they look: `bash` and `zsh` return to it
+for the duration of every command they run, and `dash` — `/bin/sh` on Ubuntu —
+never leaves it. For long text, write it to a file and run that file instead.
+
 ## The `herdr` command is not found
 
 Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. For package-manager installs, use that package manager to update Herdr and expose it on `PATH`. See [Install Herdr](/docs/install/#verify).

docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx

@@ -87,6 +87,25 @@ herdr
 
 停止服务器会结束窗格进程。Herdr 窗格会继承长期运行服务器的 macOS 启动上下文，因此通过 SSH 或后台任务启动的服务器可能无法访问交互式钥匙串服务。详情见 [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966)。
 
+## 窗格中显示 `. /…/staged-commands/…` 而不是命令
+
+当前台程序以规范模式 (canonical mode) 读取输入时，终端单行只能接受有限的字节数：
+macOS 为 1024，Linux 为 4096。超出部分会被内核静默丢弃，因此过长的命令只会被截断
+送达，而不会执行。
+
+为此，`herdr agent start` 会把超过 512 字节的命令写入一个私有文件，并输入一行短命
+令来运行它，这就是你在窗格中看到的内容。该文件在运行的那一刻即被删除。更短的命令
+会原样输入，所以只有 `--append-system-prompt` 这类长参数才会出现这种显示。
+
+只有 Herdr 知道如何加载的 shell 才会这样暂存：`sh`、`bash`、`dash`、`zsh`、`ksh`
+和 `mksh` 使用 `.`，`fish` 使用 `source`。在 `csh`、`tcsh`、`nu`、`elvish`、`xonsh`
+以及 Windows 上，命令会原样输入，并且仍受行长限制。
+
+通过 `herdr pane send-text`、`herdr pane run` 或粘贴发送到窗格的文本仍按字面逐字送
+达，因此依旧受终端行长限制。shell 处于规范模式的时间比看上去更多：`bash` 和 `zsh`
+在其运行的每条命令期间都会回到规范模式，而 Ubuntu 上作为 `/bin/sh` 的 `dash` 从不
+离开规范模式。文本较长时，请先写入文件再运行该文件。
+
 ## 找不到 `herdr` 命令
 
 重启终端以重新加载环境，然后确认 Herdr 安装目录位于 `PATH` 中。通过软件包管理器安装的 Herdr 必须通过该管理器更新并加入环境。见[安装 Herdr](/zh-cn/docs/install/#verify)。

src/app/agents.rs

@@ -196,24 +196,34 @@ impl App {
         argv.extend(params.args);
         let command = crate::platform::interactive_shell_command(&argv, &shell_name)
             .ok_or(AgentStartError::InvalidArgument)?;
-        let bytes = crate::app::api_helpers::encode_api_submission(runtime, &command);
         let timeout = Duration::from_millis(
             params
                 .timeout_ms
                 .unwrap_or(DEFAULT_AGENT_START_TIMEOUT.as_millis() as u64),
         );
+        // Reject before staging, so no rejected request leaves a payload behind.
         if timeout <= AGENT_START_SETTLE_DELAY || timeout > MAX_AGENT_START_TIMEOUT {
             return Err(AgentStartError::InvalidTimeout);
         }
+        // A composed agent command can carry a system prompt far longer than a
+        // terminal will accept on one line, so stage it rather than type it
+        // (refs #2862).
+        let staged = crate::app::command_delivery::stage(
+            &command,
+            &shell_name,
+            &format!("agent-{}", params.kind),
+        )
+        .map_err(|err| AgentStartError::InputFailed(err.to_string()))?;
+        let bytes = crate::app::api_helpers::encode_api_submission(runtime, &staged.text);
 
         let now = Instant::now();
-        let terminal = self
-            .state
-            .terminals
-            .get_mut(&terminal_id)
-            .ok_or_else(|| AgentStartError::TargetUnavailable(params.pane_id.clone()))?;
+        let Some(terminal) = self.state.terminals.get_mut(&terminal_id) else {
+            staged.discard();
+            return Err(AgentStartError::TargetUnavailable(params.pane_id.clone()));
+        };
         terminal.begin_managed_agent(name.clone(), kind, now, AGENT_START_SETTLE_DELAY, timeout);
         if let Err(err) = runtime.try_send_bytes(Bytes::from(bytes)) {
+            staged.discard();
             terminal.clear_agent_name();
             return Err(AgentStartError::InputFailed(err.to_string()));
         }