aiterm-mcp 0.70.16 → 0.70.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.70.17] - 2026-11-11
11
+
12
+ - On a POSIX terminal where npm linked only `aiterm-mcp` onto the login PATH, Aiterm's other programs on the terminal (`aiterm-remote-terminal` for `path_status` / `make_dir` / `list_dirs` and transcript reads) now run from the same package, as `aiterm-wait` already did. Before, the folder picker failed there with `/bin/sh: aiterm-remote-terminal: not found`.
13
+ - An Aiterm program missing on the terminal (exit 127) now ends as `REMOTE_AITERM_UNAVAILABLE` with an action (install Aiterm with its programs on the login PATH, or provision the terminal), instead of `COMMAND_FAILED`.
14
+
15
+ - After a restart of the controlling host (for example a container restart, which starts a new pid namespace), a terminal's seat MCP forward is started again. The forward lock kept only the old keeper's pid. The new host reused that number at once, here for a thread of a long-lived process, and `kill(pid, 0)` succeeds on a Linux thread id too, so the lock read as held and no process started the forward. Every seat on that terminal lost its BellTeam MCP tools. The lock now also records the boot time and, on Linux, the process start time; a pid that differs in either, or a thread id in an older lock, is not the owner. macOS and Windows have no thread ids in the pid space; a lock from an earlier boot is now also ignored there.
16
+ - A terminal launch no longer receives the stored seat forward port when no keeper is running. Before, the port kept from the previous host was returned at once and the seat started with an MCP URL that reached nothing. Now the launch waits for the new keeper's ssh, or ends with `SEAT_FORWARD_UNAVAILABLE`.
17
+
10
18
  ## [0.70.16] - 2026-11-11
11
19
 
12
20
  - `pty_list` no longer starts an idle-clock checker process for every hibernated, closed or dead seat on every call. A seat without a live session retires its clock at once, so each list re-spawned a checker for it (about 30 per call on a BellTeam host with 50 saved seats and 18 live). The sweep now covers only seats with a live terminal session, and confirms all clock owners with one process read instead of one per seat. On that host this load kept the serving process busy 95 % of the time, with stretches up to 7 s, so a terminal relay's answer often arrived after the 4 s budget and the terminal's seats came back `unread`.
@@ -3261,7 +3269,8 @@ prototype (preserved under `prototype/python/` as the porting source and referen
3261
3269
  `ubuntu-latest` for Node 18/20/22, publishing to npm on `v*` tags with
3262
3270
  provenance.
3263
3271
 
3264
- [Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.70.16...HEAD
3272
+ [Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.70.17...HEAD
3273
+ [0.70.17]: https://github.com/kitepon/aiterm-mcp/compare/v0.70.16...v0.70.17
3265
3274
  [0.70.16]: https://github.com/kitepon/aiterm-mcp/compare/v0.70.15...v0.70.16
3266
3275
  [0.70.15]: https://github.com/kitepon/aiterm-mcp/compare/v0.70.14...v0.70.15
3267
3276
  [0.70.14]: https://github.com/kitepon/aiterm-mcp/compare/v0.70.13...v0.70.14
package/README.ja.md CHANGED
@@ -215,7 +215,7 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
215
215
  場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance(OIDC Trusted
216
216
  Publishing)で公開し、GitHub Release が Official MCP Registry を再登録します。
217
217
 
218
- **状態:** 開発継続中 · 現行公開版 **v0.70.16** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
218
+ **状態:** 開発継続中 · 現行公開版 **v0.70.17** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
219
219
 
220
220
  ### 更新と巻き戻し
221
221
 
package/README.md CHANGED
@@ -227,7 +227,7 @@ collection is off by default and performs no network I/O. It ships via
227
227
  tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
228
228
  Release re-registers the Official MCP Registry entry.
229
229
 
230
- **Status:** actively maintained · current public release **v0.70.16** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
230
+ **Status:** actively maintained · current public release **v0.70.17** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
231
231
 
232
232
  ### Update and rollback
233
233
 
@@ -10,7 +10,7 @@ import { createRequire } from "node:module";
10
10
  import { Client } from "@modelcontextprotocol/sdk/client/index.js";
11
11
  import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
12
12
  import { ensureStateRoot, writeJson0600 } from "./agent-shared.js";
13
- import { WAIT_RESOLVE, powershellForShell, remotePlatform, remoteShell, terminalCommand, terminalProgram } from "./remote.js";
13
+ import { powershellForShell, remotePlatform, remoteShell, terminalCommand, terminalProgram } from "./remote.js";
14
14
  import { PRIVATE_ENV_SCHEMA } from "./private-env.js";
15
15
  import { checkRemotePath } from "./remote-path.js";
16
16
  const pkg = createRequire(import.meta.url)("../package.json");
@@ -167,6 +167,16 @@ export function confirmHostKey(ref, fingerprint) {
167
167
  return bindingStatus(ref);
168
168
  }
169
169
  // ---- connection ----
170
+ const AITERM_MISSING_ACTION = "install Aiterm on the terminal with its programs on the login PATH (npm install -g aiterm-mcp), or provision the terminal";
171
+ /** 255 = ssh failed; 127 = an Aiterm program is missing on the terminal (terminalProgram exits so on every shell). */
172
+ function failedRun(result) {
173
+ if (result.code === 127)
174
+ return new RemoteTerminalError("REMOTE_AITERM_UNAVAILABLE", "an Aiterm program is missing on the terminal (Aiterm is incomplete there)", AITERM_MISSING_ACTION);
175
+ if (result.code !== 255)
176
+ return null;
177
+ const f = classifySshFailure(result.stderr);
178
+ return new RemoteTerminalError(f.code, f.message, f.action);
179
+ }
170
180
  export function classifySshFailure(stderr) {
171
181
  if (/REMOTE HOST IDENTIFICATION HAS CHANGED|Host key for .* has changed/i.test(stderr))
172
182
  return { code: "HOST_KEY_MISMATCH", message: "the terminal presented a different host key", action: "confirm the new host key" };
@@ -176,7 +186,7 @@ export function classifySshFailure(stderr) {
176
186
  return { code: "AUTH_FAILED", message: "the terminal refused the key" };
177
187
  // POSIX, our own Windows guard (any language), and the English cmd / PowerShell wording when it names an Aiterm program.
178
188
  if (/aiterm-[\w-]+: (command )?not found|aiterm-[\w-]+: No such file|aiterm-[\w-]+['"]? is not recognized as (an internal or external command|(the|a) name of a cmdlet)/i.test(stderr))
179
- return { code: "REMOTE_AITERM_UNAVAILABLE", message: "Aiterm is not installed on the terminal" };
189
+ return { code: "REMOTE_AITERM_UNAVAILABLE", message: "Aiterm is not installed on the terminal", action: AITERM_MISSING_ACTION };
180
190
  if (/Connection refused/i.test(stderr))
181
191
  return { code: "CONNECTION_REFUSED", message: "the terminal refused the SSH connection" };
182
192
  if (/timed out|No route to host|Network is unreachable|Could not resolve|Connection closed|Connection reset/i.test(stderr))
@@ -505,17 +515,17 @@ export class RemoteTerminalConnection extends EventEmitter {
505
515
  return parsed;
506
516
  if (parsed?.code)
507
517
  throw new RemoteTerminalError(parsed.code, parsed.message ?? "transcript read failed");
508
- if (result.code === 255) {
509
- const f = classifySshFailure(result.stderr);
510
- throw new RemoteTerminalError(f.code, f.message, f.action);
518
+ {
519
+ const f = failedRun(result);
520
+ if (f)
521
+ throw f;
511
522
  }
512
523
  throw new RemoteTerminalError("COMMAND_FAILED", "the transcript reader failed on the terminal");
513
524
  }
514
525
  /** Run the terminal's aiterm-wait with the flags of a receipt's wait_process; its one-line JSON comes back unchanged. */
515
526
  async wait(waitProcess, signal) {
516
527
  const flags = waitArguments(waitProcess?.args);
517
- // Same resolution as remoteWaitCommand: npm may link only aiterm-mcp.
518
- const result = await this.exec({ posix: `${WAIT_RESOLVE}; exec "$w" ${flags.join(" ")}`, windows: terminalProgram(["aiterm-wait", ...flags]).windows }, 90_000_000, signal);
528
+ const result = await this.exec(terminalProgram(["aiterm-wait", ...flags]), 90_000_000, signal);
519
529
  if (signal?.aborted)
520
530
  throw new RemoteTerminalError("WAIT_CANCELLED", "the wait was cancelled");
521
531
  const line = result.stdout.trim().split("\n").pop() ?? "";
@@ -523,11 +533,7 @@ export class RemoteTerminalConnection extends EventEmitter {
523
533
  return JSON.parse(line);
524
534
  }
525
535
  catch {
526
- if (result.code === 255) {
527
- const f = classifySshFailure(result.stderr);
528
- throw new RemoteTerminalError(f.code, f.message, f.action);
529
- }
530
- throw new RemoteTerminalError("COMMAND_FAILED", "aiterm-wait returned no receipt");
536
+ throw failedRun(result) ?? new RemoteTerminalError("COMMAND_FAILED", "aiterm-wait returned no receipt");
531
537
  }
532
538
  }
533
539
  async command(op, targetPath, harness) {
@@ -596,9 +602,10 @@ export class RemoteTerminalConnection extends EventEmitter {
596
602
  throw new RemoteTerminalError("REMOTE_AITERM_TOO_OLD", `the terminal runs Aiterm ${this.remoteVersion}; ${minimum} or later is required (provision the terminal)`);
597
603
  const sub = op === "path_status" ? "path-status" : "make-dir";
598
604
  const result = await this.exec(terminalProgram(["aiterm-remote-terminal", sub, "--path-base64", Buffer.from(targetPath, "utf8").toString("base64")]), 60_000);
599
- if (result.code === 255) {
600
- const f = classifySshFailure(result.stderr);
601
- throw new RemoteTerminalError(f.code, f.message, f.action);
605
+ {
606
+ const f = failedRun(result);
607
+ if (f)
608
+ throw f;
602
609
  }
603
610
  let parsed = null;
604
611
  try {
@@ -620,9 +627,10 @@ export class RemoteTerminalConnection extends EventEmitter {
620
627
  throw new RemoteTerminalError("REMOTE_AITERM_TOO_OLD", `the terminal runs Aiterm ${this.remoteVersion}; ${minimum} or later is required (update or provision the terminal)`);
621
628
  const flag = targetPath === undefined ? [] : ["--path-base64", Buffer.from(targetPath, "utf8").toString("base64")];
622
629
  const result = await this.exec(terminalProgram(["aiterm-remote-terminal", "list-dirs", ...flag]), 60_000);
623
- if (result.code === 255) {
624
- const f = classifySshFailure(result.stderr);
625
- throw new RemoteTerminalError(f.code, f.message, f.action);
630
+ {
631
+ const f = failedRun(result);
632
+ if (f)
633
+ throw f;
626
634
  }
627
635
  let parsed = null;
628
636
  try {
@@ -807,43 +815,80 @@ function writeBinding(ref, change) {
807
815
  writeJson0600(storePath(), { schema: "aiterm.remote-bindings.v1", bindings });
808
816
  }
809
817
  function lockFile(ref) { return path.join(ensureStateRoot(), `terminal-forward-${ref}.lock`); }
818
+ function lockOwner(ref) {
819
+ try {
820
+ return JSON.parse(fs.readFileSync(lockFile(ref), "utf8"));
821
+ }
822
+ catch {
823
+ return null; /* absent or unreadable: no owner */
824
+ }
825
+ }
826
+ const bootTime = () => Math.round(Date.now() / 1000 - os.uptime());
827
+ /** Linux: the start time (field 22 of /proc/<pid>/stat, counted after the comm's last ") "); null elsewhere. */
828
+ function procStart(pid) {
829
+ try {
830
+ return fs.readFileSync(`/proc/${pid}/stat`, "utf8").split(") ").pop().split(" ")[19] ?? null;
831
+ }
832
+ catch {
833
+ return null;
834
+ }
835
+ }
836
+ /** T3: the recorded owner is this same process still running, not a later process or a thread given the same number. */
837
+ function ownerAlive(owner) {
838
+ const pid = Number(owner.pid);
839
+ if (!(pid > 0))
840
+ return false;
841
+ try {
842
+ process.kill(pid, 0);
843
+ }
844
+ catch {
845
+ return false;
846
+ }
847
+ if (typeof owner.boot === "number" && Math.abs(owner.boot - bootTime()) > 60)
848
+ return false; // from an earlier boot
849
+ if (process.platform !== "linux")
850
+ return true; // shortcut: a pid reused within one boot looks alive until that process exits
851
+ // A container restart reuses pids at once, and kill(pid, 0) also succeeds on a thread id (0.70.16 stayed down).
852
+ if (typeof owner.start === "string")
853
+ return procStart(pid) === owner.start;
854
+ try {
855
+ return /^Tgid:\s*(\d+)$/m.exec(fs.readFileSync(`/proc/${pid}/status`, "utf8"))?.[1] === String(pid);
856
+ }
857
+ catch {
858
+ return true;
859
+ }
860
+ }
810
861
  /** T3: true when this process holds the keeper lock for ref (taking it from a dead owner). */
811
862
  function holdLock(ref) {
812
863
  const file = lockFile(ref);
813
864
  for (let attempt = 0; attempt < 2; attempt++) {
814
865
  try {
815
- fs.writeFileSync(file, JSON.stringify({ pid: process.pid }), { flag: "wx", mode: 0o600 });
866
+ fs.writeFileSync(file, JSON.stringify({ pid: process.pid, boot: bootTime(), start: procStart(process.pid) }), { flag: "wx", mode: 0o600 });
816
867
  return true;
817
868
  }
818
869
  catch (error) {
819
870
  if (error.code !== "EEXIST")
820
871
  return false;
821
- let pid = 0;
822
- try {
823
- pid = Number(JSON.parse(fs.readFileSync(file, "utf8")).pid);
824
- }
825
- catch { /* unreadable: treat as dead */ }
826
- if (pid === process.pid)
872
+ const owner = lockOwner(ref);
873
+ if (Number(owner?.pid) === process.pid)
827
874
  return true;
828
- // shortcut: a reused pid looks alive; the next owner check after that process exits takes over.
829
- try {
830
- if (pid > 0) {
831
- process.kill(pid, 0);
832
- return false;
833
- }
834
- }
835
- catch { /* owner gone */ }
875
+ if (owner && ownerAlive(owner))
876
+ return false;
836
877
  fs.rmSync(file, { force: true });
837
878
  }
838
879
  }
839
880
  return false;
840
881
  }
841
882
  function releaseLock(ref) {
842
- try {
843
- if (Number(JSON.parse(fs.readFileSync(lockFile(ref), "utf8")).pid) === process.pid)
844
- fs.rmSync(lockFile(ref), { force: true });
845
- }
846
- catch { /* none */ }
883
+ if (Number(lockOwner(ref)?.pid) === process.pid)
884
+ fs.rmSync(lockFile(ref), { force: true });
885
+ }
886
+ /** A stored P is usable only while a keeper runs: this process's ssh -R, or another live lock owner's. */
887
+ function forwardLive(ref) {
888
+ const owner = lockOwner(ref);
889
+ if (!owner)
890
+ return false;
891
+ return Number(owner.pid) === process.pid ? Boolean(keepers.get(ref)?.child) : ownerAlive(owner);
847
892
  }
848
893
  function forwardNeeded(ref) {
849
894
  return (keepers.get(ref)?.launchUntil ?? 0) > Date.now() || Object.values(readSeats()).includes(ref);
@@ -971,8 +1016,9 @@ export async function ensureSeatForward(ref, ingress, timeoutMs = 30_000) {
971
1016
  maintainSeatForwards();
972
1017
  const deadline = Date.now() + timeoutMs;
973
1018
  for (;;) {
1019
+ // A P stored by an earlier process (before a restart) without a running keeper reaches nothing.
974
1020
  const port = binding(ref).seat_forward_port;
975
- if (port)
1021
+ if (port && forwardLive(ref))
976
1022
  return port;
977
1023
  if (Date.now() > deadline)
978
1024
  throw new RemoteTerminalError("SEAT_FORWARD_UNAVAILABLE", "the seat's MCP route back to this computer is not ready; launch again later");
package/dist/remote.js CHANGED
@@ -193,8 +193,11 @@ export const powershellInvoke = (argv) => `& ${argv.map(powershellQuote).join("
193
193
  /** 固定のプログラム呼び出し。windowsのaiterm-*は、無い時に言語によらず読める`command not found`を出す。 */
194
194
  export function terminalProgram(argv) {
195
195
  const [program] = argv;
196
+ const file = program.startsWith("aiterm-") ? pkg.bin[program]?.replace(/^dist\//, "") : undefined;
196
197
  return {
197
- posix: `exec ${argv.join(" ")}`,
198
+ // npm may link only aiterm-mcp onto PATH: then the program runs from the same package; else the shell's exit 127.
199
+ posix: file ? `p=$(command -v ${program}) || p="$(dirname "$(readlink -f "$(command -v aiterm-mcp)")")/${file}"; [ -x "$p" ] || p=${program}; exec "$p" ${argv.slice(1).join(" ")}`.trimEnd()
200
+ : `exec ${argv.join(" ")}`,
198
201
  windows: `${program.startsWith("aiterm-") ? `if (-not (Get-Command ${powershellQuote(program)} -ErrorAction SilentlyContinue)) { [Console]::Error.WriteLine(${powershellQuote(`${program}: command not found`)}); exit 127 }; ` : ""}${powershellInvoke(argv)}`,
199
202
  };
200
203
  }
@@ -264,8 +267,6 @@ export async function callRemoteTool(target, name, args, timeoutMs = 600_000, pr
264
267
  await client.close().catch(() => { });
265
268
  }
266
269
  }
267
- // npmのbinをPATHへ通さず aiterm-mcp だけリンクしている端末がある。見つからなければ同じpackageのCLIを使う。
268
- export const WAIT_RESOLVE = 'w=$(command -v aiterm-wait) || w="$(dirname "$(readlink -f "$(command -v aiterm-mcp)")")/aiterm-wait-cli.js"';
269
270
  const SESSION_RE = /^[A-Za-z0-9_-]{1,64}$/;
270
271
  const OPERATION_RE = /^sha256:[0-9a-f]{64}$/;
271
272
  export function remoteWaitCommand(shell, session, cursor, operationId, timeout, inputId, trusted = false) {
@@ -283,10 +284,10 @@ export function remoteWaitCommand(shell, session, cursor, operationId, timeout,
283
284
  if (inputId !== undefined)
284
285
  parts.push("--input", inputId);
285
286
  if (trusted)
286
- return terminalCommand(shell, { posix: `${WAIT_RESOLVE}; exec "$w" ${parts.join(" ")}`, windows: terminalProgram(["aiterm-wait", ...parts]).windows });
287
+ return terminalCommand(shell, terminalProgram(["aiterm-wait", ...parts]));
287
288
  if (shell !== "posix")
288
289
  return `aiterm-wait ${parts.join(" ")}`;
289
- return posixCommand(`${WAIT_RESOLVE}; exec "$w" ${parts.join(" ")}`);
290
+ return posixCommand(terminalProgram(["aiterm-wait", ...parts]).posix);
290
291
  }
291
292
  /** 親が別processで起動する完了待ち。ssh越しのaiterm-waitで、exit codeは現地のaiterm-waitをそのまま返す。 */
292
293
  export async function remoteWaitProcess(target, session, cursor, inputId) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aiterm-mcp",
3
- "version": "0.70.16",
3
+ "version": "0.70.17",
4
4
  "mcpName": "io.github.kitepon/aiterm-mcp",
5
5
  "description": "Persistent terminal MCP with one harness-based launcher for Claude Code, Codex CLI, Grok CLI, Cursor Agent CLI, and Antigravity CLI, plus durable PTYs for SSH, containers, and REPLs.",
6
6
  "keywords": [