glasspane-mcp 1.29.1 → 1.30.0

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.
@@ -26,7 +26,7 @@ export declare const MCP_PROTOCOL_VERSION: "2025-06-18";
26
26
  export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
27
27
  export declare const SERVER_INFO: {
28
28
  readonly name: "glasspane-mcp";
29
- readonly version: "1.29.1";
29
+ readonly version: "1.30.0";
30
30
  };
31
31
  export declare const PARSE_ERROR = -32700;
32
32
  export declare const INVALID_REQUEST = -32600;
package/dist/errors.d.ts CHANGED
@@ -155,5 +155,18 @@ export interface ToolErrorText {
155
155
  */
156
156
  export declare function formatToolError(code: string, message: string, remedy: string): string;
157
157
  export declare function formatToolErrorShape(error: ToolErrorText): string;
158
+ /**
159
+ * 一道 `GP_E_BAD_PARAMS` 的出路,两个门面共用同一句话(候选 E,2026-11-05)。
160
+ *
161
+ * 缺陷形状:zod 校验失败时,stdio 那一侧写的是 `check the tool's input schema; <issues>`,
162
+ * 而 HTTP 那一侧(`http-gateway.ts` 的 `spec.validate` 失败支)把 `<issues>` **裸着**当成整条
163
+ * remedy 发出去。zod 的原话是对模式失败的描述("Invalid input: expected string, received
164
+ * number at …"),不是一条做得动的动作——curl 的调用方拿到的是一个对问题的复述,而不是下一步。
165
+ * 本仓对 remedy 的口径一直是"agent 照着敲就得做得动",而这条口径不能只在一道门上成立。
166
+ *
167
+ * 放在 `errors.ts` 而不是任一门面的文件里:这一层住的就是"对外怎么措辞",两个门面都从这里取
168
+ * (`tools.ts` 与 `http-gateway.ts` 都已 import 本文件),抄第二份就又是一条事实两种拼写。
169
+ */
170
+ export declare function badParamsRemedy(issues: string): string;
158
171
  export declare function quoteShellArg(value: string): string;
159
172
  //# sourceMappingURL=errors.d.ts.map
@@ -184,6 +184,9 @@ var StreamLineIo = class {
184
184
  bufferedBytes() {
185
185
  return this.output.writableLength;
186
186
  }
187
+ // 注册侧的签名从前只收 `(line)`,而 `LineIo` 接口与内部 `messageHandler` 都带 `raw`:
188
+ // 于是 #16 那句"sha256 of the exact bytes this transport received"在 socket 这一路永远是
189
+ // 拿不到真字节的那一支(2026-11-04 候选 D)。签名与实际传的东西必须一致。
187
190
  onMessage(handler) {
188
191
  this.messageHandler = handler;
189
192
  }
@@ -221,6 +224,9 @@ function formatToolError(code, message, remedy) {
221
224
  function formatToolErrorShape(error) {
222
225
  return formatToolError(error.code, error.message, error.remedy);
223
226
  }
227
+ function badParamsRemedy(issues) {
228
+ return `check the tool's input schema; ${issues}`;
229
+ }
224
230
  var SHELL_INERT_WORD = /^[A-Za-z0-9@%+=:,./_-]+$/;
225
231
  function quoteShellArg(value) {
226
232
  return SHELL_INERT_WORD.test(value) && !value.startsWith("-") ? value : `'${value.split("'").join("'\\''")}'`;
@@ -524,7 +530,7 @@ var EngineJsonRpcClient = class {
524
530
  this.callerCeilingMs = callerCeilingMs;
525
531
  this.surface = surface;
526
532
  this.expectedDaemonMethods = expectedDaemonMethods;
527
- this.io.onMessage((line) => this.handleMessage(line));
533
+ this.io.onMessage((line, raw) => this.handleMessage(line, raw));
528
534
  this.io.onError((error) => {
529
535
  if (error instanceof OversizeFrameError) {
530
536
  this.failOversizedReply(error);
@@ -910,7 +916,7 @@ var EngineJsonRpcClient = class {
910
916
  const byOrder = inferred ? " (attributed by arrival order: this frame echoed no request id, so nothing here confirms that guess \u2014 this is the oldest request this client still tracks, and the daemon answers in the order it received them; a frame matched to a request that way is recorded as inferred, never as verified)" : "";
911
917
  if (frame.error) {
912
918
  this.report(
913
- `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${JSON.stringify(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
919
+ `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${shortFieldValue(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
914
920
  );
915
921
  return;
916
922
  }
@@ -1122,6 +1128,9 @@ var ReconnectingSocketIo = class {
1122
1128
  bufferedBytes() {
1123
1129
  return this.inner?.bufferedBytes() ?? 0;
1124
1130
  }
1131
+ // `LineIo` 声明的是 `(line, raw?)`。这一侧从前只收 `(line)`,TypeScript 的参数双变性
1132
+ // 让窄一点的那个覆盖合法,于是 `raw` 在生产传输上被剪掉而类型检查一声不响(2026-11-04
1133
+ // 候选 D 修的是 `StreamLineIo`,这一枚是同一件事的另一半)。签名与转发的实参都要跟着接口。
1125
1134
  onMessage(handler) {
1126
1135
  this.messageHandler = handler;
1127
1136
  }
@@ -1153,7 +1162,7 @@ var ReconnectingSocketIo = class {
1153
1162
  }
1154
1163
  const socket = this.open(this.socketPath);
1155
1164
  const io = new StreamLineIo(socket, socket);
1156
- io.onMessage((line) => this.messageHandler?.(line));
1165
+ io.onMessage((line, raw) => this.messageHandler?.(line, raw));
1157
1166
  io.onError((error) => {
1158
1167
  if (!(error instanceof OversizeFrameError) && this.inner === io) {
1159
1168
  this.inner = null;
@@ -2292,7 +2301,7 @@ function refusedStateRootMessage(raw, defect) {
2292
2301
  suggested = `${stripFirmlink(path3.posix.normalize(systemHome()))}/.glasspane`;
2293
2302
  } catch {
2294
2303
  }
2295
- return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? "`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>` " : `\`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
2304
+ return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? '`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>` ' : `\`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
2296
2305
  }
2297
2306
  function daemonProjectsPath(daemonStateRoot) {
2298
2307
  const named2 = typeof daemonStateRoot === "string" ? daemonStateRoot.trim() : "";
@@ -2371,7 +2380,7 @@ function refusedProjectsFileOverride(raw, defect) {
2371
2380
  return new ProjectRegistryError(
2372
2381
  GP_E_STATE_ROOT_REFUSED,
2373
2382
  `the ${PROJECTS_FILE_ENV} override this shell was started with ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. This is the override slot of **this process**, not a root the background service reported about itself \u2014 the daemon never reads ${PROJECTS_FILE_ENV} (R7-14), so the value being judged is one an environment, a wrapper, or an agent set for the MCP shell alone. It is not a harmless pointer either: \`gp_project_set\` would have created that directory and re-permissioned it to 0700, then written the project registry \u2014 bundle ids, pids and storage paths \u2014 into it, which is the same authority this module refuses a self-reported root over (\`StateRoot.notADedicatedRoot\`) and refuses an agent-named evidence archive over (\`refuseCandidate\`). Nothing was read and nothing was written by this call: no directory was created, no permission was changed, no projects.json was opened, listed or saved.`,
2374
- `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
2383
+ `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
2375
2384
  );
2376
2385
  }
2377
2386
  function loadRegistry(filePath) {
@@ -2581,7 +2590,7 @@ function saveProjects(filePath, entries) {
2581
2590
  // The refusal above already names the two commands that make the modes true, so the
2582
2591
  // remedy transcribes them instead of sending the reader to repair a file nobody
2583
2592
  // called damaged (B5). Nothing here is a judgement about the registry's contents.
2584
- `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
2593
+ `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
2585
2594
  );
2586
2595
  }
2587
2596
  const errno = error?.code ?? "unknown";
@@ -2732,7 +2741,7 @@ function reloadSentence(changed) {
2732
2741
  return changed ? "the running background service loaded that file once when it started, so gp_attach will keep returning GP_E_NOT_FOUND for this projectId until the service restarts" : "this call rewrote the entry that file already held, field for field, so it left no new registration for the service to pick up \u2014 restarting changes nothing about an entry that was already there";
2733
2742
  }
2734
2743
  function rootDiscriminator() {
2735
- return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
2744
+ return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
2736
2745
  }
2737
2746
  function restartCommand() {
2738
2747
  return `run \`launchctl kickstart -k gui/${currentUid()}/com.glasspane.daemon\` \u2014 if that reports the service was not found, the launchd job was never bootstrapped, so ${daemonUnreachableRemedy()}`;
@@ -3703,19 +3712,19 @@ function passedThroughRegistryError(error) {
3703
3712
  }
3704
3713
  function projectErrorRemedy(code) {
3705
3714
  if (code === GP_E_PROJECT_LIMIT) {
3706
- return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-remove <projectId>\` removes exactly one registration, and \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: $HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects prints the file the service loads by default`;
3715
+ return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-remove <projectId>\` removes exactly one registration, and \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: "$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects prints the file the service loads by default`;
3707
3716
  }
3708
3717
  if (code === GP_E_NOT_FOUND) {
3709
3718
  return "check the projectId; use gp_project_list to view available projects";
3710
3719
  }
3711
3720
  if (code === GP_E_REGISTRY_DRIFT) {
3712
- return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
3721
+ return 'the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon\'s maintenance CLI and the settings panel both rewrite it): read the table with `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.';
3713
3722
  }
3714
3723
  if (code === GP_E_NO_USER_RECORD) {
3715
3724
  return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
3716
3725
  }
3717
3726
  if (code === GP_E_STATE_ROOT_REFUSED) {
3718
- return "the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job's own arguments), and `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path> --evidence-stats` echoes that run's `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched";
3727
+ return 'the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job\'s own arguments), and `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path> --evidence-stats` echoes that run\'s `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched';
3719
3728
  }
3720
3729
  if (code === GP_E_INTERNAL) {
3721
3730
  return `the projects file is the problem, not your arguments: the message above names its path, so read it with ${registryReaders("<that path>")}; repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
@@ -4012,7 +4021,7 @@ function mapAuditError(error, engineMethod = "last_evidence") {
4012
4021
  }
4013
4022
 
4014
4023
  // src/dispatch.ts
4015
- var SERVER_INFO = { name: "glasspane-mcp", version: "1.29.1" };
4024
+ var SERVER_INFO = { name: "glasspane-mcp", version: "1.30.0" };
4016
4025
 
4017
4026
  // src/http-gateway.ts
4018
4027
  var GLASSPANE_HTTP_TOKEN_ENV = "GLASSPANE_HTTP_TOKEN";
@@ -4553,7 +4562,7 @@ async function handleToolForward(name, req, client, res, bodyReadTimeoutMs = DEF
4553
4562
  400,
4554
4563
  GP_E_BAD_PARAMS,
4555
4564
  `invalid arguments for '${name}'`,
4556
- checked.issues
4565
+ badParamsRemedy(checked.issues)
4557
4566
  );
4558
4567
  return;
4559
4568
  }
@@ -160,6 +160,9 @@ var StreamLineIo = class {
160
160
  bufferedBytes() {
161
161
  return this.output.writableLength;
162
162
  }
163
+ // 注册侧的签名从前只收 `(line)`,而 `LineIo` 接口与内部 `messageHandler` 都带 `raw`:
164
+ // 于是 #16 那句"sha256 of the exact bytes this transport received"在 socket 这一路永远是
165
+ // 拿不到真字节的那一支(2026-11-04 候选 D)。签名与实际传的东西必须一致。
163
166
  onMessage(handler) {
164
167
  this.messageHandler = handler;
165
168
  }
@@ -197,6 +200,9 @@ function formatToolError(code, message, remedy) {
197
200
  function formatToolErrorShape(error) {
198
201
  return formatToolError(error.code, error.message, error.remedy);
199
202
  }
203
+ function badParamsRemedy(issues) {
204
+ return `check the tool's input schema; ${issues}`;
205
+ }
200
206
  var SHELL_INERT_WORD = /^[A-Za-z0-9@%+=:,./_-]+$/;
201
207
  function quoteShellArg(value) {
202
208
  return SHELL_INERT_WORD.test(value) && !value.startsWith("-") ? value : `'${value.split("'").join("'\\''")}'`;
@@ -480,7 +486,7 @@ var EngineJsonRpcClient = class {
480
486
  this.callerCeilingMs = callerCeilingMs;
481
487
  this.surface = surface;
482
488
  this.expectedDaemonMethods = expectedDaemonMethods;
483
- this.io.onMessage((line) => this.handleMessage(line));
489
+ this.io.onMessage((line, raw) => this.handleMessage(line, raw));
484
490
  this.io.onError((error) => {
485
491
  if (error instanceof OversizeFrameError) {
486
492
  this.failOversizedReply(error);
@@ -866,7 +872,7 @@ var EngineJsonRpcClient = class {
866
872
  const byOrder = inferred ? " (attributed by arrival order: this frame echoed no request id, so nothing here confirms that guess \u2014 this is the oldest request this client still tracks, and the daemon answers in the order it received them; a frame matched to a request that way is recorded as inferred, never as verified)" : "";
867
873
  if (frame.error) {
868
874
  this.report(
869
- `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${JSON.stringify(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
875
+ `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${shortFieldValue(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
870
876
  );
871
877
  return;
872
878
  }
@@ -1078,6 +1084,9 @@ var ReconnectingSocketIo = class {
1078
1084
  bufferedBytes() {
1079
1085
  return this.inner?.bufferedBytes() ?? 0;
1080
1086
  }
1087
+ // `LineIo` 声明的是 `(line, raw?)`。这一侧从前只收 `(line)`,TypeScript 的参数双变性
1088
+ // 让窄一点的那个覆盖合法,于是 `raw` 在生产传输上被剪掉而类型检查一声不响(2026-11-04
1089
+ // 候选 D 修的是 `StreamLineIo`,这一枚是同一件事的另一半)。签名与转发的实参都要跟着接口。
1081
1090
  onMessage(handler) {
1082
1091
  this.messageHandler = handler;
1083
1092
  }
@@ -1109,7 +1118,7 @@ var ReconnectingSocketIo = class {
1109
1118
  }
1110
1119
  const socket = this.open(this.socketPath);
1111
1120
  const io = new StreamLineIo(socket, socket);
1112
- io.onMessage((line) => this.messageHandler?.(line));
1121
+ io.onMessage((line, raw) => this.messageHandler?.(line, raw));
1113
1122
  io.onError((error) => {
1114
1123
  if (!(error instanceof OversizeFrameError) && this.inner === io) {
1115
1124
  this.inner = null;
@@ -2240,7 +2249,7 @@ function refusedStateRootMessage(raw, defect) {
2240
2249
  suggested = `${stripFirmlink(path3.posix.normalize(systemHome()))}/.glasspane`;
2241
2250
  } catch {
2242
2251
  }
2243
- return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? "`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>` " : `\`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
2252
+ return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? '`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>` ' : `\`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
2244
2253
  }
2245
2254
  function daemonProjectsPath(daemonStateRoot) {
2246
2255
  const named2 = typeof daemonStateRoot === "string" ? daemonStateRoot.trim() : "";
@@ -2319,7 +2328,7 @@ function refusedProjectsFileOverride(raw, defect) {
2319
2328
  return new ProjectRegistryError(
2320
2329
  GP_E_STATE_ROOT_REFUSED,
2321
2330
  `the ${PROJECTS_FILE_ENV} override this shell was started with ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. This is the override slot of **this process**, not a root the background service reported about itself \u2014 the daemon never reads ${PROJECTS_FILE_ENV} (R7-14), so the value being judged is one an environment, a wrapper, or an agent set for the MCP shell alone. It is not a harmless pointer either: \`gp_project_set\` would have created that directory and re-permissioned it to 0700, then written the project registry \u2014 bundle ids, pids and storage paths \u2014 into it, which is the same authority this module refuses a self-reported root over (\`StateRoot.notADedicatedRoot\`) and refuses an agent-named evidence archive over (\`refuseCandidate\`). Nothing was read and nothing was written by this call: no directory was created, no permission was changed, no projects.json was opened, listed or saved.`,
2322
- `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
2331
+ `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
2323
2332
  );
2324
2333
  }
2325
2334
  function loadRegistry(filePath) {
@@ -2529,7 +2538,7 @@ function saveProjects(filePath, entries) {
2529
2538
  // The refusal above already names the two commands that make the modes true, so the
2530
2539
  // remedy transcribes them instead of sending the reader to repair a file nobody
2531
2540
  // called damaged (B5). Nothing here is a judgement about the registry's contents.
2532
- `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
2541
+ `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
2533
2542
  );
2534
2543
  }
2535
2544
  const errno = error?.code ?? "unknown";
@@ -2680,7 +2689,7 @@ function reloadSentence(changed) {
2680
2689
  return changed ? "the running background service loaded that file once when it started, so gp_attach will keep returning GP_E_NOT_FOUND for this projectId until the service restarts" : "this call rewrote the entry that file already held, field for field, so it left no new registration for the service to pick up \u2014 restarting changes nothing about an entry that was already there";
2681
2690
  }
2682
2691
  function rootDiscriminator() {
2683
- return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
2692
+ return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
2684
2693
  }
2685
2694
  function restartCommand() {
2686
2695
  return `run \`launchctl kickstart -k gui/${currentUid()}/com.glasspane.daemon\` \u2014 if that reports the service was not found, the launchd job was never bootstrapped, so ${daemonUnreachableRemedy()}`;
@@ -3651,19 +3660,19 @@ function passedThroughRegistryError(error) {
3651
3660
  }
3652
3661
  function projectErrorRemedy(code) {
3653
3662
  if (code === GP_E_PROJECT_LIMIT) {
3654
- return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-remove <projectId>\` removes exactly one registration, and \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: $HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects prints the file the service loads by default`;
3663
+ return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-remove <projectId>\` removes exactly one registration, and \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: "$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects prints the file the service loads by default`;
3655
3664
  }
3656
3665
  if (code === GP_E_NOT_FOUND) {
3657
3666
  return "check the projectId; use gp_project_list to view available projects";
3658
3667
  }
3659
3668
  if (code === GP_E_REGISTRY_DRIFT) {
3660
- return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
3669
+ return 'the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon\'s maintenance CLI and the settings panel both rewrite it): read the table with `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.';
3661
3670
  }
3662
3671
  if (code === GP_E_NO_USER_RECORD) {
3663
3672
  return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
3664
3673
  }
3665
3674
  if (code === GP_E_STATE_ROOT_REFUSED) {
3666
- return "the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job's own arguments), and `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path> --evidence-stats` echoes that run's `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched";
3675
+ return 'the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job\'s own arguments), and `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path> --evidence-stats` echoes that run\'s `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched';
3667
3676
  }
3668
3677
  if (code === GP_E_INTERNAL) {
3669
3678
  return `the projects file is the problem, not your arguments: the message above names its path, so read it with ${registryReaders("<that path>")}; repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
@@ -3960,7 +3969,7 @@ function mapAuditError(error, engineMethod = "last_evidence") {
3960
3969
  }
3961
3970
 
3962
3971
  // src/dispatch.ts
3963
- var SERVER_INFO = { name: "glasspane-mcp", version: "1.29.1" };
3972
+ var SERVER_INFO = { name: "glasspane-mcp", version: "1.30.0" };
3964
3973
 
3965
3974
  // src/http-gateway.ts
3966
3975
  var GLASSPANE_HTTP_TOKEN_ENV = "GLASSPANE_HTTP_TOKEN";
@@ -4501,7 +4510,7 @@ async function handleToolForward(name, req, client, res, bodyReadTimeoutMs = DEF
4501
4510
  400,
4502
4511
  GP_E_BAD_PARAMS,
4503
4512
  `invalid arguments for '${name}'`,
4504
- checked.issues
4513
+ badParamsRemedy(checked.issues)
4505
4514
  );
4506
4515
  return;
4507
4516
  }
package/dist/index.js CHANGED
@@ -815,6 +815,9 @@ function formatToolError(code, message, remedy) {
815
815
  function formatToolErrorShape(error) {
816
816
  return formatToolError(error.code, error.message, error.remedy);
817
817
  }
818
+ function badParamsRemedy(issues) {
819
+ return `check the tool's input schema; ${issues}`;
820
+ }
818
821
  var SHELL_INERT_WORD = /^[A-Za-z0-9@%+=:,./_-]+$/;
819
822
  function quoteShellArg(value) {
820
823
  return SHELL_INERT_WORD.test(value) && !value.startsWith("-") ? value : `'${value.split("'").join("'\\''")}'`;
@@ -1611,6 +1614,9 @@ var StreamLineIo = class {
1611
1614
  bufferedBytes() {
1612
1615
  return this.output.writableLength;
1613
1616
  }
1617
+ // 注册侧的签名从前只收 `(line)`,而 `LineIo` 接口与内部 `messageHandler` 都带 `raw`:
1618
+ // 于是 #16 那句"sha256 of the exact bytes this transport received"在 socket 这一路永远是
1619
+ // 拿不到真字节的那一支(2026-11-04 候选 D)。签名与实际传的东西必须一致。
1614
1620
  onMessage(handler) {
1615
1621
  this.messageHandler = handler;
1616
1622
  }
@@ -2053,7 +2059,7 @@ var EngineJsonRpcClient = class {
2053
2059
  this.callerCeilingMs = callerCeilingMs;
2054
2060
  this.surface = surface;
2055
2061
  this.expectedDaemonMethods = expectedDaemonMethods;
2056
- this.io.onMessage((line) => this.handleMessage(line));
2062
+ this.io.onMessage((line, raw) => this.handleMessage(line, raw));
2057
2063
  this.io.onError((error) => {
2058
2064
  if (error instanceof OversizeFrameError) {
2059
2065
  this.failOversizedReply(error);
@@ -2439,7 +2445,7 @@ var EngineJsonRpcClient = class {
2439
2445
  const byOrder = inferred ? " (attributed by arrival order: this frame echoed no request id, so nothing here confirms that guess \u2014 this is the oldest request this client still tracks, and the daemon answers in the order it received them; a frame matched to a request that way is recorded as inferred, never as verified)" : "";
2440
2446
  if (frame.error) {
2441
2447
  this.report(
2442
- `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${JSON.stringify(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
2448
+ `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${shortFieldValue(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
2443
2449
  );
2444
2450
  return;
2445
2451
  }
@@ -2651,6 +2657,9 @@ var ReconnectingSocketIo = class {
2651
2657
  bufferedBytes() {
2652
2658
  return this.inner?.bufferedBytes() ?? 0;
2653
2659
  }
2660
+ // `LineIo` 声明的是 `(line, raw?)`。这一侧从前只收 `(line)`,TypeScript 的参数双变性
2661
+ // 让窄一点的那个覆盖合法,于是 `raw` 在生产传输上被剪掉而类型检查一声不响(2026-11-04
2662
+ // 候选 D 修的是 `StreamLineIo`,这一枚是同一件事的另一半)。签名与转发的实参都要跟着接口。
2654
2663
  onMessage(handler) {
2655
2664
  this.messageHandler = handler;
2656
2665
  }
@@ -2682,7 +2691,7 @@ var ReconnectingSocketIo = class {
2682
2691
  }
2683
2692
  const socket = this.open(this.socketPath);
2684
2693
  const io = new StreamLineIo(socket, socket);
2685
- io.onMessage((line) => this.messageHandler?.(line));
2694
+ io.onMessage((line, raw) => this.messageHandler?.(line, raw));
2686
2695
  io.onError((error) => {
2687
2696
  if (!(error instanceof OversizeFrameError) && this.inner === io) {
2688
2697
  this.inner = null;
@@ -3034,7 +3043,7 @@ function refusedStateRootMessage(raw, defect) {
3034
3043
  suggested = `${stripFirmlink(path4.posix.normalize(systemHome()))}/.glasspane`;
3035
3044
  } catch {
3036
3045
  }
3037
- return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? "`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>` " : `\`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
3046
+ return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? '`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>` ' : `\`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
3038
3047
  }
3039
3048
  function daemonProjectsPath(daemonStateRoot) {
3040
3049
  const named2 = typeof daemonStateRoot === "string" ? daemonStateRoot.trim() : "";
@@ -3113,7 +3122,7 @@ function refusedProjectsFileOverride(raw, defect) {
3113
3122
  return new ProjectRegistryError(
3114
3123
  GP_E_STATE_ROOT_REFUSED,
3115
3124
  `the ${PROJECTS_FILE_ENV} override this shell was started with ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. This is the override slot of **this process**, not a root the background service reported about itself \u2014 the daemon never reads ${PROJECTS_FILE_ENV} (R7-14), so the value being judged is one an environment, a wrapper, or an agent set for the MCP shell alone. It is not a harmless pointer either: \`gp_project_set\` would have created that directory and re-permissioned it to 0700, then written the project registry \u2014 bundle ids, pids and storage paths \u2014 into it, which is the same authority this module refuses a self-reported root over (\`StateRoot.notADedicatedRoot\`) and refuses an agent-named evidence archive over (\`refuseCandidate\`). Nothing was read and nothing was written by this call: no directory was created, no permission was changed, no projects.json was opened, listed or saved.`,
3116
- `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
3125
+ `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
3117
3126
  );
3118
3127
  }
3119
3128
  function loadRegistry(filePath) {
@@ -3323,7 +3332,7 @@ function saveProjects(filePath, entries) {
3323
3332
  // The refusal above already names the two commands that make the modes true, so the
3324
3333
  // remedy transcribes them instead of sending the reader to repair a file nobody
3325
3334
  // called damaged (B5). Nothing here is a judgement about the registry's contents.
3326
- `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
3335
+ `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
3327
3336
  );
3328
3337
  }
3329
3338
  const errno = error?.code ?? "unknown";
@@ -3474,7 +3483,7 @@ function reloadSentence(changed) {
3474
3483
  return changed ? "the running background service loaded that file once when it started, so gp_attach will keep returning GP_E_NOT_FOUND for this projectId until the service restarts" : "this call rewrote the entry that file already held, field for field, so it left no new registration for the service to pick up \u2014 restarting changes nothing about an entry that was already there";
3475
3484
  }
3476
3485
  function rootDiscriminator() {
3477
- return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
3486
+ return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
3478
3487
  }
3479
3488
  function restartCommand() {
3480
3489
  return `run \`launchctl kickstart -k gui/${currentUid()}/com.glasspane.daemon\` \u2014 if that reports the service was not found, the launchd job was never bootstrapped, so ${daemonUnreachableRemedy()}`;
@@ -4327,7 +4336,7 @@ async function executeTool(spec, args, engine, session, stdoutDroppedFrames) {
4327
4336
  content: [{ type: "text", text: formatToolError(
4328
4337
  GP_E_BAD_PARAMS,
4329
4338
  `invalid arguments for ${spec.name}`,
4330
- `check the tool's input schema; ${checked.issues}`
4339
+ badParamsRemedy(checked.issues)
4331
4340
  ) }],
4332
4341
  isError: true
4333
4342
  };
@@ -4715,19 +4724,19 @@ function passedThroughRegistryError(error) {
4715
4724
  }
4716
4725
  function projectErrorRemedy(code) {
4717
4726
  if (code === GP_E_PROJECT_LIMIT) {
4718
- return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-remove <projectId>\` removes exactly one registration, and \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: $HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects prints the file the service loads by default`;
4727
+ return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-remove <projectId>\` removes exactly one registration, and \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: "$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects prints the file the service loads by default`;
4719
4728
  }
4720
4729
  if (code === GP_E_NOT_FOUND) {
4721
4730
  return "check the projectId; use gp_project_list to view available projects";
4722
4731
  }
4723
4732
  if (code === GP_E_REGISTRY_DRIFT) {
4724
- return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
4733
+ return 'the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon\'s maintenance CLI and the settings panel both rewrite it): read the table with `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.';
4725
4734
  }
4726
4735
  if (code === GP_E_NO_USER_RECORD) {
4727
4736
  return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
4728
4737
  }
4729
4738
  if (code === GP_E_STATE_ROOT_REFUSED) {
4730
- return "the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job's own arguments), and `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path> --evidence-stats` echoes that run's `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched";
4739
+ return 'the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job\'s own arguments), and `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path> --evidence-stats` echoes that run\'s `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched';
4731
4740
  }
4732
4741
  if (code === GP_E_INTERNAL) {
4733
4742
  return `the projects file is the problem, not your arguments: the message above names its path, so read it with ${registryReaders("<that path>")}; repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
@@ -5054,7 +5063,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
5054
5063
  "2025-03-26",
5055
5064
  MCP_PROTOCOL_VERSION
5056
5065
  ];
5057
- var SERVER_INFO = { name: "glasspane-mcp", version: "1.29.1" };
5066
+ var SERVER_INFO = { name: "glasspane-mcp", version: "1.30.0" };
5058
5067
  var PARSE_ERROR = -32700;
5059
5068
  var INVALID_REQUEST = -32600;
5060
5069
  var METHOD_NOT_FOUND = -32601;
package/dist/io.d.ts CHANGED
@@ -165,7 +165,7 @@ export declare class StreamLineIo implements LineIo {
165
165
  constructor(input: Readable, output: Writable);
166
166
  writeLine(line: string, onHandedOff?: () => void): void;
167
167
  bufferedBytes(): number;
168
- onMessage(handler: (line: string) => void): void;
168
+ onMessage(handler: (line: string, raw?: Buffer) => void): void;
169
169
  onClose(handler: () => void): void;
170
170
  onError(handler: (error: Error) => void): void;
171
171
  close(): void;
@@ -810,6 +810,9 @@ function formatToolError(code, message, remedy) {
810
810
  function formatToolErrorShape(error) {
811
811
  return formatToolError(error.code, error.message, error.remedy);
812
812
  }
813
+ function badParamsRemedy(issues) {
814
+ return `check the tool's input schema; ${issues}`;
815
+ }
813
816
  var SHELL_INERT_WORD = /^[A-Za-z0-9@%+=:,./_-]+$/;
814
817
  function quoteShellArg(value) {
815
818
  return SHELL_INERT_WORD.test(value) && !value.startsWith("-") ? value : `'${value.split("'").join("'\\''")}'`;
@@ -1606,6 +1609,9 @@ var StreamLineIo = class {
1606
1609
  bufferedBytes() {
1607
1610
  return this.output.writableLength;
1608
1611
  }
1612
+ // 注册侧的签名从前只收 `(line)`,而 `LineIo` 接口与内部 `messageHandler` 都带 `raw`:
1613
+ // 于是 #16 那句"sha256 of the exact bytes this transport received"在 socket 这一路永远是
1614
+ // 拿不到真字节的那一支(2026-11-04 候选 D)。签名与实际传的东西必须一致。
1609
1615
  onMessage(handler) {
1610
1616
  this.messageHandler = handler;
1611
1617
  }
@@ -2048,7 +2054,7 @@ var EngineJsonRpcClient = class {
2048
2054
  this.callerCeilingMs = callerCeilingMs;
2049
2055
  this.surface = surface;
2050
2056
  this.expectedDaemonMethods = expectedDaemonMethods;
2051
- this.io.onMessage((line) => this.handleMessage(line));
2057
+ this.io.onMessage((line, raw) => this.handleMessage(line, raw));
2052
2058
  this.io.onError((error) => {
2053
2059
  if (error instanceof OversizeFrameError) {
2054
2060
  this.failOversizedReply(error);
@@ -2434,7 +2440,7 @@ var EngineJsonRpcClient = class {
2434
2440
  const byOrder = inferred ? " (attributed by arrival order: this frame echoed no request id, so nothing here confirms that guess \u2014 this is the oldest request this client still tracks, and the daemon answers in the order it received them; a frame matched to a request that way is recorded as inferred, never as verified)" : "";
2435
2441
  if (frame.error) {
2436
2442
  this.report(
2437
- `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${JSON.stringify(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
2443
+ `late engine reply for '${entry.method}' (id ${entry.id}), ${entry.deadlineMs}ms deadline already reported, is an error frame (${shortFieldValue(frame.error)}): an error answer names no operationId, so nothing can be recorded in the trail for it${byOrder}`
2438
2444
  );
2439
2445
  return;
2440
2446
  }
@@ -2646,6 +2652,9 @@ var ReconnectingSocketIo = class {
2646
2652
  bufferedBytes() {
2647
2653
  return this.inner?.bufferedBytes() ?? 0;
2648
2654
  }
2655
+ // `LineIo` 声明的是 `(line, raw?)`。这一侧从前只收 `(line)`,TypeScript 的参数双变性
2656
+ // 让窄一点的那个覆盖合法,于是 `raw` 在生产传输上被剪掉而类型检查一声不响(2026-11-04
2657
+ // 候选 D 修的是 `StreamLineIo`,这一枚是同一件事的另一半)。签名与转发的实参都要跟着接口。
2649
2658
  onMessage(handler) {
2650
2659
  this.messageHandler = handler;
2651
2660
  }
@@ -2677,7 +2686,7 @@ var ReconnectingSocketIo = class {
2677
2686
  }
2678
2687
  const socket = this.open(this.socketPath);
2679
2688
  const io = new StreamLineIo(socket, socket);
2680
- io.onMessage((line) => this.messageHandler?.(line));
2689
+ io.onMessage((line, raw) => this.messageHandler?.(line, raw));
2681
2690
  io.onError((error) => {
2682
2691
  if (!(error instanceof OversizeFrameError) && this.inner === io) {
2683
2692
  this.inner = null;
@@ -3029,7 +3038,7 @@ function refusedStateRootMessage(raw, defect) {
3029
3038
  suggested = `${stripFirmlink(path4.posix.normalize(systemHome()))}/.glasspane`;
3030
3039
  } catch {
3031
3040
  }
3032
- return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? "`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>` " : `\`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
3041
+ return `the background service's self-reported state root ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. That value is not a choice this process made \u2014 it is the \`stateRoot\` field of the \`hello\` frame the daemon answered, and the engine socket has no peer authentication (SECURITY.md: any process running as this user may answer one), so a reply can name a directory this install does not own. \`gp_project_*\` would have created that directory and re-permissioned it to 0700 before writing projects.json into it, which is the daemon's own \`--state-dir\` guard arriving one step late: \`StateRoot.notADedicatedRoot\` rejects the same two shapes at the argument precisely so that nothing is ever touched. This shell will not create or re-permission that path, and it will NOT quietly fall back to the home default instead \u2014 writing a different file while reporting success is the failure this registry refuses by design. Nothing was read and nothing was written: no directory was created, no permission was changed, no projects.json was opened, listed or saved. Move the service onto a directory this install owns: start it as ` + (suggested === null ? '`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>` ' : `\`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\` (the daemon's own suggested form is \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir ${quoteShellArg(suggested)}\`) `) + `then reconnect so a fresh hello reports the new root, and repeat the call. If the reported root is not one you configured, treat the answer to that handshake as untrusted: another process on this account replied to it.`;
3033
3042
  }
3034
3043
  function daemonProjectsPath(daemonStateRoot) {
3035
3044
  const named2 = typeof daemonStateRoot === "string" ? daemonStateRoot.trim() : "";
@@ -3108,7 +3117,7 @@ function refusedProjectsFileOverride(raw, defect) {
3108
3117
  return new ProjectRegistryError(
3109
3118
  GP_E_STATE_ROOT_REFUSED,
3110
3119
  `the ${PROJECTS_FILE_ENV} override this shell was started with ${defect}, so this shell refuses to use it: ${quoteShellArg(raw)}. This is the override slot of **this process**, not a root the background service reported about itself \u2014 the daemon never reads ${PROJECTS_FILE_ENV} (R7-14), so the value being judged is one an environment, a wrapper, or an agent set for the MCP shell alone. It is not a harmless pointer either: \`gp_project_set\` would have created that directory and re-permissioned it to 0700, then written the project registry \u2014 bundle ids, pids and storage paths \u2014 into it, which is the same authority this module refuses a self-reported root over (\`StateRoot.notADedicatedRoot\`) and refuses an agent-named evidence archive over (\`refuseCandidate\`). Nothing was read and nothing was written by this call: no directory was created, no permission was changed, no projects.json was opened, listed or saved.`,
3111
- `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
3120
+ `this shell's own override is what is configured, not your arguments and not a damaged file: \`unset ${PROJECTS_FILE_ENV}\` for this MCP server process and repeat gp_project_set \u2014 it then writes the projects file of the root the running daemon named in its hello, or the home default \`${quoteShellArg(defaultFile)}\` when it named none. Alternatively point the override at one of those two paths; do not point it at a tree this shell will not create or re-permission, and do not repair a projects file for this refusal \u2014 the refusal names a directory, and no path under it was touched. If the service really is running on a root this shell cannot accept, move the service instead: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`, then reconnect so a fresh hello reports it`
3112
3121
  );
3113
3122
  }
3114
3123
  function loadRegistry(filePath) {
@@ -3318,7 +3327,7 @@ function saveProjects(filePath, entries) {
3318
3327
  // The refusal above already names the two commands that make the modes true, so the
3319
3328
  // remedy transcribes them instead of sending the reader to repair a file nobody
3320
3329
  // called damaged (B5). Nothing here is a judgement about the registry's contents.
3321
- `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
3330
+ `the mode this shell asked for did not stick, so nothing was published: bring it to the daemon's own modes yourself \u2014 \`chmod 700 ${quoteShellArg(dir)}\` and \`chmod 600 ${quoteShellArg(filePath)}\` \u2014 read them back with \`stat -f '%Sp %N' ${quoteShellArg(dir)} ${quoteShellArg(filePath)}\`, and repeat gp_project_set once they say 700 and 600. If chmod answers success and the mode stays loose, the volume ignores permissions: find out with \`ls -lO ${quoteShellArg(dir)}\` (an immutable flag) and \`diskutil info -live ${quoteShellArg(dir)}\` (a read-only or remote mount), and move the service onto a volume that honours them \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <a directory this install owns>\`). Do not repair or overwrite projects.json for this one, and do not set ${FORCE_OVERWRITE_ENV}: the fault is the mode, not the bytes in the file`
3322
3331
  );
3323
3332
  }
3324
3333
  const errno = error?.code ?? "unknown";
@@ -3469,7 +3478,7 @@ function reloadSentence(changed) {
3469
3478
  return changed ? "the running background service loaded that file once when it started, so gp_attach will keep returning GP_E_NOT_FOUND for this projectId until the service restarts" : "this call rewrote the entry that file already held, field for field, so it left no new registration for the service to pick up \u2014 restarting changes nothing about an entry that was already there";
3470
3479
  }
3471
3480
  function rootDiscriminator() {
3472
- return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
3481
+ return 'Tell the two cases apart with the service\'s own answer: gp_project_list reads the file this call wrote, so an entry it lists is on disk, and gp_attach {projectId} is answered by the running service \u2014 an entry the list shows plus an attach that answers GP_E_NOT_FOUND means the service is loading a different projects.json than the one this write reached, not that the write failed. Which file the running service loads is not something this shell guesses from $HOME: `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <root>` moves it to <root>/projects.json, and the daemon reports the root it resolved \u2014 `hello` names the state root under its `stateRoot` key. A daemon predating 1.15.0 omits the key, and an omitted key means "that daemon does not report it", never "so it must be the home default": for those binaries the discriminator below is the only read. Cross-check either way \u2014 `launchctl print gui/' + currentUid() + "/com.glasspane.daemon` prints the arguments the job was started with. If those arguments name a --state-dir, the entry has to go into that root's projects.json (repeat gp_project_set with " + PROJECTS_FILE_ENV + " pointed at <that root>/projects.json \u2014 this shell judges that override with the same path gates it judges every root it writes, because writing there means creating the directory and bringing it to 0700, so a shared scratch tree, a directory this user does not own, or a world-writable one is refused with " + GP_E_STATE_ROOT_REFUSED + " and nothing is written; such a service root is not a place this surface can register into, and the fix is to run the service on a root both sides accept): no restart of the service will make it read anywhere else, so restarting again changes nothing. If they name no --state-dir, the service is on the default root and simply predates this write, and one restart with the command in this notice is what surfaces it.";
3473
3482
  }
3474
3483
  function restartCommand() {
3475
3484
  return `run \`launchctl kickstart -k gui/${currentUid()}/com.glasspane.daemon\` \u2014 if that reports the service was not found, the launchd job was never bootstrapped, so ${daemonUnreachableRemedy()}`;
@@ -4322,7 +4331,7 @@ async function executeTool(spec, args, engine, session, stdoutDroppedFrames) {
4322
4331
  content: [{ type: "text", text: formatToolError(
4323
4332
  GP_E_BAD_PARAMS,
4324
4333
  `invalid arguments for ${spec.name}`,
4325
- `check the tool's input schema; ${checked.issues}`
4334
+ badParamsRemedy(checked.issues)
4326
4335
  ) }],
4327
4336
  isError: true
4328
4337
  };
@@ -4710,19 +4719,19 @@ function passedThroughRegistryError(error) {
4710
4719
  }
4711
4720
  function projectErrorRemedy(code) {
4712
4721
  if (code === GP_E_PROJECT_LIMIT) {
4713
- return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-remove <projectId>\` removes exactly one registration, and \`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: $HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects prints the file the service loads by default`;
4722
+ return `the limit (${MAX_PROJECTS}) counts the entries stored in the projects file named above, so a new registration cannot be made to fit by changing an existing one: gp_project_set with an existing projectId patches that entry and leaves the count where it is. See what is stored with gp_project_list, then free a slot with a removal this product does implement: \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-remove <projectId>\` removes exactly one registration, and \`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --project-prune\` removes only the engine's own test residue \u2014 both take \`--dry-run\` to preview and print JSON, and an unknown id exits 3. A running daemon keeps its own copy of the table, so the removal only sticks after it is restarted (the reply's requiresDaemonRestart says whether one is pending; \`launchctl kickstart -k gui/$(id -u)/com.glasspane.daemon\`). Do NOT hand-edit the projects file: the next daemon save overwrites it. To read the same set without this shell: "$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects prints the file the service loads by default`;
4714
4723
  }
4715
4724
  if (code === GP_E_NOT_FOUND) {
4716
4725
  return "check the projectId; use gp_project_list to view available projects";
4717
4726
  }
4718
4727
  if (code === GP_E_REGISTRY_DRIFT) {
4719
- return "the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon's maintenance CLI and the settings panel both rewrite it): read the table with `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.";
4728
+ return 'the projects file changed between the read that produced this reply and the write it attempted, so nothing was written: re-run the same gp_project_set \u2014 what this refusal wants is a second read, not different arguments. If it repeats, another writer owns that file (the daemon\'s maintenance CLI and the settings panel both rewrite it): read the table with `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --list-projects`, and remember a removal only sticks after the daemon restarts. `GLASSPANE_PROJECTS_FORCE_OVERWRITE=1` moves a file aside before writing, and nothing is overwritten without it.';
4720
4729
  }
4721
4730
  if (code === GP_E_NO_USER_RECORD) {
4722
4731
  return "this process has no entry in the password database, so neither it nor the daemon can know which user's state directory is meant; run the shell as a user that has one (`id -u` / `dscl . -read /Users/<name> NFSHomeDirectory`). Nothing in ~/.glasspane needs repairing for this";
4723
4732
  }
4724
4733
  if (code === GP_E_STATE_ROOT_REFUSED) {
4725
- return "the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job's own arguments), and `$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path> --evidence-stats` echoes that run's `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched";
4734
+ return 'the running service named a state root this shell will not create or re-permission, so nothing was read or written by this call: the refused root is named in the message above, so nothing has to be asked again. To see which root the job really starts with, run `launchctl print gui/$(id -u)/com.glasspane.daemon` (read-only \u2014 it prints the job\'s own arguments), and `"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path> --evidence-stats` echoes that run\'s `dir` under the root it resolved, which is how to confirm a candidate without writing anything. Then start the service with a directory this install owns (`"$HOME/Applications/GlassPane Daemon.app/Contents/MacOS/glasspaned" --state-dir <path>`). Do not repair projects.json for this one \u2014 the refusal names a root, not a file, and no path under that root was touched';
4726
4735
  }
4727
4736
  if (code === GP_E_INTERNAL) {
4728
4737
  return `the projects file is the problem, not your arguments: the message above names its path, so read it with ${registryReaders("<that path>")}; repair or restore the damaged entry, and retry \u2014 or set ${FORCE_OVERWRITE_ENV}=1 and call gp_project_set to rebuild the registry from scratch (the unloadable file is moved aside as <path>.unreadable-<id>, never deleted, and every entry still in it is lost). Do not retry the same read-only call unchanged: it will keep failing.`;
@@ -5049,7 +5058,7 @@ var SUPPORTED_PROTOCOL_VERSIONS = [
5049
5058
  "2025-03-26",
5050
5059
  MCP_PROTOCOL_VERSION
5051
5060
  ];
5052
- var SERVER_INFO = { name: "glasspane-mcp", version: "1.29.1" };
5061
+ var SERVER_INFO = { name: "glasspane-mcp", version: "1.30.0" };
5053
5062
  var PARSE_ERROR = -32700;
5054
5063
  var INVALID_REQUEST = -32600;
5055
5064
  var METHOD_NOT_FOUND = -32601;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glasspane-mcp",
3
- "version": "1.29.1",
3
+ "version": "1.30.0",
4
4
  "description": "GlassPane MCP stdio shell: JSON-RPC 2.0 over stdio bridging an AI agent to the glasspane engine daemon",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",