local-commander-agent 0.3.6 → 0.3.9-issue11.1

package/README.md

@@ -19,8 +19,8 @@ Use **Windows 11 x64** and a currently supported Node.js LTS version meeting the
    ```
 
 2. The installer opens a browser. Sign in to [Local Commander](https://localcmd.app), check the displayed pairing code, and approve this computer. Approve only a pairing you just started yourself.
-3. Choose filesystem access in the local Windows dialog:
-   - **All connected drives — read and write:** approve all currently available drive letters shown in the dialog at once. There is no folder picker or separate approval for each drive.
+3. Choose access in the local Windows dialog:
+   - **Full access - all connected drives (default):** approve the available drive letters, file reads/writes, installed commands and localhost services at once. There is no folder picker or separate approval for Node.
    - **Selected folders:** choose one folder in the folder picker. It starts read/write; more folders and write permission can be added later.
 
    Cancel leaves existing permissions unchanged. On first setup, cancellation stops before enabling autostart or starting the agent. Existing grants are preserved when repeating installation or updating: an update never opts you into all drives.
@@ -34,11 +34,13 @@ Use **Windows 11 x64** and a currently supported Node.js LTS version meeting the
 
 You can close the installation terminal. The agent runs in the background and starts when this Windows user signs in. The PC must be awake and online for remote AI tasks. As a first test, ask the connected assistant to list the files in a folder you approved.
 
+Installation and update also add `localcommander` to your Windows **user PATH**. Open a new CMD/terminal window, then run `localcommander status`, `localcommander monitor --watch`, or `localcommander logs --follow` from any folder. No global npm installation is needed. The launcher uses your required Node.js installation and an installed copy of the CLI, so clearing npm's cache does not remove the command. Fetch newer releases with `npx local-commander-agent@latest update`. Uninstall removes Local Commander's PATH entry and launcher while preserving your other entries.
+
 ## What “all connected drives” means
 
 It expands the **filesystem scope** to the drive letters shown at the moment you consent. It includes available local fixed and removable drives. Mapped network drives and `subst` letters are not included. New drive letters, unavailable drives and unmounted volumes are not automatically added; run `configure-access` again after making the desired drive available. Grants are path/drive-letter based, not tied to a particular removable disk's hardware identity: reusing an approved letter gives access under that letter.
 
-This is not administrator access or an unrestricted shell. Windows permissions, protected Local Commander state/runtime and secret-file filters still apply to file tools. Direct command execution and localhost ports remain separately controlled. Read/write access is powerful: an assistant may read personal documents or change accessible files, and writing startup items, scripts or Git hooks can make programs run later as you. Treat drive-wide write access like permission to run programs. Folder controls are not an OS sandbox for an executable you separately allow. ChatGPT/Claude or your workspace may still ask for their own action confirmations.
+Full access allows installed commands resolved from absolute owner PATH entries or an absolute executable path, plus localhost services. Explicit command/port denials and write restrictions still apply. It does not elevate Windows privileges. Protected Local Commander state/runtime and secret-file filters apply to file tools; programs run with your Windows account's rights, so these controls are not an OS sandbox. ChatGPT/Claude or your workspace may still ask for their own action confirmations. Existing installations keep their current permissions until the owner runs `configure-access` and selects full access using a release that supports it.
 
 ## Manage the installation
 
@@ -72,7 +74,7 @@ npx local-commander-agent@latest workspaces
 npx local-commander-agent@latest revoke-workspace <workspaceGrantId>
 ```
 
-`configure-access` reopens the all-drives/selected-folder choice. **It replaces the current set of filesystem grants and clears their command and localhost permissions.** Choosing a restricted folder actually removes the old broader grants. `approve-workspace` adds another read/write folder without replacing the existing set. `workspaces` shows the grant IDs and permissions to use with the other commands. A successful change restarts an already-running agent to synchronize grants; cancellation does not restart it. A revoked drive is not silently re-added in the background.
+`configure-access` reopens the full-access/selected-folder choice. **It replaces current grants and their restrictions.** Full access enables commands and localhost by default; selected folders start read/write with separate command/port allowlists. Choosing a restricted folder removes old broader grants. `approve-workspace` adds another read/write folder without replacing the existing set. `workspaces` shows grant IDs, full/scoped mode and explicit denials. A successful change restarts an already-running agent to synchronize grants; cancellation does not restart it. A revoked drive is not silently re-added in the background.
 
 To enable or remove individual capabilities, replace the placeholders with a grant ID from `workspaces` and an executable path that actually exists on your PC:
 
@@ -88,6 +90,10 @@ npx local-commander-agent@latest deny-localhost <workspaceGrantId> 3000
 
 `allow-command` associates an exact executable with the name the assistant uses; it does not accept a shell command string. Capability changes are local owner actions, not MCP settings the assistant can silently widen. The all-drives decision always requires the local dialog; there is no `--yes` or environment flag to approve it.
 
+Under full access, `deny-command` and `deny-localhost` exclude the named command or port while other commands/ports remain available. Native `.exe`/`.com` commands receive argument arrays directly. `.cmd`/`.bat` launchers use a hidden PowerShell wrapper and reject cmd metacharacters in arguments; use an explicit interpreter for more complex scripts. Allowing a general interpreter is not containment against it launching a denied program.
+
+The MCP discovery sequence is `workspace_list`, `diagnostics`, `execution_session_open`, requested work, output/status, then session close. Diagnostics reports quota separately from the device's execution slot limit. Its optional `repairSafe` mode releases only expired reservations from this OAuth connection that never acquired a dispatch lease. It never retries work, changes permissions or clears unknown executions.
+
 ## Troubleshooting
 
 | Symptom | What to check |
@@ -114,3 +120,33 @@ npx local-commander-agent@latest
 ```
 
 Enrollment retains the chosen origin. Changing this variable does not move an already paired device or turn the package into a standalone MCP server. Account/device enrollment, OAuth, the control plane and relay are still required.
+
+## Monitor the production connection from CMD
+
+After installing an agent release with monitoring support, run these commands from any CMD window:
+
+```cmd
+npx local-commander-agent@latest monitor
+npx local-commander-agent@latest monitor --watch
+npx local-commander-agent@latest logs --follow
+```
+
+If the CLI is already on PATH, use `localcommander monitor --watch` or `localcommander logs --follow`. `monitor --json` returns a machine-readable snapshot; `logs` prints recent events once. Ctrl+C exits a live view without stopping the agent. These commands only read local monitoring files; they do not install, pair, restart, dispatch cloud work or consume execution quota.
+
+From the development checkout, `npm run monitor` opens this live view using the same installed-agent snapshots. `npm run monitor -- --json` streams the bounded JSON observations. There is no install or build step for the monitor.
+
+The navy/cyan ASCII view groups requested/prepared/accepted/running processes beneath each computer. Each row shows its eight-character work ID (the execution ID prefix), actual child PID when available, command summary, declared model and estimated tokens saved. Connected idle computers show READY. The fixed footer reports Raw/Sent/Saved token estimates and savings percentage from measured output bytes for this run; partial totals are marked when some companions have older snapshots. Completed, rejected, unknown, stale and stopped executions stay out of this screen. Freshness follows authenticated transport activity when the relay advertises monitorHeartbeatV1; three missed negotiated heartbeat intervals mark it stale. Fresh local writes cannot renew transport proof. Older peers/snapshots retain the ten-second rule. Work IDs identify executions; sessions are not AI instance identities. Only computers with snapshots available locally can appear.
+
+In a terminal, `monitor --watch` uses a fixed screen and rewrites only changed lines every two seconds. Computers and work IDs have stable ordering; the footer stays at the bottom as processes start and finish. It fits the terminal size, repaints on resize and reports omitted active processes. It does not scroll or clear/redraw on each refresh; Ctrl+C restores the terminal, colors and cursor. One-shot `monitor` prints the same active-work view; redirected watch output and `--json` are ordinary snapshots. `NO_COLOR=1` disables colors; terminal backgrounds use the sample's navy with cyan status highlights.
+
+The first-use MCP greeting asks which model you use when unknown; approved work continues without an answer. The client can classify each batch with optional `efficiencyProfile: {model: "your-model"}`. Labels are declarations, never verified AI identity or permissions. Repeat the label on each batch; missing metadata stays unknown. No pricing is collected or calculated.
+
+Savings use the existing output-compaction ledger: original/sent bytes are measured, and estimated saved tokens equal saved bytes divided by four. The monitor totals cover this agent run, grouped by declared model, and reset on restart. They are not provider token counts. Older snapshots show unavailable savings rather than a fabricated zero.
+
+The runtime reuses its last 64 shaped terminal results for later completed output reads, so repeated reads match the counted compacted result. The encrypted journal retains the original output. After restart or result-cache eviction, reads fall back to that original output; no historical model attribution or extra savings is invented.
+
+Each instance retains its last 64 observed executions, 100 events, 32 sessions and up to 32 model groups in `%LOCALAPPDATA%\LocalCommander\Monitor`. Known command classes such as `node --test`, `git status` and `npm run build` are shown; arbitrary arguments, paths, inline scripts, headers, credentials, request bodies and tool output are never retained. Child PIDs are runtime notifications; the companion PID is identified separately.
+
+`logs` shows recent events, model/command classifications and measured compaction or passthrough sizes. Its initial review lists the five largest remaining outputs and suggests focused file reads/searches, lower command verbosity or less polling when the observed counts justify it. These are advisory review candidates, not proven avoidable tokens, automatic command changes or caching. `logs --follow` reports overwritten-history gaps. Last snapshots remain inspectable after a stop, and a new run replaces that state directory's snapshot. `monitor --json` includes all bounded observations, including finished work omitted from the live screen.
+
+An older installed agent produces no monitoring snapshot even if it is running; the CLI reports that monitoring is unavailable. Publishing/installing the updated agent is required before these views can report its connection. The existing `status` command remains available for installation and process state.

package/bin/command-path.mjs

@@ -0,0 +1,102 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SHIM_MARKER = "@rem Local Commander managed command\r\n";
+const CLI_FILES = ["package.json", "bin/localcommander.mjs", "bin/monitor.mjs", "bin/command-path.mjs"];
+
+export function commandShim(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) throw Error("PACKAGE_VERSION_INVALID");
+  return SHIM_MARKER + '@echo off\r\nsetlocal DisableDelayedExpansion\r\nnode "%~dp0..\\Versions\\' + version +
+    '\\bin\\localcommander.mjs" %*\r\nexit /b %errorlevel%\r\n';
+}
+
+async function plainDirectory(directory) {
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("INSTALL_DIRECTORY_INVALID");
+}
+async function regularOrMissing(file) {
+  const stat = await fs.lstat(file).catch(error => { if (error.code !== "ENOENT") throw error; });
+  if (stat && (!stat.isFile() || stat.isSymbolicLink())) throw Error("INSTALL_STATE_INVALID");
+}
+
+export async function installCommandFiles(packageRoot, installRoot, version) {
+  const shim = commandShim(version);
+  const runtime = path.join(installRoot, "Versions", version);
+  const bin = path.join(installRoot, "bin");
+  for (const directory of [installRoot, path.join(installRoot, "Versions"), runtime, path.join(runtime, "bin"), bin]) await plainDirectory(directory);
+  for (const file of CLI_FILES) {
+    const source = path.join(packageRoot, file), target = path.join(runtime, file);
+    await regularOrMissing(source);
+    await regularOrMissing(target);
+    if (path.resolve(source).toLowerCase() !== path.resolve(target).toLowerCase()) await fs.copyFile(source, target);
+  }
+  const target = path.join(bin, "localcommander.cmd");
+  await regularOrMissing(target);
+  const previous = await fs.readFile(target, "utf8").catch(error => { if (error.code !== "ENOENT") throw error; });
+  if (previous !== undefined && !previous.startsWith(SHIM_MARKER)) throw Error("COMMAND_SHIM_CONFLICT");
+  await fs.writeFile(target, shim, { mode: 0o600 });
+  return bin;
+}
+
+export async function removeCommandFile(installRoot) {
+  for (const directory of [installRoot, path.join(installRoot, "bin")]) {
+    const stat = await fs.lstat(directory).catch(error => { if (error.code !== "ENOENT") throw error; });
+    if (!stat) return;
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("INSTALL_DIRECTORY_INVALID");
+  }
+  const file = path.join(installRoot, "bin", "localcommander.cmd");
+  await regularOrMissing(file);
+  const content = await fs.readFile(file, "utf8").catch(error => { if (error.code !== "ENOENT") throw error; });
+  if (content?.startsWith(SHIM_MARKER)) await fs.unlink(file);
+}
+
+// Read the registry's raw value so %VARIABLE% entries and its value type survive.
+export const USER_PATH_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$target = $env:LC_COMMAND_BIN
+$remove = $env:LC_COMMAND_PATH_REMOVE -eq '1'
+$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+try {
+  $raw = $key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+  if ($raw -isnot [string]) { throw 'USER_PATH_INVALID' }
+  $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
+  if ($key.GetValueNames() -contains 'Path') { $kind = $key.GetValueKind('Path') }
+  if ($kind -ne [Microsoft.Win32.RegistryValueKind]::String -and $kind -ne [Microsoft.Win32.RegistryValueKind]::ExpandString) { throw 'USER_PATH_INVALID' }
+  $entries = $raw.Split(';')
+  $kept = @($entries | Where-Object {
+    $expanded = [Environment]::ExpandEnvironmentVariables($_.Trim().Trim('"')).Replace('/', '\').TrimEnd('\')
+    -not [string]::Equals($expanded, $target.TrimEnd('\'), [StringComparison]::OrdinalIgnoreCase)
+  })
+  $next = $raw
+  if ($remove) { $next = [string]::Join(';', $kept) }
+  elseif ($kept.Count -eq $entries.Count) {
+    $separator = if ($raw.Length -gt 0 -and -not $raw.EndsWith(';')) { ';' } else { '' }
+    $next = $raw + $separator + $target
+  }
+  if ($next.Length -gt 32766) { throw 'USER_PATH_TOO_LONG' }
+  if ($next -cne $raw) { $key.SetValue('Path', $next, $kind) }
+} finally { $key.Dispose() }
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class LocalCommanderEnvironment {
+  [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, IntPtr word, string value, uint flags, uint timeout, out UIntPtr result);
+}
+'@
+$result = [UIntPtr]::Zero
+[void][LocalCommanderEnvironment]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [IntPtr]::Zero, 'Environment', 2, 1000, [ref]$result)
+Write-Output 'USER_PATH_READY'
+`;
+
+export function updateUserPath(bin, remove = false) {
+  if (!path.isAbsolute(bin) || /[;"\r\n\0]/.test(bin)) throw Error("COMMAND_PATH_INVALID");
+  const result = spawnSync(path.join(process.env.SystemRoot || "C:\\Windows", "System32/WindowsPowerShell/v1.0/powershell.exe"),
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(USER_PATH_SCRIPT, "utf16le").toString("base64")], {
+      windowsHide: true, encoding: "utf8", timeout: 15_000,
+      env: { ...process.env, LC_COMMAND_BIN: bin, LC_COMMAND_PATH_REMOVE: remove ? "1" : "0" }
+    });
+  if (result.error || result.status !== 0 || result.stdout.trim() !== "USER_PATH_READY") throw Error("USER_PATH_UPDATE_FAILED");
+}

package/bin/localcommander.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { runMonitor } from "./monitor.mjs";
+import { installCommandFiles, removeCommandFile, updateUserPath } from "./command-path.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const PACKAGE_META = JSON.parse(await fs.readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
@@ -43,6 +45,7 @@ function currentPath() {
   return path.join(appDataRoot(), "current.json");
 }
 function runtimeSource() {
+  if (PACKAGE_ROOT.toLowerCase() === path.join(versionsDirectory(), VERSION).toLowerCase()) return PACKAGE_ROOT;
   return path.join(PACKAGE_ROOT, "runtime");
 }
 function processFile() {
@@ -169,7 +172,7 @@ function agentEnv() {
 function agentExe(runtimeDir) {
   return path.join(runtimeDir, "LocalCommanderAgent.exe");
 }
-function execAgent(runtimeDir, args, timeout = 30_000) {
+function execAgent(runtimeDir, args, timeout = 30_000) {
   const result = spawnSync(agentExe(runtimeDir), args, {
     windowsHide: true,
     encoding: "utf8",
@@ -178,7 +181,22 @@ function execAgent(runtimeDir, args, timeout = 30_000) {
   });
   if (result.error) fail("AGENT_COMMAND_FAILED");
   return { status: result.status ?? -1, stdout: boundedText(result.stdout), stderr: boundedText(result.stderr) };
-}
+}
+async function fabricCommand(runtimeDir, command) {
+  const chunks = []; let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > 16_384) fail("FABRIC_REQUEST_LIMIT");
+    chunks.push(chunk);
+  }
+  // Private stdin is explicit; no credential arguments, shell, listener or foreground window.
+  const result = spawnSync(path.join(runtimeDir, "node.exe"), [path.join(runtimeDir, "agent.mjs"), command], {
+    input: Buffer.concat(chunks), windowsHide: true, encoding: "utf8", timeout: 30_000,
+    maxBuffer: 2 * 1024 * 1024, env: agentEnv()
+  });
+  if (result.error || result.status !== 0) fail(/^[A-Z0-9_]{1,80}$/u.test(result.stderr?.trim()) ? result.stderr.trim() : "FABRIC_REQUEST_FAILED");
+  process.stdout.write(result.stdout);
+}
 function openBrowser(url) {
   let parsed;
   try { parsed = new URL(url); } catch { fail("PAIRING_URL_INVALID"); }
@@ -364,12 +382,17 @@ async function bootstrap({ chooseWorkspace = true } = {}) {
   }
   registerAutostart(runtimeDir);
   await startAgent();
+  const commandBin = await installCommandFiles(PACKAGE_ROOT, appDataRoot(), VERSION);
+  updateUserPath(commandBin);
   if (previous && previous.version !== VERSION) process.stdout.write("Updated Local Commander from " + previous.version + " to " + VERSION + ".\n");
   process.stdout.write("Local Commander " + VERSION + " is installed and running.\n");
+  process.stdout.write("The localcommander command is on your user PATH. Open a new CMD or terminal window to use it.\n");
 }
 async function uninstall(purgeState) {
   await stopAgent();
   removeAutostart();
+  updateUserPath(path.join(appDataRoot(), "bin"), true);
+  await removeCommandFile(appDataRoot());
   const versions = versionsDirectory();
   if (under(appDataRoot(), versions)) await fs.rm(versions, { recursive: true, force: true });
   await fs.rm(currentPath(), { force: true });
@@ -388,6 +411,9 @@ function help() {
     "Usage:",
     "  npx local-commander-agent@latest              install/pair/start",
     "  npx local-commander-agent@latest status       show local state",
+    "  npx local-commander-agent@latest monitor --watch  production connection and sessions",
+    "  npx local-commander-agent@latest monitor --json   monitoring snapshot as JSON",
+    "  npx local-commander-agent@latest logs --follow    recent production relay events",
     "  npx local-commander-agent@latest start        start background agent",
     "  npx local-commander-agent@latest stop         stop background agent",
     "  npx local-commander-agent@latest restart      restart background agent",
@@ -395,7 +421,9 @@ function help() {
     "  npx local-commander-agent@latest configure-access  choose all connected drives or selected folders",
     "  npx local-commander-agent@latest approve-workspace add another read/write folder",
     "  npx local-commander-agent@latest revoke-workspace <workspaceGrantId>",
-    "  npx local-commander-agent@latest workspaces    list approved workspaces and permissions",
+    "  npx local-commander-agent@latest workspaces    list approved workspaces and permissions",
+    "  localcommander fabric-owner                 owner mailbox request through private stdin",
+    "  localcommander fabric-worker                restricted worker request through private stdin",
     "  npx local-commander-agent@latest allow-write <workspaceGrantId>",
     "  npx local-commander-agent@latest allow-command <workspaceGrantId> <name> <absolute-executable-path>",
     "  npx local-commander-agent@latest allow-localhost <workspaceGrantId> <port>",
@@ -447,6 +475,17 @@ async function main() {
     process.stdout.write(JSON.stringify(await statusObject(), null, 2) + "\n");
     return;
   }
+  if (command === "monitor" || command === "logs") {
+    await runMonitor(path.join(appDataRoot(), "Monitor"), command, args);
+    return;
+  }
+  if (command === "fabric-owner" || command === "fabric-worker") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    const current = await readCurrent();
+    if (!current) fail("AGENT_NOT_INSTALLED");
+    await fabricCommand(current.runtimeDir, command);
+    return;
+  }
   if (command === "configure-access") {
     if (args.length) fail("ARGUMENT_INVALID");
     const current = await readCurrent();

package/bin/monitor.mjs

@@ -0,0 +1,310 @@
+import { lstat, open, readdir } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const STATES = new Set(["starting", "connecting", "connected", "disconnected", "stopped", "failed"]);
+const EVENTS = new Set([...STATES, "execute", "prepare", "status", "output", "cancel", "finished", "cancelled", "unknown", "result", "request_failed", "rejected", "connection_error", "compacted", "passthrough"]);
+const iso = value => typeof value === "string" && /^\d{4}-\d\d-\d\dT[\d:.]+Z$/.test(value) && Number.isFinite(Date.parse(value));
+const invalid = () => { throw Error("MONITOR_DATA_INVALID"); };
+const count = value => Number.isSafeInteger(value) && value >= 0 && value <= 1_000_000_000_000;
+const label = value => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,79}$/.test(value);
+const EXECUTION_STATES = new Set(["requested", "prepared", "accepted", "running", "finished", "failed", "cancelled", "rejected", "unknown", "missing"]);
+const PROCESS_NAMES = new Set(["node", "npm", "npx", "git", "rg", "powershell", "pwsh", "cmd", "tsc", "python", "dotnet", "command",
+  "fs_list", "fs_read", "fs_search", "fs_write", "fs_replace", "git_status", "git_diff", "git_log", "project_snapshot", "localhost_request"]);
+const COMMANDS = new Set(["node --test", ...["status", "diff", "log", "show", "fetch", "pull", "push", "commit"].map(value => "git " + value),
+  ...["test", "install", "ci", "pack", "publish"].map(value => "npm " + value),
+  ...["test", "build", "typecheck", "lint", "dev", "start"].map(value => "npm run " + value),
+  ...[...PROCESS_NAMES].flatMap(value => [value, value + " [args]"])]);
+function profileView(raw) {
+  if (raw === null) return null;
+  if (!raw || !label(raw.model)) invalid();
+  return { model: raw.model };
+}
+function efficiencyView(raw) {
+  if (raw === undefined) return null; // Older agents did not measure monitor savings.
+  if (!raw || raw.scope !== "this_run" || !count(raw.calls) || !count(raw.polls?.status) || !count(raw.polls?.output) ||
+      !Array.isArray(raw.models) || raw.models.length > 32) invalid();
+  const models = raw.models.map(group => {
+    if (!group || (group.model !== null && !label(group.model)) || !count(group.calls) || !count(group.savedBytes) || !count(group.sentBytes)) invalid();
+    return { model: group.model, calls: group.calls, savedBytes: group.savedBytes,
+      sentBytes: group.sentBytes, estimatedSavedTokens: Math.round(group.savedBytes / 4) };
+  });
+  if (models.reduce((sum, group) => sum + group.calls, 0) !== raw.calls) invalid();
+  const savedBytes = models.reduce((sum, group) => sum + group.savedBytes, 0);
+  return { scope: "this_run", calls: raw.calls, polls: { status: raw.polls.status, output: raw.polls.output }, models,
+    savedBytes, estimatedSavedTokens: Math.round(savedBytes / 4),
+    unclassifiedSavedBytes: models.filter(group => group.model === null).reduce((sum, group) => sum + group.savedBytes, 0) };
+}
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code === "EPERM"; }
+}
+
+// Explicit allowlist projection: never print extra fields from a local file.
+export function monitorView(raw, now = Date.now(), alive = pidAlive) {
+  if (!raw || raw.schemaVersion !== 1 || !UUID.test(raw.instanceId) || !Number.isSafeInteger(raw.pid) || raw.pid <= 0 ||
+      typeof raw.agentVersion !== "string" || !/^[A-Za-z0-9._+-]{1,64}$/.test(raw.agentVersion) || !iso(raw.updatedAt) ||
+      !STATES.has(raw.connection?.state) || !Array.isArray(raw.sessions) || raw.sessions.length > 32 ||
+      !Array.isArray(raw.events) || raw.events.length > 100) invalid();
+  let origin = null;
+  if (raw.connection.origin !== null) {
+    const url = new URL(raw.connection.origin);
+    if (url.origin !== raw.connection.origin || url.username || url.password ||
+        !(url.protocol === "https:" || (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) invalid();
+    origin = url.origin;
+  }
+  const sessions = raw.sessions.map(session => {
+    if (!session || !UUID.test(session.sessionId) || !UUID.test(session.workspaceGrantId) || !iso(session.lastSeenAt)) invalid();
+    return { sessionId: session.sessionId, workspaceGrantId: session.workspaceGrantId, lastSeenAt: session.lastSeenAt, model: null };
+  });
+  const events = raw.events.map(event => {
+    if (!event || !Number.isSafeInteger(event.seq) || event.seq < 1 || !iso(event.at) || !EVENTS.has(event.event) ||
+        (event.sessionId !== undefined && !UUID.test(event.sessionId)) || (event.executionId !== undefined && !UUID.test(event.executionId)) ||
+        (event.tool !== undefined && (typeof event.tool !== "string" || !/^[a-z_]{1,64}$/.test(event.tool))) ||
+        (event.code !== undefined && (typeof event.code !== "string" || !/^[A-Z0-9_]{1,64}$/.test(event.code)))) invalid();
+    return { seq: event.seq, at: event.at, event: event.event,
+      ...(event.sessionId ? { sessionId: event.sessionId } : {}), ...(event.executionId ? { executionId: event.executionId } : {}),
+      ...(event.tool ? { tool: event.tool } : {}), ...(event.code ? { code: event.code } : {}) };
+  });
+  const running = alive(raw.pid);
+  if (raw.transportAt !== undefined && !iso(raw.transportAt)) invalid();
+  const age = now - Date.parse(raw.connection.state === "connected" ? raw.transportAt ?? raw.updatedAt : raw.updatedAt);
+  const freshnessMs = raw.freshnessMs ?? 10_000;
+  if (!Number.isInteger(freshnessMs) || freshnessMs < 1000 || freshnessMs > 180_000) invalid();
+  const connection = !running ? "stopped" : age < -5000 || age > freshnessMs ? "stale" : raw.connection.state;
+  if (raw.computer !== undefined && (typeof raw.computer !== "string" || !/^[A-Za-z0-9._-]{1,64}$/.test(raw.computer))) invalid();
+  if (raw.processName !== undefined && raw.processName !== "lc-agent") invalid();
+  if (raw.executions !== undefined && (!Array.isArray(raw.executions) || raw.executions.length > 64)) invalid();
+  const executions = (raw.executions ?? []).map(execution => {
+    if (!execution || !UUID.test(execution.executionId) || !UUID.test(execution.sessionId) || !PROCESS_NAMES.has(execution.name) ||
+        !COMMANDS.has(execution.command) || !EXECUTION_STATES.has(execution.state) ||
+        (execution.pid !== null && (!Number.isSafeInteger(execution.pid) || execution.pid <= 0)) ||
+        ![execution.originalBytes, execution.sentBytes, execution.savedBytes].every(value => value === null || count(value)) ||
+        (execution.reason !== null && (typeof execution.reason !== "string" || !/^[a-z_]{1,80}$/.test(execution.reason)))) invalid();
+    const measured = execution.originalBytes !== null;
+    if (measured ? execution.sentBytes === null || execution.savedBytes === null || execution.sentBytes > execution.originalBytes ||
+        execution.savedBytes !== execution.originalBytes - execution.sentBytes : execution.sentBytes !== null || execution.savedBytes !== null) invalid();
+    const profile = profileView(execution.profile);
+    const active = ["requested", "prepared", "accepted", "running"].includes(execution.state);
+    const state = active && connection !== "connected" ? connection === "stale" ? "stale" : "unknown" : execution.state;
+    return { executionId: execution.executionId, sessionId: execution.sessionId, name: execution.name, command: execution.command,
+      state, pid: execution.pid, profile, originalBytes: execution.originalBytes, sentBytes: execution.sentBytes,
+      savedBytes: execution.savedBytes, reason: execution.reason, estimatedSavedTokens: measured ? Math.round(execution.savedBytes / 4) : null };
+  });
+  return { instanceId: raw.instanceId, pid: raw.pid, agentVersion: raw.agentVersion, updatedAt: raw.updatedAt,
+    running, connection, origin, sessions, events, computer: raw.computer ?? null, processName: "lc-agent", executions,
+    efficiency: efficiencyView(raw.efficiency) };
+}
+
+export async function readMonitors(directory) {
+  let entries;
+  try {
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+    entries = (await readdir(directory)).filter(name => /^[a-f0-9]{64}\.json$/.test(name));
+  } catch (error) {
+    if (error?.code === "ENOENT") return { instances: [], unavailable: 0 };
+    return { instances: [], unavailable: 1 };
+  }
+  const instances = [];
+  let unavailable = Math.max(0, entries.length - 32);
+  for (const name of entries.slice(0, 32)) {
+    try {
+      const file = path.join(directory, name);
+      const stat = await lstat(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) invalid();
+      const handle = await open(file, "r");
+      let contents;
+      try {
+        const buffer = Buffer.alloc(128 * 1024 + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > 128 * 1024) invalid();
+        contents = buffer.subarray(0, bytesRead).toString("utf8");
+      } finally { await handle.close(); }
+      instances.push(monitorView(JSON.parse(contents)));
+    } catch { unavailable++; }
+  }
+  instances.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  return { instances, unavailable };
+}
+
+function logLine(instance, event) {
+  const execution = instance.executions.find(row => row.executionId === event.executionId);
+  return [event.at, "pc=" + (instance.computer ?? "unknown"), "pid=" + instance.pid, event.event, event.tool, event.code,
+    execution && "cmd=" + execution.command,
+    execution?.profile && "model=" + execution.profile.model,
+    execution && ["compacted", "passthrough"].includes(event.event) && "saved=~" + compact(execution.estimatedSavedTokens) +
+      "tok sent=" + execution.sentBytes + "B reason=" + execution.reason,
+    event.sessionId && "session=" + event.sessionId, event.executionId && "execution=" + event.executionId].filter(Boolean).join(" ");
+}
+
+const compact = value => value === null ? "n/a" : value >= 1e6 ? (value / 1e6).toFixed(1) + "M" : value >= 1000 ? (value / 1000).toFixed(1) + "k" : String(value);
+const fit = (value, width) => {
+  const text = String(value);
+  return (text.length > width ? width < 4 ? text.slice(0, width) : text.slice(0, width - 3) + "..." : text).padEnd(width);
+};
+export function formatMonitor(result, columns = process.stdout.columns ?? 120, height = 40, color = false) {
+  const width = Math.max(1, Math.min(160, Number.isFinite(columns) ? Math.floor(columns) : 120));
+  height = Math.max(1, Number.isFinite(height) ? Math.floor(height) : 40);
+  const live = result.instances.filter(instance => instance.running && ["starting", "connecting", "connected"].includes(instance.connection));
+  const pcs = new Map();
+  for (const instance of [...live].sort((a, b) => a.instanceId.localeCompare(b.instanceId))) {
+    const name = instance.computer ?? "unknown";
+    if (!pcs.has(name)) pcs.set(name, []);
+    pcs.get(name).push(instance);
+  }
+  const active = instance => instance.executions.filter(row => ["requested", "prepared", "accepted", "running"].includes(row.state));
+  const jobs = live.reduce((sum, instance) => sum + active(instance).length, 0);
+  const stats = live.map(instance => instance.efficiency).filter(Boolean);
+  const saved = stats.reduce((sum, item) => sum + item.savedBytes, 0);
+  const sent = stats.reduce((sum, item) => sum + item.models.reduce((bytes, group) => bytes + group.sentBytes, 0), 0);
+  const tokens = bytes => "~" + Math.round(bytes / 4).toLocaleString("en-US");
+  const pair = (left, right) => fit(left, Math.max(0, width - right.length - 1)) + " " + right;
+  const lines = [pair("LC >_  Local Commander MCP", "LIVE MONITOR"), "-".repeat(width), "> fleet status", ""];
+  const connected = [...pcs.values()].filter(instances => instances.some(instance => instance.connection === "connected")).length;
+  if (height >= 26 && width >= 60) lines.push(
+    "+-------------+   " + connected + " PCs connected",
+    "| >_ " + fit(jobs ? "RUNNING" : connected ? "READY" : "WAITING", 9) + "|   " + jobs + " active processes",
+    "| LC >_       |   Separate agent sessions",
+    "+-------------+   Parallel work across machines",
+    "      ||",
+    "   ___||___", "");
+  else lines.push(connected + " PCs connected | " + jobs + " active processes", "");
+
+  const body = [];
+  let shown = 0, shownPcs = 0;
+  const footer = [
+    "-".repeat(width),
+    stats.length ? "Raw: " + tokens(saved + sent) + " tokens   Sent: " + tokens(sent) + "   Saved: " + tokens(saved) +
+      "  " + (saved + sent ? Math.round(100 * saved / (saved + sent)) : 0) + "%" + (stats.length < live.length ? " (partial)" : "") :
+      "Raw: n/a   Sent: n/a   Saved: n/a",
+    "~ Tokens: bytes / 4, this run | model: " + (live.some(instance => active(instance).some(row => row.profile)) ? "declared" : "unavailable") +
+      " | Sessions are not AI instance identities.",
+    "Server: " + ([...new Set(live.map(instance => instance.origin).filter(Boolean))].join(", ") || "not connected"),
+    "Ctrl+C exits | logs --follow: history | --json: all observations"
+  ];
+  const capacity = Math.max(0, height - lines.length - footer.length - 1);
+  for (const [name, instances] of [...pcs].sort(([a], [b]) => a.localeCompare(b))) {
+    const pcStats = instances.map(instance => instance.efficiency).filter(Boolean);
+    const pcSaved = pcStats.length ? tokens(pcStats.reduce((sum, item) => sum + item.savedBytes, 0)) : "n/a";
+    const rows = instances.flatMap(active);
+    const state = rows.length ? "RUNNING" : instances.some(instance => instance.connection === "connected") ? "READY" : "CONNECTING";
+    // Keep each process with its PC heading, including in a short terminal.
+    if (capacity - body.length < (rows.length ? width < 60 ? 5 : 4 : 3)) break;
+    body.push(pair("PC " + name + "  |  saved " + pcSaved + " tokens", state));
+    shownPcs++;
+    if (rows.length) {
+      if (width >= 100) body.push("  " + fit("WORK ID", 8) + "  " + fit("PID", 7) + "  " + fit("DOING", width - 70) +
+        "  " + fit("MODEL", 24) + "  " + fit("SAVED TOK", 10) + "  STATE");
+      for (const row of rows.sort((a, b) => a.executionId.localeCompare(b.executionId))) {
+        const id = row.executionId.slice(0, 8), model = row.profile?.model ?? "unavailable";
+        const saving = row.estimatedSavedTokens === null ? "n/a" : "~" + compact(row.estimatedSavedTokens);
+        const entry = width >= 100 ? ["  " + id + "  " + fit(row.pid ?? "-", 7) + "  " + fit(row.command, width - 70) +
+          "  " + fit(model, 24) + "  " + fit(saving, 10) + "  " + row.state.toUpperCase()] : [
+          pair("  " + id + "  " + row.command, row.state.toUpperCase()),
+          ...(width >= 60 ? ["    PID " + (row.pid ?? "-") + " | model " + fit(model, width - 51).trimEnd() + " | saved " + saving + " tok"] :
+            ["    model " + model, "    PID " + (row.pid ?? "-") + " | saved " + saving + " tok"])
+        ];
+        if (body.length + entry.length + 1 > capacity) break;
+        body.push(...entry);
+        shown++;
+      }
+    } else body.push("  Waiting for work");
+    body.push("");
+  }
+  if (!pcs.size) body.push(result.instances.length ? "No active work. Stopped, stale and completed work is hidden." :
+    "No monitoring snapshots. Update/start a monitoring-capable agent.");
+  lines.push(...body.slice(0, capacity));
+  while (lines.length < height - footer.length - 1) lines.push("");
+  lines.push((jobs > shown ? (jobs - shown) + " more active processes | " : "") +
+    (pcs.size > shownPcs ? (pcs.size - shownPcs) + " more PCs | " : "") +
+    "Unavailable/stale/stopped snapshots: " + (result.unavailable + result.instances.length - live.length));
+  lines.push(...footer);
+  // Paint after clipping so ANSI sequences never count toward the terminal width.
+  return lines.slice(0, height).map(line => {
+    const text = fit(line, width);
+    if (!color) return text.trimEnd();
+    const cyan = /^LC |^> |^PC |^[+|]|^\s+[_|]/.test(line);
+    return "\x1b[48;2;15;23;42m\x1b[38;2;" + (cyan ? "0;255;213" : "191;219;254") + "m" +
+      text.replace(/\b(RUNNING|READY|CONNECTED)\b|Saved:.*$/g, value => "\x1b[38;2;0;255;213m" + value + "\x1b[38;2;191;219;254m") + "\x1b[0m";
+  }).join("\n") + "\n";
+}
+
+export function formatInsights(result) {
+  const lines = ["OUTPUT TO REVIEW (recent measured bytes; potential savings unproven):"];
+  const candidates = result.instances.flatMap(instance => instance.executions.filter(row => row.sentBytes > 0)
+    .map(row => ({ ...row, computer: instance.computer ?? "unknown" })))
+    .sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 5);
+  if (!candidates.length) lines.push("  No measured output candidates yet.");
+  for (const row of candidates) lines.push("  " + row.computer + " " + row.executionId.slice(0, 8) + " " + row.command + " | " + compact(row.sentBytes) +
+    " B sent | " + (row.reason ?? "unknown") + " | " +
+    (row.reason === "validated_compact" ? "already compacted; review remaining detail" :
+      row.name === "fs_read" ? "request a focused line range" : row.name === "fs_search" ? "narrow query and maxResults" :
+        "review command verbosity; preserve failures/warnings"));
+  for (const instance of result.instances) {
+    const stats = instance.efficiency;
+    if (stats && stats.polls.status + stats.polls.output >= 10) lines.push("POLLING: " + stats.polls.status + " status / " + stats.polls.output +
+      " output calls on " + (instance.computer ?? "unknown") + "; wait between polls and fetch final output once when practical.");
+  }
+  return lines.join("\n") + "\n";
+}
+
+// Fixed cursor positions: rewrite changed lines only, with no clear/redraw or scrolling.
+export function monitorFrame(previous, next, maxRows = Infinity) {
+  const before = previous ? previous.trimEnd().split("\n") : [];
+  const after = next.trimEnd().split("\n");
+  let output = "";
+  for (let index = 0; index < Math.min(maxRows, Math.max(before.length, after.length)); index++) {
+    if (before[index] !== after[index]) output += "\x1b[" + (index + 1) + ";1H\x1b[2K" + (after[index] ?? "");
+  }
+  return output;
+}
+
+export async function runMonitor(directory, command, args) {
+  const allowed = command === "logs" ? ["--follow"] : ["--watch", "--json"];
+  if (new Set(args).size !== args.length || args.some(arg => !allowed.includes(arg))) throw Error("ARGUMENT_INVALID");
+  const repeat = args.includes("--watch") || args.includes("--follow");
+  const stop = new AbortController();
+  const abort = () => stop.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  const seen = new Map();
+  const fixedScreen = command === "monitor" && repeat && process.stdout.isTTY && !args.includes("--json");
+  let previous = "", previousSize = "", initial = true;
+  if (fixedScreen) process.stdout.write("\x1b[?1049h\x1b[?25l");
+  try {
+    do {
+      const result = await readMonitors(directory);
+      if (command === "logs" && result.instances.length) {
+        if (initial) process.stdout.write(formatInsights(result));
+        for (const instance of result.instances) {
+          const after = seen.get(instance.instanceId) ?? 0;
+          if (after && instance.events[0]?.seq > after + 1) process.stdout.write("Earlier events were overwritten in the 100-event buffer.\n");
+          for (const event of instance.events) if (event.seq > after) process.stdout.write(logLine(instance, event) + "\n");
+          seen.set(instance.instanceId, instance.events.at(-1)?.seq ?? after);
+        }
+        for (const key of seen.keys()) if (!result.instances.some(instance => instance.instanceId === key)) seen.delete(key);
+        if (result.unavailable) process.stderr.write("Some monitoring snapshots are unavailable.\n");
+      } else {
+        const columns = Math.max(1, (process.stdout.columns ?? 120) - 1);
+        const rows = Math.max(1, (process.stdout.rows ?? 40) - 1);
+        const size = columns + "x" + rows;
+        // A resized terminal must repaint even when the snapshot is unchanged.
+        if (fixedScreen && size !== previousSize) previous = "";
+        const next = args.includes("--json") ? JSON.stringify(result) + "\n" :
+          formatMonitor(result, fixedScreen ? columns : undefined, fixedScreen ? rows : undefined,
+            process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb");
+        process.stdout.write(fixedScreen ? monitorFrame(previous, next, Math.max(1, (process.stdout.rows ?? 40) - 1)) : next);
+        previous = next;
+        previousSize = size;
+      }
+      initial = false;
+      if (repeat) await delay(2000, undefined, { signal: stop.signal }).catch(error => { if (error.name !== "AbortError") throw error; });
+    } while (repeat && !stop.signal.aborted);
+  } finally {
+    if (fixedScreen) process.stdout.write("\x1b[0m\x1b[?25h\x1b[?1049l");
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-commander-agent",
-  "version": "0.3.6",
+  "version": "0.3.9-issue11.1",
   "description": "Windows companion for Local Commander: connect AI clients to local files, approved commands and localhost. Requires https://localcmd.app.",
   "type": "module",
   "bin": {