Envelope guard rejects a workspace passed by name, and names that same workspace as the closest match (5.16.2, regression from #311)

[gcp007-ops]

The envelope guard added in #311 rejects a workspace passed by name, and the rejection offers that same workspace back as its closest match:

Invalid workspace "Desenvolvedor". Closest match: "Desenvolvedor". Use one of these
exact values — do not infer a workspace name from the user's wording.
Available: "default" (global), "Desenvolvedor", "Dev", "Reflexao", ...

Hit on the first call of a session on 5.16.2, running the same vault as #214 (13,432 notes, 8 workspaces).

Repro

Any useTools envelope carrying a real workspace name, on a vault whose boot-time snapshot was empty:

useTools { workspaceId: "Desenvolvedor", tool: "task list-projects --status active" }
→ Invalid workspace "Desenvolvedor". Closest match: "Desenvolvedor". …

useTools { workspaceId: "a8fbad11-7412-49c8-bce0-5690e2c1d197", tool: "task list-projects --status active" }
→ 5 projects

Same workspace, both forms. The UUID passes, the name does not — which isolates the acceptance path as the only difference.

The two halves of the mandatory pair now contradict each other

getTools is a required first step, and on 5.16.2 it grounds the caller by returning the live list in the RESULT — the whole point of #311:

workspaces: ["default", "Default Workspace", "Desenvolvedor", "Dev", …]
workspacesNote: "These are the only workspaces that exist. Pass one of these exact
names — do not infer a workspace name from the user's wording."

useTools then receives one of those exact names and answers with "do not infer a workspace name from the user's wording". An agent that follows the grounding instruction perfectly is told it invented the name.

Cause

ToolBatchExecutionService.validateWorkspaceId checks the name and the id against different lists:

const byName = this.knownWorkspaces.find(w => w.name.toLowerCase() === workspaceId.toLowerCase());
if (byName) return null;                      // boot-time snapshot

const workspaces = await workspaceService.listWorkspaces();
const byUuid = workspaces.find(w => w.id === workspaceId);
if (byUuid) return null;                      // live list — id only

The name is only ever tested against knownWorkspaces. That is the same boot-time snapshot #311 deliberately stopped trusting three lines further down:

Name the alternatives off the LIVE list, not knownWorkspaces — that snapshot is taken at boot and is empty whenever SQLite was not ready then

So the error message reads from the live list and the acceptance does not. On exactly the vaults where the snapshot is empty — the ones #311 was written for — every by-name call is rejected, and matchWorkspaces then finds the real workspace and prints it as the suggestion. The message is self-refuting by construction: it can only name a closest match that came from the live list it never checked for acceptance.

Fix

Recheck the name against the live list alongside the id — 13 lines, one file, no behavior change for identifiers that resolve to nothing.

• Branch: https://github.com/gcp007-ops/nexus/tree/fix/envelope-workspace-name-live-list (on tag 5.16.2)
• Commit: gcp007-ops@3b0e78fb

const byLiveName = workspaces.find(w => w.name.toLowerCase() === workspaceId.toLowerCase());
if (byLiveName) return null;

Coverage

tests/unit/EnvelopeWorkspaceValidation.test.ts, 5 cases, RED verified before the fix — 3 failing, and notably the id case and the legitimate rejection (--workspaceId) already passed, which is what pins the defect to the by-name path rather than to the guard as a whole.

The fifth is a self-contradiction lock rather than another hand-picked case: for every live workspace, assert the error never contains Closest match: "<that same name>". Any future divergence between the list the guard accepts from and the list it suggests from fails there, whichever direction it drifts.

• Suite: 4253 pass / 3 fail — the 3 reproduce identically on clean 5.16.2 (two are toLocaleString under a pt-BR locale, one is LocalCliInstaller).
• tsc --noEmit, eslint ., npm run build clean.

Note on severity

validateWorkspaceId fails open, so this is bounded — but it fails closed here, because the plugin and workspaceService do resolve. The guard works; only the acceptance list is wrong. On a vault with named workspaces this makes every by-name envelope unusable until callers are rewritten to pass UUIDs, which is the opposite of the grounding #311 introduced.

Happy to open a PR if you want it; not opening a cold one.

Measured on macOS 15.6, Nexus 5.16.2 stock (main.js 4,288,180 bytes), vault of 13,432 notes.

[ProfSynapse]

Fixed on main in #318. I'll slot this into the next release.

Thanks for the writeup — the diagnosis was exactly right. I verified it against the code rather than applying the patch directly, and it lands as a single combined lookup instead of a second find, so acceptance and suggestion provably read the same list:

const byIdOrName = workspaces.find(workspace =>
  workspace.id === workspaceId || workspace.name.toLowerCase() === target
);

The knownWorkspaces fast path stays, since it avoids the async lookup on vaults where the snapshot is populated, but it's now commented as accept-only — a miss falls through to the live list rather than rejecting. That's the property that keeps it from drifting back into being a second source of truth.

Two additions beyond your five cases:

• Archived workspace by name. The id branch matches the full list, so the name branch has to as well, or the two forms disagree for archived rows.
• Your self-contradiction lock is the one I'd have missed, and it earned its keep immediately. Mid-fix I dropped the listWorkspaces() line; the ReferenceError went into the enclosing catch and the guard failed open, accepting everything. Three acceptance tests went green for the wrong reason — the lock and the legitimate-rejection case caught it. Good argument for asserting the rejection path on any guard that fails open by design.

Suite is 4257 passing here. Of your three failures I only see LocalCliInstaller; the two toLocaleString ones don't reproduce outside a pt-BR locale, which is worth a separate issue if you're up for filing it — locale-dependent assertions will keep biting.

---

Generated by Claude Code