Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

fix(agent): require live receiver for mentions

Rahman3e06c70885b3
diff --git a/README.md b/README.md
index 29c53acd..1e6586e4 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy
- **Use BYOK AI** — Alfa and the terminal MSO Agent use credentials stored on your server, not committed to the repo. Bare `mso` opens the interactive setup/operations agent. `mso models` manages AI provider/API/OAuth connections; `mso model` only selects the active model from providers that are already connected.
- **Automate deployment providers without handing tokens to the model** — Dokploy and Cloudflare are built-in feature apps; `mso provider` also supports Hostinger DNS. Secrets stay in owner-only MSO state while bounded provider tools perform live checks and approved deployment/DNS operations. See [docs/INFRASTRUCTURE-PROVIDERS.md](./docs/INFRASTRUCTURE-PROVIDERS.md).
- **Drive the box from ChatGPT, Codex, Claude Code, Cursor, Gemini CLI or VS Code** — Settings → MCP now provides client-specific numbered setup, copy-ready remote configs, live MCP/OAuth discovery checks, tunnel/domain guidance, and the same OAuth 2.1 + PKCE `read → write → exec` permission ladder enforced server-side. See the [ChatGPT Plugin / custom MCP app guide](./docs/CHATGPT-PLUGIN.md) and [MCP reference](./docs/MCP.md).
-- **Message live local sessions by a short name** — every durable same-principal MSO session gets a unique familiar handle such as `@milo`, `@luna`, or `@nara`, independent from its longer auto-generated session title. `/rename <name>` changes that handle, while `/title <text>` changes the session description. `@milo …` resolves active agents only and creates an explicitly correlated request; replies relay deterministically into the originating conversation while notify-only events remain passive. Presence lease (`idle`/`busy`/`offline`) and receiver subscription (`consumerConnected`) are reported separately so an idle-but-unsubscribed target is diagnosable. See [Local Agents](./docs/LOCAL-AGENTS.md).
+- **Message live local sessions by a short name** — every durable same-principal MSO session gets a unique familiar handle such as `@milo`, `@luna`, or `@nara`, independent from its longer auto-generated session title. `/rename <name>` changes that handle, while `/title <text>` changes the session description. `@milo …` resolves only agents with a current lease **and** a live receiver subscription, then creates an explicitly correlated request; replies relay deterministically into the originating conversation while notify-only events remain passive. Presence lease (`idle`/`busy`/`offline`) and receiver subscription (`consumerConnected`) are reported separately so an idle-but-unsubscribed target is diagnosable. See [Local Agents](./docs/LOCAL-AGENTS.md).
- **Spawn focused same-session subagents** — `/spawn` and `agent_subagent_run` create bounded foreground workers with isolated context, explicit delegated scope, turn/timeout caps, no recursive spawn, and final-result-only return. They are not Local Agent peers and do not run autonomously after the parent call returns. See [Subagents](./docs/SUBAGENTS.md).
- **Delegate between remote agents with standard A2A v1** — register public HTTPS peers, attach private API-key/Bearer/OAuth access-token profiles, stream remote tasks over SSE, or expose MSO's authenticated inbound Agent Card when a public HTTPS origin is configured. Inbound credentials are owner-minted `read | write | exec` capabilities and run in a memory-isolated task context. See [A2A](./docs/A2A.md).
- **Keep agents efficient independently of the model provider** — the MCP-first [Cognitive Runtime](./docs/COGNITIVE-RUNTIME.md) isolates conversations from OAuth identity, budgets model context/tool output, selects a compact per-turn capability set without weakening scopes, compacts durable sessions with sanitized 30-day backup archives, and learns only verified workflow recipes. `bun run bench:cognitive` guards routing recall and context footprint.
diff --git a/bin/mso b/bin/mso
index 1b35c650..22b1d0ea 100755
--- a/bin/mso
+++ b/bin/mso
@@ -128,7 +128,7 @@
# Docs: https://github.com/rahmanef63/mso
set -euo pipefail
-VERSION="1.11.0"
+VERSION="1.11.1"
ROOT="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)"
die() { echo "mso: $*" >&2; exit 1; }
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index e49c3878..d2b87e3d 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -19,6 +19,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Fixed**
+- `agent` require live receiver for mentions
- `agent` make restart process-safe
- `a2a` harden remote v1 delegation
diff --git a/docs/LOCAL-AGENTS.md b/docs/LOCAL-AGENTS.md
index ada3c4da..bff2ae40 100644
--- a/docs/LOCAL-AGENTS.md
+++ b/docs/LOCAL-AGENTS.md
@@ -39,7 +39,7 @@ Useful TUI commands:
/inbox
```
-A leading `@rahman …` resolves **active agents only**. If `rahman` is offline/ended, the mention fails clearly and does not silently queue a new request. This prevents a typo/stale handle from becoming a delayed surprise response. The lower-level `local_agent_message_send`/`mso agents send` compatibility surface may still explicitly address a known offline session and retain durable queued delivery.
+A leading `@rahman …` resolves **active agents only**, where active means both a current presence lease and `consumerConnected=true`. If `rahman` is offline/ended or its receiver has disconnected while the lease is still in its grace window, the mention fails clearly and does not silently queue a new request. This prevents a typo/stale handle from becoming a delayed surprise response. The lower-level `local_agent_message_send`/`mso agents send` compatibility surface may still explicitly address a known offline session and retain durable queued delivery.
From the ordinary shell, the same native route has an explicit CLI group for scripting/inspection:
@@ -102,7 +102,7 @@ Interactive CLI sessions maintain a lightweight lease heartbeat and one SSE rece
MCP conversation sessions have no persistent terminal socket, so MSO refreshes their lease around bound MCP tool calls. Messages remain durable when that client is not currently connected and can be read with `local_agent_inbox` on a later call.
-Only `ready`, `idle`, and `busy` sessions appear in the normal active target list. `@mention` is stricter and only resolves this active list. An explicit lower-level send to a known `offline`/`ended` target can still retain a durable queued message; the sender receives `target_offline` instead of a false delivered status.
+Only `ready`, `idle`, and `busy` sessions appear in the normal lease-active target list. `@mention` is stricter: it resolves only those rows that also have `consumerConnected=true`. An explicit lower-level send to a known `offline`/`ended` target can still retain a durable queued message; the sender receives `target_offline` instead of a false delivered status.
## Session names, titles and legacy aliases
diff --git a/docs/TESTING-HANDOFF.md b/docs/TESTING-HANDOFF.md
index 1410887d..2a3c0528 100644
--- a/docs/TESTING-HANDOFF.md
+++ b/docs/TESTING-HANDOFF.md
@@ -71,8 +71,19 @@ Validation minimum: focused unit tests for success, offline target, absent subsc
- Lint: **0 errors / 9 existing max-lines warnings**; the responsive composer tests were split into a dedicated file so this change adds no new warning-only file.
- The first full-load run exposed an overly broad per-principal session-name lock; it was replaced with per-candidate-name locking, after which unrelated conversation/session creation remained concurrent and the full suite passed.
+**Live 1.11.0 smoke finding**
+- Fresh PTYs received familiar names `@omar` and `@cali`; `/rename qa-omar` changed only the handle while the title stayed `MSO Agent session`; `consumerConnected=true/1` was correct while the receiver was attached.
+- A 40×16 PTY rendered one long logical draft across four visual rows; resizing to 72×20 repainted the same draft across two visual rows without submission/data loss.
+- One real race remained: immediately after closing the target PTY, the presence lease was still `idle` for its grace window while `consumerConnected=false`, so `@qa-omar` could still enqueue. The 1.11.1 patch tightens human mention eligibility to **lease current + receiver subscribed** and race-proofs the server send boundary with the same rule. Lower-level explicit mailbox sends keep offline/no-consumer queue compatibility.
+
+**1.11.1 verification**
+- Targeted receiver-required mention patch: **24/24 tests passed**.
+- First full-load gate exposed two test-timing races unrelated to the mention behavior. Session-store concurrency passed immediately when isolated; the gateway exclusion fixture still used a two-second lock-holder despite claiming explicit synchronization. The fixture now holds the lock until the test terminates it.
+- Final full release gate PASS with exit 0: `npm run typecheck`, `npm run lint`, full `npm run test`, `npm run check`, production `npm run build`, and `git diff --check`.
+- Lint remains **0 errors / 9 existing max-lines warnings**. Full-load session-store concurrency and gateway exclusion both pass in the final run.
+
**Open work / handoff**
-- Only live post-deploy PTY smoke remains before treating 1.11 as shipped: generated `@name`, `/rename`, active-only mention, consumer subscription fields, and narrow/resized wrapped composer.
+- Commit/push/deploy 1.11.1, then repeat the close-target mention smoke: immediately after receiver disconnect, the target may still have an `idle` lease but `consumerConnected=false`; human `@name` must be rejected and the mailbox marker count must remain unchanged.
### 2026-09-02 — local agent wake + subagent capacity
diff --git a/lib/agent/local-agent-messaging.test.ts b/lib/agent/local-agent-messaging.test.ts
index e42c2aca..9df53e60 100644
--- a/lib/agent/local-agent-messaging.test.ts
+++ b/lib/agent/local-agent-messaging.test.ts
@@ -126,6 +126,16 @@ describe("native local session agents", () => {
expect(received).toContain(result.message.id);
});
+ it("rejects active-only sends when the lease is alive but no receiver is subscribed", async () => {
+ await presence.touchLocalAgentPresence(owner, b.id, "idle", "test:b");
+ await expect(messaging.sendLocalAgentMessage({
+ principal: owner, senderSessionId: a.id, target: "rahman", text: "must not queue",
+ intent: "request", requiresUserRelay: true, requireActiveTarget: true,
+ })).rejects.toThrow(/not currently active with a receiver/i);
+ const inbox = await mailbox.listLocalAgentInbox(owner, b.id, { includeRead: true });
+ expect(inbox.some((row) => row.text === "must not queue")).toBe(false);
+ });
+
it("returns consumer_absent for a bounded request wait when lease is active but no receiver is subscribed", async () => {
await presence.touchLocalAgentPresence(owner, b.id, "idle", "test:b");
const request = await messaging.sendLocalAgentMessage({
diff --git a/lib/agent/local-agent-messaging.ts b/lib/agent/local-agent-messaging.ts
index 7252ec6e..88434970 100644
--- a/lib/agent/local-agent-messaging.ts
+++ b/lib/agent/local-agent-messaging.ts
@@ -74,8 +74,8 @@ export async function sendLocalAgentMessage(input: {
const correlationId = correlation(input.correlationId) ?? (intent === "request" ? `localcorr_${randomUUID()}` : undefined);
const owner = principalHash(input.principal);
const targetOffline = target.status === "offline" || target.status === "ended";
- if (input.requireActiveTarget && targetOffline)
- throw new Error(`local agent @${target.name} is no longer active; no message was sent`);
+ if (input.requireActiveTarget && (targetOffline || !target.consumerConnected))
+ throw new Error(`local agent @${target.name} is not currently active with a receiver; no message was sent`);
const busy = target.status === "busy";
let message = await enqueueLocalAgentMessage({
principalHash: owner,
diff --git a/scripts/mso-agent-mentions.mjs b/scripts/mso-agent-mentions.mjs
index 60021bd9..f3f9a89e 100644
--- a/scripts/mso-agent-mentions.mjs
+++ b/scripts/mso-agent-mentions.mjs
@@ -15,7 +15,9 @@ export function parseLocalAgentMention(line) {
export function resolveLocalAgentMention(rows, token) {
const wanted = clean(token);
- const activeRows = (Array.isArray(rows) ? rows : []).filter((row) => !["offline", "ended"].includes(String(row?.status || "")));
+ const activeRows = (Array.isArray(rows) ? rows : []).filter((row) =>
+ !["offline", "ended"].includes(String(row?.status || "")) && row?.consumerConnected === true,
+ );
const matches = activeRows.filter((row) => [row?.name, row?.label].map(clean).filter(Boolean).includes(wanted));
if (!matches.length) {
const available = activeRows.map((row) => `@${row.name}`).slice(0, 12).join(", ");
diff --git a/scripts/mso-agent-mentions.test.ts b/scripts/mso-agent-mentions.test.ts
index c3e3b859..083d179f 100644
--- a/scripts/mso-agent-mentions.test.ts
+++ b/scripts/mso-agent-mentions.test.ts
@@ -2,9 +2,10 @@ import { describe, expect, it, vi } from "vitest";
import { dispatchLocalAgentMention, mentionAck, parseLocalAgentMention, resolveLocalAgentMention } from "./mso-agent-mentions.mjs";
const rows = [
- { id: "session-b", name: "milo", alias: "agent-b", label: "[milo]", title: "Session B", titleSource: "auto", status: "idle" },
- { id: "session-z", name: "zahra", alias: "agent-c", label: "[zahra]", title: "Design review", titleSource: "manual", status: "idle" },
- { id: "session-o", name: "luna", alias: "agent-d", label: "[luna]", title: "Offline", titleSource: "auto", status: "offline" },
+ { id: "session-b", name: "milo", alias: "agent-b", label: "[milo]", title: "Session B", titleSource: "auto", status: "idle", consumerConnected: true },
+ { id: "session-z", name: "zahra", alias: "agent-c", label: "[zahra]", title: "Design review", titleSource: "manual", status: "idle", consumerConnected: true },
+ { id: "session-o", name: "luna", alias: "agent-d", label: "[luna]", title: "Offline", titleSource: "auto", status: "offline", consumerConnected: false },
+ { id: "session-g", name: "ghost", alias: "agent-e", label: "[ghost]", title: "Lease only", titleSource: "auto", status: "idle", consumerConnected: false },
];
describe("local agent @mention routing", () => {
@@ -14,6 +15,7 @@ describe("local agent @mention routing", () => {
expect(resolveLocalAgentMention(rows, "zahra").id).toBe("session-z");
expect(() => resolveLocalAgentMention(rows, "agent-b")).toThrow(/not found/i);
expect(() => resolveLocalAgentMention(rows, "luna")).toThrow(/not found/i);
+ expect(() => resolveLocalAgentMention(rows, "ghost")).toThrow(/not found/i);
});
it("fails unknown mentions with active public names only", () => {
@@ -44,8 +46,8 @@ describe("local agent @mention routing", () => {
expect(mentionAck({ target: { label: "[milo]" }, status: "queued" })).toMatch(/target busy/i);
});
- it("explains an active lease with no subscribed receiver instead of pretending it ran", () => {
- expect(mentionAck({ target: { label: "[milo]", consumerConnected: false }, status: "accepted" })).toMatch(/no receiver is subscribed/i);
+ it("does not expose a lease-only target as mentionable", () => {
+ expect(() => resolveLocalAgentMention(rows, "ghost")).toThrow(/not found/i);
});
it("reports bounded lookup timeout without sending anything", async () => {
diff --git a/scripts/mso-gateway-boundaries.test.ts b/scripts/mso-gateway-boundaries.test.ts
index 34a67942..50630568 100644
--- a/scripts/mso-gateway-boundaries.test.ts
+++ b/scripts/mso-gateway-boundaries.test.ts
@@ -74,7 +74,7 @@ esac
// `flock ... command` acquires the lock before executing the command. The ready
// file therefore proves ownership; a fixed sleep is not a synchronization primitive
// when the full suite is deliberately running under nice/ionice.
- const holder = spawn("flock", ["-x", lock, "sh", "-c", 'printf ready > "$1"; sleep 2', "mso-lock-holder", ready], { stdio: "ignore" });
+ const holder = spawn("flock", ["-x", lock, "sh", "-c", 'printf ready > "$1"; while :; do sleep 60; done', "mso-lock-holder", ready], { stdio: "ignore" });
await waitForFile(ready);
try {
const out = spawnSync(GATEWAY, ["local-start"], { encoding: "utf8", env: { ...f.baseEnv,
diff --git a/scripts/mso-model-dx-contract.test.ts b/scripts/mso-model-dx-contract.test.ts
index 5710841f..2d439201 100644
--- a/scripts/mso-model-dx-contract.test.ts
+++ b/scripts/mso-model-dx-contract.test.ts
@@ -29,7 +29,7 @@ const all = [cli, agentCli, configRoute, oauthRoute, slash, picker].join("\n");
describe("MSO model/provider/session CLI contract", () => {
it("keeps provider auth (`models`) separate from active selection (`model`)", () => {
- expect(cli).toContain('VERSION="1.11.0"');
+ expect(cli).toContain('VERSION="1.11.1"');
expect(cli).toContain("models * Configure AI providers/auth");
expect(cli).toContain("model [ref] Select active model");
expect(agentCli).toContain("run_models()");