local-commander-agent 0.3.7 → 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 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.
+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.
@@ -40,7 +40,7 @@ Installation and update also add `localcommander` to your Windows **user PATH**.
 
 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.
 
-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.
+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
 
@@ -74,7 +74,7 @@ npx local-commander-agent@latest workspaces
 npx local-commander-agent@latest revoke-workspace <workspaceGrantId>
 ```
 
-`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.
+`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,11 +88,11 @@ npx local-commander-agent@latest deny-command <workspaceGrantId> node
 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.
+`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
 
@@ -133,8 +133,20 @@ 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.
 
-The view lists this Windows user's reporting production-agent instances, process IDs, agent versions, enrolled server origin, relay connection state and recently observed execution sessions. A live process with a snapshot older than ten seconds is **stale**, not connected. An execution session is not an independently identified AI agent. **Model names are unavailable** because the current production relay does not transmit them.
+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.
 
-Each instance retains its last 100 connection/tool events and 32 recently observed sessions in `%LOCALAPPDATA%\LocalCommander\Monitor`. Logs show timestamps, tool names, result codes and session/execution IDs. They exclude credentials, command arguments, file paths, request bodies and tool output. The monitor refreshes every two seconds. `logs --follow` reports a gap if the bounded history is overwritten between reads. Last snapshots remain available after a stop; a new run replaces that state directory's snapshot.
+`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/localcommander.mjs

@@ -172,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",
@@ -181,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"); }
@@ -406,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>",
@@ -458,10 +475,17 @@ async function main() {
     process.stdout.write(JSON.stringify(await statusObject(), null, 2) + "\n");
     return;
   }
-  if (command === "monitor" || command === "logs") {
+  if (command === "monitor" || command === "logs") {
     await runMonitor(path.join(appDataRoot(), "Monitor"), command, args);
-    return;
-  }
+    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

@@ -4,9 +4,38 @@ 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"]);
+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"; }
@@ -39,10 +68,33 @@ export function monitorView(raw, now = Date.now(), alive = pidAlive) {
       ...(event.tool ? { tool: event.tool } : {}), ...(event.code ? { code: event.code } : {}) };
   });
   const running = alive(raw.pid);
-  const age = now - Date.parse(raw.updatedAt);
-  const connection = !running ? "stopped" : age < -5000 || age > 10_000 ? "stale" : raw.connection.state;
+  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 };
+    running, connection, origin, sessions, events, computer: raw.computer ?? null, processName: "lc-agent", executions,
+    efficiency: efficiencyView(raw.efficiency) };
 }
 
 export async function readMonitors(directory) {
@@ -78,25 +130,137 @@ export async function readMonitors(directory) {
 }
 
 function logLine(instance, event) {
-  return [event.at, "pid=" + instance.pid, event.event, event.tool, event.code,
+  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(" ");
 }
 
-export function formatMonitor(result) {
-  const lines = ["Local Commander production monitor", ""];
-  if (!result.instances.length) lines.push("No monitoring snapshots. Start an agent version that supports monitoring; older agents need an update.");
+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) {
-    lines.push("PID " + instance.pid + " | v" + instance.agentVersion + " | " + instance.connection.toUpperCase(),
-      "Server: " + (instance.origin ?? "Not connected yet") + " | Updated: " + instance.updatedAt,
-      "Observed execution sessions (not AI instance identities): " + instance.sessions.length);
-    for (const session of instance.sessions) lines.push("  " + session.sessionId + " | model: unavailable | last seen: " + session.lastSeenAt);
-    lines.push("Recent events:", ...instance.events.slice(-10).map(event => "  " + logLine(instance, event)), "");
+    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.");
   }
-  if (result.unavailable) lines.push("Unavailable or omitted snapshots: " + result.unavailable);
-  lines.push("Models are unavailable: production relay does not report AI model names.");
   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");
@@ -106,10 +270,14 @@ export async function runMonitor(directory, command, args) {
   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");
@@ -119,12 +287,23 @@ export async function runMonitor(directory, command, args) {
         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 {
-        if (repeat && process.stdout.isTTY && !args.includes("--json")) console.clear();
-        process.stdout.write(args.includes("--json") ? JSON.stringify(result) + "\n" : formatMonitor(result));
+        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.7",
+  "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": {