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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(mcp): contain, bound and uniquely identify project discovery
rahmanef63bf8e810fae28
diff --git a/app/api/skills/route.ts b/app/api/skills/route.tsindex abcd42f5..96e48b70 100644--- a/app/api/skills/route.ts+++ b/app/api/skills/route.ts@@ -1,7 +1,7 @@import { NextRequest, NextResponse } from "next/server";import { requireSession } from "@/lib/auth/require-session";import { IS_DEMO } from "@/lib/demo";-import { catalogSkills, findSkill, readSkillFile, type SkillInfo } from "@/lib/skills/catalog";+import { catalogSkillsDetailed, resolveSkill, readSkillFile, type SkillInfo } from "@/lib/skills/catalog";import { listLearnedRecipes } from "@/lib/skills/memory";import { searchSkillMemory } from "@/lib/skills/search";@@ -27,7 +27,7 @@ export async function GET(req: NextRequest) {.map((s) => ({ kind: "skill", id: s.id, name: s.name, score: 1, description: s.description, source: s.source, trust: s.trust })),});}- const skill = name ? findSkill(demoSkills, name) : null;+ const skill = name ? resolveSkill(demoSkills, name).skill : null;return skill? NextResponse.json({ skill, content: `# ${skill.name}\n\n${skill.description}\n\nDemo mode only lists this skill; it does not run host automation.` }): NextResponse.json({ skills: demoSkills, recipes: [] });@@ -43,16 +43,19 @@ export async function GET(req: NextRequest) {}));}- const skills = await catalogSkills();+ const { skills, scan } = await catalogSkillsDetailed();if (!name) {const recipes = (await listLearnedRecipes()).map((r) => ({id: r.id, intent: r.intent, project: r.project, summary: r.summary, attempts: r.attempts,successes: r.successes, failures: r.failures, fastestDurationMs: r.fastestDurationMs, updatedAt: r.updatedAt,}));- return NextResponse.json({ skills, recipes });+ return NextResponse.json({ skills, recipes, scan });}- const skill = findSkill(skills, name);+ const { skill, ambiguous } = resolveSkill(skills, name);+ // A bare name matching several projects is not a 404 and must not be a guess:+ // returning one project's instructions under another's name is the whole bug.+ if (ambiguous) return NextResponse.json({ error: "ambiguous", candidates: ambiguous }, { status: 409 });if (!skill) return NextResponse.json({ error: "not_found" }, { status: 404 });const content = await readSkillFile(skill.path);if (content === null) return NextResponse.json({ error: "not_found" }, { status: 404 });diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 9f7e3ddd..01aab25d 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -14,6 +14,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Fixed**+- `mcp` contain, bound and uniquely identify project discovery- `mcp` make ChatGPT file imports region agnostic- `mcp` allow ChatGPT India South Central file storage- `mcp` allow ChatGPT New Zealand file storagediff --git a/docs/CONNECTORS-GATEWAY-INTEGRATION.md b/docs/CONNECTORS-GATEWAY-INTEGRATION.mdindex f7a331bd..816aa5ae 100644--- a/docs/CONNECTORS-GATEWAY-INTEGRATION.md+++ b/docs/CONNECTORS-GATEWAY-INTEGRATION.md@@ -4,7 +4,7 @@## Cross-repo contract-MSO currently exposes **26 tool names** (server `1.5.0`, toolset `2026.08.20.3`). The gateway manifest still maps **15** of them through literal `x-upstream` strings:+MSO currently exposes **26 tool names** (server `1.5.1`, toolset `2026.08.20.4`). The gateway manifest still maps **15** of them through literal `x-upstream` strings:```json{ "id": "mso.fs.delete", "x-upstream": "fs_delete" }diff --git a/docs/MCP.md b/docs/MCP.mdindex 8b9682ca..7698989a 100644--- a/docs/MCP.md+++ b/docs/MCP.md@@ -104,8 +104,8 @@ The catalog has a stable server version plus a schema-derived toolset signature.Settings → MCP shows the current version/hash/count and stores a browser-local acknowledgement when the operator marks ChatGPT refreshed. A later signature change becomes an explicit stale-snapshot warning. This does not mutate ChatGPT remotely; it makes the required refresh visible instead of relying on memory.-Current catalog: **26 tools** (14 read, 10 write, 2 exec), server `1.5.0` / toolset-`2026.08.20.3`. `projects_list`, `skills_list` and `skills_read` are the new public+Current catalog: **26 tools** (14 read, 10 write, 2 exec), server `1.5.1` / toolset+`2026.08.20.4`. `projects_list`, `skills_list` and `skills_read` are the new publicnames in this release; `image_generation_status` and `image_generate` were removed(see the migration note below).@@ -117,49 +117,78 @@ names in this release; `image_generation_status` and `image_generate` were removMSO drives **all** of the owner's projects, not the one it happens to live in.-`projects_list` enumerates project directories across every configured project-container — each `OS_FS_READ_ROOTS` entry plus its `projects/` subdirectory, deduped by-realpath, in configured order. It returns name, absolute path, container root, package-name/version and Git branch/head read straight off `.git` with no subprocess. Hidden-directories, symlinks and credential paths are excluded, results are paginated-(default 50, max 200), and the scan is bounded (12 containers, 400 entries per-container, 400 projects). The filesystem root `/` is never treated as a container.+### Which directories count, and why a symlink never does++Each `OS_FS_READ_ROOTS` entry is canonicalized ONCE into an **authorized root**. A+container — a directory that holds projects — is an authorized root, plus its+`projects/` child *only when* that child is a real, non-symlink directory whose+realpath stays inside that same root. A symlinked `projects/` is refused outright, even+when it currently points somewhere legal: accepting it is a TOCTOU bet, because the link+can be repointed between the check and the walk. `/` is never a container — "/" as a read+root means browse-anywhere, not "every top-level system directory is a project".++Every project candidate must then be a real, non-hidden, non-symlink directory whose+realpath is still inside its exact container *and* inside an authorized root, owned by+the uid MSO runs as. Ownership is checked **before** any metadata read, so a directory+another user controls never reaches the `package.json` or `.git` readers at all.++### Bounds, and telling the truth about them++Every scan is bounded: 12 containers, 400 entries read per container, 400 projects,+60 projects scanned for skills, 200 entries per skill root, 300 project skills, and a+4-second wall clock on each of the two walks. Directory iteration uses `opendir` and+stops at the cap rather than materializing the whole listing first. Every metadata read+goes through one byte-capped, `O_NOFOLLOW` reader (`lib/host/bounded-read.ts`): the cap+is checked against `fstat` *before* any bytes move, so an oversized `package.json`,+`SKILL.md` or `packed-refs` costs one stat, not its size.++`projects_list`, `skills_list`, `skills_search` and `workflow_start` all return a+**scan report**. `truncated:false` means "this is all of it"; hitting any cap sets+`truncated:true` and names the reason (`maxRoots`, `maxEntriesPerRoot:<path>`,+`maxProjects`, `maxProjectSkills`, `deadline`), alongside `scannedRoots`, `skippedRoots`+and a count of entries rejected by the containment/ownership checks. **Do not conclude a+project or skill is absent from a truncated scan** — the tool descriptions say so too.++### Ids, so nothing shadows anything++A global skill is addressed by bare name. A project is `<rootId>/<name>` and a project+skill is `<rootId>/<project>/<name>`, where `rootId` is a short sha256 of the canonical+container path. That makes ids **globally unique**: two configured roots may each hold a+`widget` shipping `deploy`, and both stay visible, readable and searchable. The derived+`projects/` container gets its own `rootId` for the same reason, so `~/widget` and+`~/projects/widget` cannot collide either. Within one project, `.mso/skills` outranks the+agent-tool roots; every project root ranks below every global root, so an operator or+official skill can never be displaced.++`skills_read` takes the exact id. A bare name is accepted only when it is unambiguous —+when several projects ship it, the call is **refused** and lists the exact ids rather+than handing back another project's instructions under the name you asked for.+`skills_list`'s `project` filter accepts an exact `projectId`, an absolute path, or a+bare name; a bare name matching several roots keeps them all and reports the candidates+in `ambiguousProjects`.`resolveProjectHint` — behind `workflow_start`'s `project` and `fs_search` — searches-those same containers, deterministically and exact-before-fuzzy: an absolute/`~` path-wins outright, then an exact directory name or known alias probed container by-container, then one bounded scan scoring exact package names above substrings. An exact-name in the second container beats a substring hit in the first.+the same containers, deterministically and exact-before-fuzzy: an absolute/`~` path wins+outright, then an exact directory name or known alias probed container by container,+then one bounded scan scoring exact package names above substrings. The exact-name probe+refuses exactly what enumeration refuses — a symlinked entry (whether or not its target+is legal) and a hidden directory. An explicit `rootHint` runs **every** strategy inside+that root, including package and fuzzy matching, even when the global container list is+already at its cap; a path hint may not leave it.-`skills_list` merges the global roots with the **per-project** roots of every project:+### Project skill trust is earned, never assumed++`skills_list` merges the global roots with the per-project roots of every project:`.mso/skills`, `.claude/skills`, `.hermes/skills`, `.agents/skills`, `.codex/skills`.-Each row carries the exact catalog id, trust, source and its project.--**Ids, so nothing shadows anything.** A global skill is addressed by bare name; a-project skill is `<project>/<name>`. Two projects may both ship `deploy`, and neither-can displace an operator (`~/.mso/skills`) or official (MSO repo) skill of the same-name. Within one project, `.mso/skills` outranks the agent-tool roots. Precedence is-fully deterministic.--**Project trust is earned, never assumed from the path.** A project skill becomes-`local` only when all three hold: the skill directory realpaths back *inside* its-project (a `.claude/skills -> /tmp/attacker` symlink is discovered, not followed); the-directory and its `SKILL.md` are owned by the uid MSO runs as; and `SKILL.md` is a-regular file, not a symlink. Otherwise it is cataloged `untrusted`. The generic HOME-agent roots (`~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, OpenClaw) keep-their existing untrusted behaviour — this promotion is for project roots only.--`skills_read` takes the **exact catalog id** and nothing else — no fuzzy resolution, so-`widget-deploy` will not silently return `widget/widget-deploy`. It returns instructions-for `official`, hash-`verified`, operator-`local` and ownership-verified project skills.-An `untrusted` skill returns metadata plus an explicit refusal: review the file, then-move it into `~/.mso/skills` to promote it. The reader still opens only a realpath'd file-named exactly `SKILL.md`. Content is capped at 24,000 characters; the project scan is-bounded to 60 projects, 100 skills per root and 300 project skills per call.--`workflow_start` and `skills_search` search this unified catalog, and every skill hit-carries its `project` when it has one — so a workflow named against project A still-finds the relevant skill in project B rather than relearning it.+A project skill becomes `local` only when all three hold: the skill directory realpaths+back *inside* its project; the directory and its `SKILL.md` are owned by MSO's uid; and+`SKILL.md` is a regular file, not a symlink. Otherwise it is cataloged `untrusted` —+metadata visible, instructions withheld until the operator reviews it and moves it into+`~/.mso/skills`. The generic HOME agent roots keep their existing untrusted behaviour.++`workflow_start` and `skills_search` search this unified catalog; every skill hit carries+its `project`, and the bootstrap carries a `discovery.complete` flag plus a+`[Discovery] partial scan` trace line when the catalog was truncated.## Semantic skill search and learned workflowsdiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 677fb37c..1464253e 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -8,6 +8,69 @@ Running log of what shipped each phase. Newest at top.> Read those phases as history. **This file is the source of truth for what exists** —> `ARCHITECTURE.md` is no longer maintained and carries a stale-warning banner.+## 2026-08-20 — discovery containment, honest bounds and unique ids (DONE)++A fail-closed review of the discovery release found three things worth blocking on, and+all three came from the same habit: treating "we checked the happy path" as containment.++**A symlinked `projects/` escaped the read jail.** `<root>/projects` was accepted on a+plain `realpath`, so with `OS_FS_READ_ROOTS=/safe` and `/safe/projects -> /outside`, the+enumerator walked `/outside` and project-skill discovery could mark same-uid skills there+`local` — instructions handed to a model from outside the jail entirely. Each configured+root is now canonicalized ONCE into an authorized root; a derived container must be a+REAL non-symlink directory whose realpath stays inside that same root. A symlinked+`projects/` is refused even when its target is currently legal, because accepting it is a+TOCTOU bet. Every project candidate is re-checked too: non-hidden, non-symlink, realpath+still inside its exact container AND an authorized root, and owned by MSO's uid — checked+BEFORE any metadata read, so a directory another user controls never reaches the readers.++**The advertised limits bounded nothing.** `readdir` materialized a whole container+before slicing, global skill roots had no entry budget at all, and `package.json`,+`SKILL.md` and `packed-refs` were read in full and sliced afterwards — so one read-scope+`projects_list` on an attacker-influenced tree was a memory-exhaustion primitive. Both+walks now use `opendir` and stop at the cap, global skill roots got the budget they were+missing, and every metadata read goes through one `O_NOFOLLOW` reader that checks the cap+against `fstat` before any bytes move. Each walk also carries a 4-second wall clock.++**Truncation lied.** `projectRoots()` returned early after 12 roots and each container was+silently sliced to 400 entries, yet only the separate 400-project condition set+`truncated`. A caller could be told the scan was complete while configured containers were+never opened. Every discovery response now carries a scan report: `truncated:false` means+"this is all of it", and any cap sets `truncated:true` with a named reason+(`maxRoots`, `maxEntriesPerRoot:<path>`, `maxProjects`, `maxProjectSkills`, `deadline`)+plus `scannedRoots`, `skippedRoots` and a count of rejected entries. `workflow_start`+carries `discovery.complete` and adds a `[Discovery] partial scan` trace line, and the+tool descriptions tell the client not to conclude something is absent from a truncated+scan.++**Ids were not unique.** A project skill was `<project>/<name>`, deduped by that string,+so two configured roots each holding a `widget` collapsed into one row and a whole+project's skills were unreachable. Identity is now root-qualified: a project is+`<rootId>/<name>` and its skills `<rootId>/<project>/<name>`, where `rootId` is a short+sha256 of the canonical container path. The derived `projects/` container gets its own id+for the same reason, so `~/widget` and `~/projects/widget` no longer collide. `skills_read`+takes the exact id and REFUSES an ambiguous bare name with the candidate list rather than+returning one project's instructions under another's name; `skills_list`'s project filter+accepts an exact projectId, a path or a bare name, reporting `ambiguousProjects` when a+bare name spans roots.++**`rootHint` was half-wired.** Exact names probed the named root, but package and fuzzy+resolution walked the global capped list and filtered — so a readable root absent from+that list could never match by package or fuzzily. All three strategies now run inside the+named root, and a path hint may not leave it. The exact-name probe also refuses a symlink+(target legal or not) and a hidden directory, matching what enumeration excludes.++Regressions cover every one of these: escaping and inside-jail symlinked containers,+symlinked project entries, 13+ configured roots, 401+ entries in one container, duplicate+project basenames across roots, oversized `package.json`/`SKILL.md`, uid mismatch,+`rootHint` package and fuzzy resolution, and truthful truncation. The positive suites are+unchanged and still green: all-agents-all-tools, the exec/read/write scope ladder, image+generation removed everywhere, and `fs_upload_file` with regional ChatGPT import.+`lib/host/project-containers.ts`, `project-roots.ts`, `bounded-read.ts` and+`lib/skills/catalog-scan.ts` split the work so every file is back under 200 lines. The MCP+server/toolset advance to `1.5.1` / `2026.08.20.4`; the catalog stays at **26 tools**+(14 read, 10 write, 2 exec).+## 2026-08-20 — global project/skill discovery, and image generation removed (DONE)**Capabilities are global now, and the docs say so.** Two invisible scopings shipped@@ -74,8 +137,9 @@ provider image tool, and a test greps for that wording.`lib/mcp/tools.ts` shed `apps_power`/`browser_power` into `tools-power.ts` and the newtools live in `tools-discovery.ts`, so every file is back under the 200-line ceiling.`lib/host/project-meta.ts` and `project-roots.ts` split the symlink-refusing readers from-the container enumeration. The MCP server/toolset advance to `1.5.0` / `2026.08.20.3`,-with **26 tools** (14 read, 10 write, 2 exec).+the container enumeration. The MCP server/toolset advanced to `1.5.0` / `2026.08.20.3`,+with **26 tools** (14 read, 10 write, 2 exec). See the entry above for the containment,+bounds and id-uniqueness fixes that followed the review of this release.## 2026-08-20 — provider-backed MCP image generation (SUPERSEDED — removed same day)diff --git a/frontend/slices/assistant/CONTRACT.md b/frontend/slices/assistant/CONTRACT.mdindex 23e732e8..696b6b9d 100644--- a/frontend/slices/assistant/CONTRACT.md+++ b/frontend/slices/assistant/CONTRACT.md@@ -89,11 +89,14 @@ The model reaches trusted skills through the `skills.list`, `skills.search` andevery configured project container (each `OS_FS_READ_ROOTS` entry and its `projects/`child), from `.mso/skills`, `.claude/skills`, `.hermes/skills`, `.agents/skills` and`.codex/skills`. A global skill's id is its bare name; a project skill's is-`<project>/<name>`, so two projects may ship the same name and neither can shadow an-operator or official skill. A project skill earns `local` trust only after realpath-containment inside its project, ownership by MSO's uid, and a regular non-symlink-`SKILL.md`; the generic HOME agent roots stay untrusted. `skills.read` takes the exact-id. See [`docs/MCP.md`](../../../docs/MCP.md) and [`skills/README.md`](../../../skills/README.md).+`<rootId>/<project>/<name>`, where `rootId` is a short hash of the canonical container+path — so two projects with the same basename in *different* configured roots stay+distinct, and neither can shadow an operator or official skill. A project skill earns+`local` trust only after realpath containment inside its project, ownership by MSO's uid,+and a regular non-symlink `SKILL.md`; the generic HOME agent roots stay untrusted.+`skills.read` takes the exact id and refuses an ambiguous bare name rather than guessing.+Every response carries a scan report, so a truncated catalog is never presented as+complete. See [`docs/MCP.md`](../../../docs/MCP.md) and [`skills/README.md`](../../../skills/README.md).## Agent@@ -176,9 +179,11 @@ re-discovers them as bugs.nothing renders it. (`instructions` IS rendered, as the card body in the librarygrid; it just never reaches the model.)2. **`/api/skills` is uncached**, `force-dynamic`, and now walks the global roots PLUS- every project's skill roots on each call. Bounded (60 projects, 100 skills per root,- 300 project skills), but a wide box pays for it every time; a TTL cache is the- obvious next step and was deliberately not added with the discovery change.+ every project's skill roots on each call. Every cap is enforced and reported+ (12 containers, 400 entries each, 60 projects, 200 entries per skill root, 300+ project skills, 4 s per walk), so the worst case is bounded — but a wide box pays it+ every time. A TTL cache is the obvious next step and was deliberately not added with+ the discovery change.3. **The `Skill` → `Playbook` rename has not happened.** The code and the UI stillsay "Skill" for the localStorage type.diff --git a/frontend/slices/assistant/host-tools/catalog-skills.ts b/frontend/slices/assistant/host-tools/catalog-skills.tsindex b377f37a..9de85ba4 100644--- a/frontend/slices/assistant/host-tools/catalog-skills.ts+++ b/frontend/slices/assistant/host-tools/catalog-skills.ts@@ -69,8 +69,13 @@ export const SKILL_TOOLS: HostTool[] = [const name = String(a.name ?? "").trim();if (!name) return "missing skill name";const r = await fetch(`/api/skills?name=${encodeURIComponent(name)}`, { cache: "no-store" });+ const d = (await r.json().catch(() => ({}))) as {+ content?: string; truncated?: boolean; error?: string; candidates?: string[];+ skill?: { trust?: string; source?: string };+ };+ if (d.error === "ambiguous")+ return `"${name}" matches several projects. Call skills.read again with one exact id: ${(d.candidates ?? []).join(", ")}`;if (!r.ok) return `couldn't read skill ${name}`;- const d = (await r.json()) as { content?: string; truncated?: boolean; skill?: { trust?: string; source?: string } };if (d.skill?.trust === "untrusted") {return `refused to load untrusted skill instructions (source=${d.skill.source ?? "unknown"}). Inspect the SKILL.md as a file and explicitly move/copy it into ~/.mso/skills after review if you want MSO to trust it.`;}diff --git a/lib/host/bounded-read.test.ts b/lib/host/bounded-read.test.tsnew file mode 100644index 00000000..b77bcde4--- /dev/null+++ b/lib/host/bounded-read.test.ts@@ -0,0 +1,47 @@+import { afterAll, describe, expect, it } from "vitest";+import { promises as fs } from "fs";+import os from "os";+import path from "path";+import { BOUNDED_READ, readBoundedRegularFile } from "./bounded-read";++// Every metadata read in project/skill discovery goes through this. The point is+// that the CAP is checked before any bytes are read: a 2 GiB package.json in an+// attacker-influenced checkout must cost one fstat, not 2 GiB of heap, and a+// read-scope projects_list must not be a memory-exhaustion primitive.+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-bounded-"));+afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });++describe("readBoundedRegularFile", () => {+ it("reads a regular file within the cap", async () => {+ const file = path.join(dir, "ok.json");+ await fs.writeFile(file, '{"name":"ok"}');+ await expect(readBoundedRegularFile(file, 1024)).resolves.toBe('{"name":"ok"}');+ });++ it("refuses a file larger than the cap WITHOUT reading it", async () => {+ const file = path.join(dir, "huge.json");+ await fs.writeFile(file, "x".repeat(5000));+ await expect(readBoundedRegularFile(file, 1024)).resolves.toBeNull();+ // The boundary itself is inclusive, so a file exactly at the cap still reads.+ await expect(readBoundedRegularFile(file, 5000)).resolves.toHaveLength(5000);+ });++ it("refuses a symlink at the final component — O_NOFOLLOW, not realpath-then-read", async () => {+ const target = path.join(dir, "target.json");+ await fs.writeFile(target, '{"name":"target"}');+ const link = path.join(dir, "link.json");+ await fs.symlink(target, link);+ await expect(readBoundedRegularFile(link, 1024)).resolves.toBeNull();+ });++ it("refuses a directory and a missing path", async () => {+ await expect(readBoundedRegularFile(dir, 1024)).resolves.toBeNull();+ await expect(readBoundedRegularFile(path.join(dir, "nope"), 1024)).resolves.toBeNull();+ });++ it("publishes a cap for every discovery read", () => {+ for (const key of ["packageJson", "skillMd", "gitHead", "gitRef", "packedRefs"] as const) {+ expect(BOUNDED_READ[key], key).toBeGreaterThan(0);+ }+ });+});diff --git a/lib/host/bounded-read.ts b/lib/host/bounded-read.tsnew file mode 100644index 00000000..f3cd7b1e--- /dev/null+++ b/lib/host/bounded-read.ts@@ -0,0 +1,52 @@+// The ONLY way project/skill discovery reads a file off disk.+//+// Discovery walks directories the owner did not necessarily author — a cloned repo,+// a vendored skill pack, a checkout someone else pushed to. Two things must therefore+// be true of every read here, and neither was before:+//+// 1. NO SYMLINK on the final component. `O_NOFOLLOW` fails with ELOOP rather than+// handing back whatever the link points at. Doing the check with lstat-then-read+// is a TOCTOU race; letting the kernel refuse the open is not.+// 2. THE CAP IS CHECKED BEFORE ANY BYTES MOVE. fstat first, refuse on size, then+// allocate. `readFile()`-then-`slice()` has already paid for the whole file, so a+// 2 GiB `package.json` turned a read-scope `projects_list` into a memory-+// exhaustion primitive.+//+// Returns null — never throws and never partially reads. A file that fails any check+// is simply "no metadata", which every caller already handles.+import { constants, promises as fs } from "fs";++/** Per-artifact caps. Generous enough for real files, small enough that the worst+ * case of a full scan is bounded arithmetic rather than "whatever is on disk". */+export const BOUNDED_READ = {+ packageJson: 256 * 1024,+ skillMd: 256 * 1024,+ gitHead: 4 * 1024,+ gitRef: 4 * 1024,+ packedRefs: 1024 * 1024,+} as const;++export async function readBoundedRegularFile(file: string, maxBytes: number): Promise<string | null> {+ let handle: Awaited<ReturnType<typeof fs.open>>;+ try {+ // O_NOFOLLOW: ELOOP if `file` itself is a symlink. Intermediate directories are+ // the caller's problem — they are realpath-contained before we get here.+ handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);+ } catch {+ return null;+ }+ try {+ const stat = await handle.stat();+ if (!stat.isFile()) return null;+ if (stat.size > maxBytes) return null;+ const size = Number(stat.size);+ if (size === 0) return "";+ const buffer = Buffer.allocUnsafe(size);+ const { bytesRead } = await handle.read(buffer, 0, size, 0);+ return buffer.subarray(0, bytesRead).toString("utf8");+ } catch {+ return null;+ } finally {+ await handle.close().catch(() => undefined);+ }+}diff --git a/lib/host/project-containers.ts b/lib/host/project-containers.tsnew file mode 100644index 00000000..8d80f953--- /dev/null+++ b/lib/host/project-containers.ts@@ -0,0 +1,156 @@+// WHICH directories may hold projects — the authorization half of project discovery.+// The walk itself lives in project-roots.ts.+//+// EVERY configured project container, not just ~/projects — and never one byte+// outside them.+//+// MSO used to hard-code `~/projects` as "where projects live". That was invisible+// scoping: an owner who set OS_FS_READ_ROOTS to two or three checkout areas still+// had project resolution, skill discovery and the MCP bootstrap looking at exactly+// one of them, and nothing said so.+//+// A container is a directory that HOLDS projects: every AUTHORIZED read root, plus+// its `projects/` child when that child is a REAL directory whose realpath stays+// inside that same root. A symlinked `projects/` is refused outright — even when it+// currently points somewhere legal — because accepting it is a TOCTOU bet: the link+// can be repointed between the check and the walk. `/` is never a container either:+// "/" as a read root means browse-anywhere, not "every top-level system directory is+// a project".+//+// Everything the scan omits is REPORTED. `truncated:false` means "this is all of it";+// hitting a root, entry, project or time cap sets `truncated:true` with a named+// reason. A silent slice that claims completeness is worse than a refusal.+import { createHash } from "crypto";+import { promises as fs } from "fs";+import path from "path";+import { isCredentialPath, isUnderRoot, readRootList } from "./paths";+import { boundedGitMeta, packageMeta } from "./project-meta";++export const PROJECT_LIMITS = {+ /** Authorized OS_FS_READ_ROOTS entries honoured per call. */+ maxRoots: 12,+ /** Directory entries READ from one container before the walk stops. */+ maxEntriesPerRoot: 400,+ /** Projects enumerated in total, across all containers. */+ maxProjects: 400,+ /** Wall-clock ceiling for one whole enumeration. */+ maxScanMs: 4000,+ defaultPageSize: 50,+ maxPageSize: 200,+} as const;++export type AuthorizedRoot = { id: string; configured: string; path: string };++export type ProjectContainer = {+ /** Short sha256 of the canonical container path. The DERIVED `projects/` child gets+ * its own id on purpose: without it `~/widget` and `~/projects/widget` would share+ * a project id and one would shadow the other. */+ id: string;+ path: string;+ authorizedRootId: string;+ authorizedRoot: string;+ derived: boolean;+};++export type ScanReport = {+ truncated: boolean;+ truncationReasons: string[];+ scannedRoots: string[];+ skippedRoots: Array<{ path: string; reason: string }>;+ /** Entries rejected by containment, hidden-name, symlink or ownership checks. */+ skippedProjects: number;+};++export type ProjectRow = {+ /** Globally unique: `<rootId>/<name>`. */+ id: string;+ name: string;+ path: string;+ /** Id of the container this project lives in. */+ rootId: string;+ root: string;+ authorizedRoot: string;+ packageName?: string;+ packageVersion?: string;+ git?: { branch?: string; head?: string };+};++export const shortId = (real: string) => createHash("sha256").update(real).digest("hex").slice(0, 8);++const currentUid = (): number | undefined => (typeof process.getuid === "function" ? process.getuid() : undefined);++/** Ownership by the uid MSO runs as. Checked BEFORE any metadata read, so a directory+ * another user controls never reaches packageMeta/boundedGitMeta at all. */+export async function ownedByUs(target: string): Promise<boolean> {+ const uid = currentUid();+ if (uid === undefined) return true; // no uid concept (Windows); containment still applies+ const stat = await fs.lstat(target).catch(() => null);+ return !!stat && stat.uid === uid;+}++/**+ * Each configured OS_FS_READ_ROOTS entry, resolved ONCE to its canonical directory.+ * Following a symlinked CONFIGURED root is intended — its realpath simply becomes the+ * authorized real root, and everything else is measured against that.+ */+export async function authorizedRoots(): Promise<AuthorizedRoot[]> {+ const out: AuthorizedRoot[] = [];+ const seen = new Set<string>();+ for (const configured of readRootList()) {+ if (out.length >= PROJECT_LIMITS.maxRoots) break;+ const real = await fs.realpath(configured).catch(() => null);+ if (!real || real === "/" || seen.has(real)) continue;+ if (!(await fs.stat(real).catch(() => null))?.isDirectory()) continue;+ if (isCredentialPath(real)) continue;+ seen.add(real);+ out.push({ id: shortId(real), configured, path: real });+ }+ return out;+}++/** Roots configured but NOT honoured, so the caller can say so rather than imply the+ * configuration was fully covered. */+export async function overflowRoots(): Promise<Array<{ path: string; reason: string }>> {+ const honoured = new Set((await authorizedRoots()).map((r) => r.configured));+ return readRootList().filter((c) => !honoured.has(c)).map((path) => ({ path, reason: "maxRoots-or-unreadable" }));+}++/** `<root>/projects`, only when it is a real, non-symlink directory contained in that+ * same authorized root. */+async function derivedContainerPath(root: AuthorizedRoot): Promise<string | null> {+ const candidate = path.join(root.path, "projects");+ const stat = await fs.lstat(candidate).catch(() => null);+ if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) return null;+ const real = await fs.realpath(candidate).catch(() => null);+ if (!real || !isUnderRoot(real, root.path) || isCredentialPath(real)) return null;+ return real;+}++/** Every container, deterministically: configured root order, each root followed by+ * its derived `projects/` child, deduped by canonical path. */+export async function projectContainers(): Promise<ProjectContainer[]> {+ const out: ProjectContainer[] = [];+ const seen = new Set<string>();+ for (const root of await authorizedRoots()) {+ for (const [candidate, derived] of [[root.path, false], [await derivedContainerPath(root), true]] as const) {+ if (!candidate || seen.has(candidate)) continue;+ seen.add(candidate);+ out.push({ id: shortId(candidate), path: candidate, authorizedRootId: root.id, authorizedRoot: root.path, derived });+ }+ }+ return out;+}++/** Back-compat view: just the container paths. */+export async function projectRoots(): Promise<string[]> {+ return (await projectContainers()).map((c) => c.path);+}++/** A container built from ONE explicitly named directory. Used by `resolveProjectHint`'s+ * `rootHint`: the caller named this root, so every strategy must run inside it even+ * when the global container list is already at its cap. Same id derivation, same+ * containment rules — only the discovery path differs. */+export function containerFor(realDir: string): ProjectContainer {+ return { id: shortId(realDir), path: realDir, authorizedRootId: shortId(realDir), authorizedRoot: realDir, derived: false };+}+diff --git a/lib/host/project-containment.test.ts b/lib/host/project-containment.test.tsnew file mode 100644index 00000000..e73493ee--- /dev/null+++ b/lib/host/project-containment.test.ts@@ -0,0 +1,191 @@+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";+import { promises as fs } from "fs";+import os from "os";+import path from "path";++// The fail-closed half of project discovery: what must NOT be enumerated, and what+// must be reported when the scan does not cover everything. Positive multi-root+// behaviour lives in project-roots.test.ts.+const base = await fs.mkdtemp(path.join(os.tmpdir(), "mso-contain-"));+const previous = process.env.OS_FS_READ_ROOTS;++const {+ authorizedRoots, listProjectDirs, listProjects, projectContainers, projectRoots, PROJECT_LIMITS,+} = await import("./project-roots");++const setRoots = (...roots: string[]) => { process.env.OS_FS_READ_ROOTS = roots.join(":"); };++afterAll(async () => {+ if (previous === undefined) delete process.env.OS_FS_READ_ROOTS;+ else process.env.OS_FS_READ_ROOTS = previous;+ await fs.rm(base, { recursive: true, force: true });+});+beforeEach(() => { vi.restoreAllMocks(); });++describe("a symlinked projects/ container cannot escape the read roots", () => {+ it("refuses <root>/projects when it is a symlink pointing OUTSIDE every authorized root", async () => {+ const safe = path.join(base, "esc-safe");+ const outside = path.join(base, "esc-outside");+ await fs.mkdir(path.join(outside, "loot"), { recursive: true });+ await fs.mkdir(safe, { recursive: true });+ await fs.symlink(outside, path.join(safe, "projects"));+ setRoots(safe);++ const containers = await projectContainers();+ expect(containers.map((c) => c.path)).toEqual([await fs.realpath(safe)]);+ const { dirs } = await listProjectDirs();+ expect(dirs.map((d) => path.basename(d.dir))).not.toContain("loot");+ });++ it("refuses a symlinked projects/ EVEN WHEN its target is inside an authorized root", async () => {+ // A symlink is not a container, full stop. Accepting it because "the target is+ // fine right now" is a TOCTOU bet: the link can be repointed between the check+ // and the walk, and nothing re-validates.+ const safe = path.join(base, "in-safe");+ await fs.mkdir(path.join(safe, "real-projects", "inner"), { recursive: true });+ await fs.symlink(path.join(safe, "real-projects"), path.join(safe, "projects"));+ setRoots(safe);++ const containers = await projectContainers();+ expect(containers.map((c) => c.path)).toEqual([await fs.realpath(safe)]);+ expect(containers.some((c) => c.derived)).toBe(false);+ });++ it("accepts a real projects/ directory as a derived container", async () => {+ const safe = path.join(base, "real-derived");+ await fs.mkdir(path.join(safe, "projects", "inner"), { recursive: true });+ setRoots(safe);++ const containers = await projectContainers();+ expect(containers.map((c) => c.derived)).toEqual([false, true]);+ const { dirs } = await listProjectDirs();+ expect(dirs.map((d) => path.basename(d.dir))).toEqual(["inner"]);+ });+});++describe("project entries are never followed through a symlink", () => {+ it("skips a symlinked project entry whose target is outside the container", async () => {+ const root = path.join(base, "entry-root");+ const outside = path.join(base, "entry-outside");+ await fs.mkdir(outside, { recursive: true });+ await fs.writeFile(path.join(outside, "package.json"), JSON.stringify({ name: "sneaky" }));+ await fs.mkdir(path.join(root, "honest"), { recursive: true });+ await fs.symlink(outside, path.join(root, "linked"));+ setRoots(root);++ const { projects } = await listProjects();+ expect(projects.map((p) => p.name)).toEqual(["honest"]);+ });++ it("skips hidden directories", async () => {+ const root = path.join(base, "hidden-root");+ await fs.mkdir(path.join(root, ".secret"), { recursive: true });+ await fs.mkdir(path.join(root, "shown"), { recursive: true });+ setRoots(root);+ const { projects } = await listProjects();+ expect(projects.map((p) => p.name)).toEqual(["shown"]);+ });++ it("skips a project directory not owned by the uid MSO runs as", async () => {+ const root = path.join(base, "uid-root");+ await fs.mkdir(path.join(root, "theirs"), { recursive: true });+ setRoots(root);+ await expect(listProjects().then((r) => r.projects.map((p) => p.name))).resolves.toEqual(["theirs"]);++ // Same tree, different apparent owner: ownership is checked BEFORE any metadata+ // read, so a directory another user controls never reaches packageMeta.+ const real = process.getuid!();+ vi.spyOn(process, "getuid").mockReturnValue(real + 4242);+ const { projects, scan } = await listProjects();+ expect(projects).toEqual([]);+ expect(scan.skippedProjects).toBeGreaterThan(0);+ });+});++describe("truncation is reported truthfully, never as a silent slice", () => {+ it("reports truncated + a maxRoots reason when more roots are configured than scanned", async () => {+ const many: string[] = [];+ for (let i = 0; i < PROJECT_LIMITS.maxRoots + 1; i += 1) {+ const dir = path.join(base, `many-${String(i).padStart(2, "0")}`);+ await fs.mkdir(dir, { recursive: true });+ many.push(dir);+ }+ setRoots(...many);++ const roots = await authorizedRoots();+ expect(roots.length).toBe(PROJECT_LIMITS.maxRoots);+ const { scan } = await listProjects();+ expect(scan.truncated).toBe(true);+ expect(scan.truncationReasons).toContain("maxRoots");+ expect(scan.skippedRoots.length).toBeGreaterThan(0);+ });++ it("reports truncated + maxEntriesPerRoot when one container has more entries than the cap", async () => {+ const root = path.join(base, "wide-root");+ await fs.mkdir(root, { recursive: true });+ await Promise.all(+ Array.from({ length: PROJECT_LIMITS.maxEntriesPerRoot + 1 }, (_, i) =>+ fs.mkdir(path.join(root, `p${String(i).padStart(4, "0")}`), { recursive: true })),+ );+ setRoots(root);++ const { scan, total } = await listProjects();+ expect(scan.truncated).toBe(true);+ expect(scan.truncationReasons.some((r) => r.startsWith("maxEntriesPerRoot"))).toBe(true);+ expect(total).toBeLessThanOrEqual(PROJECT_LIMITS.maxEntriesPerRoot);+ });++ it("reports truncated=false and no reasons when the whole tree fit", async () => {+ const root = path.join(base, "small-root");+ await fs.mkdir(path.join(root, "one"), { recursive: true });+ setRoots(root);+ const { scan } = await listProjects();+ expect(scan).toMatchObject({ truncated: false, truncationReasons: [] });+ expect(scan.scannedRoots).toHaveLength(1);+ });+});++describe("project ids are globally unique across roots", () => {+ it("keeps two same-named projects in different roots as distinct rows and ids", async () => {+ const a = path.join(base, "dup-a");+ const b = path.join(base, "dup-b");+ await fs.mkdir(path.join(a, "widget"), { recursive: true });+ await fs.mkdir(path.join(b, "widget"), { recursive: true });+ setRoots(a, b);++ const { projects } = await listProjects();+ expect(projects.map((p) => p.name)).toEqual(["widget", "widget"]);+ const ids = projects.map((p) => p.id);+ expect(new Set(ids).size).toBe(2);+ expect(new Set(projects.map((p) => p.rootId)).size).toBe(2);+ for (const p of projects) expect(p.id).toBe(`${p.rootId}/${p.name}`);+ });++ it("gives the derived projects/ container its own root id, so ~/x and ~/projects/x differ", async () => {+ const root = path.join(base, "nested-dup");+ await fs.mkdir(path.join(root, "widget"), { recursive: true });+ await fs.mkdir(path.join(root, "projects", "widget"), { recursive: true });+ setRoots(root);++ const { projects } = await listProjects();+ expect(projects).toHaveLength(2);+ expect(new Set(projects.map((p) => p.id)).size).toBe(2);+ });++ it("uses a stable short hash of the canonical container path", async () => {+ const root = path.join(base, "stable-id");+ await fs.mkdir(path.join(root, "one"), { recursive: true });+ setRoots(root);+ const first = await listProjects();+ const second = await listProjects();+ expect(first.projects[0].id).toBe(second.projects[0].id);+ expect(first.projects[0].rootId).toMatch(/^[a-f0-9]{8}$/);+ });++ it("still exposes plain container paths through projectRoots()", async () => {+ const root = path.join(base, "compat-root");+ await fs.mkdir(path.join(root, "one"), { recursive: true });+ setRoots(root);+ await expect(projectRoots()).resolves.toEqual([await fs.realpath(root)]);+ });+});diff --git a/lib/host/project-hint.test.ts b/lib/host/project-hint.test.tsnew file mode 100644index 00000000..23e99147--- /dev/null+++ b/lib/host/project-hint.test.ts@@ -0,0 +1,96 @@+import { afterAll, describe, expect, it } from "vitest";+import { promises as fs } from "fs";+import os from "os";+import path from "path";++// resolveProjectHint's two remaining sharp edges:+// 1. an explicit rootHint must resolve EVERY strategy inside that root — exact,+// package and fuzzy — even when the root is not in the globally capped container+// list, because the caller named it;+// 2. the exact-name/alias probe must reject a symlink or a hidden entry, or it+// quietly resolves what projects_list promises to exclude.+const base = await fs.mkdtemp(path.join(os.tmpdir(), "mso-hint-"));+const previous = process.env.OS_FS_READ_ROOTS;++const jail = path.join(base, "jail");+const named = path.join(jail, "named-root"); // reachable, but pushed out of the cap below+const outside = path.join(base, "outside");+await fs.mkdir(path.join(named, "orchard"), { recursive: true });+await fs.writeFile(path.join(named, "orchard", "package.json"), JSON.stringify({ name: "@farm/orchard" }));+await fs.mkdir(path.join(named, "greenhouse-annex"), { recursive: true });+await fs.mkdir(path.join(named, ".hidden-proj"), { recursive: true });+await fs.mkdir(outside, { recursive: true });+await fs.mkdir(path.join(outside, "elsewhere"), { recursive: true });+await fs.symlink(path.join(outside, "elsewhere"), path.join(named, "linked-proj"));+// A symlink whose target is INSIDE the jail: this one cannot be refused merely+// because the target escapes, so it proves the entry itself is rejected.+await fs.mkdir(path.join(jail, "inside-target"), { recursive: true });+await fs.symlink(path.join(jail, "inside-target"), path.join(named, "inside-link"));++// Fill the container cap with decoy roots so `named` is NOT in projectContainers().+const decoys: string[] = [];+for (let i = 0; i < 14; i += 1) {+ const d = path.join(jail, `decoy-${String(i).padStart(2, "0")}`);+ await fs.mkdir(d, { recursive: true });+ decoys.push(d);+}+process.env.OS_FS_READ_ROOTS = [...decoys, jail].join(":");++const { projectRoots, resolveProjectHint } = await import("./index");++afterAll(async () => {+ if (previous === undefined) delete process.env.OS_FS_READ_ROOTS;+ else process.env.OS_FS_READ_ROOTS = previous;+ await fs.rm(base, { recursive: true, force: true });+});++describe("an explicit rootHint resolves entirely within that root", () => {+ it("is genuinely outside the globally capped container list", async () => {+ // Guards the premise: if `named` ever lands in the capped list these tests stop+ // proving anything about the rootHint path.+ await expect(projectRoots()).resolves.not.toContain(await fs.realpath(named));+ });++ it("resolves an exact directory name in the named root", async () => {+ await expect(resolveProjectHint("orchard", named)).resolves.toMatchObject({+ name: "orchard", path: path.join(named, "orchard"), matchedBy: "name",+ });+ });++ it("resolves an exact PACKAGE name in the named root", async () => {+ await expect(resolveProjectHint("@farm/orchard", named)).resolves.toMatchObject({+ name: "orchard", matchedBy: "package",+ });+ });++ it("resolves a FUZZY hint in the named root", async () => {+ await expect(resolveProjectHint("greenhouse", named)).resolves.toMatchObject({+ name: "greenhouse-annex", matchedBy: "fuzzy",+ });+ });++ it("never escapes the named root for a hint that only matches elsewhere", async () => {+ await expect(resolveProjectHint("elsewhere", named)).resolves.toBeNull();+ });+});++describe("the exact-name probe rejects what enumeration excludes", () => {+ it("refuses a symlinked project entry even by exact name", async () => {+ await expect(resolveProjectHint("linked-proj", named)).resolves.toBeNull();+ });++ it("refuses a symlinked entry whose target is INSIDE the read jail", async () => {+ // The target being legal is not the question — a symlink is not a child of this+ // container, and enumeration would never have listed it.+ await expect(resolveProjectHint("inside-link", named)).resolves.toBeNull();+ });++ it("refuses a hidden directory even by exact name", async () => {+ await expect(resolveProjectHint(".hidden-proj", named)).resolves.toBeNull();+ });++ it("refuses a name that resolves outside the root it was probed in", async () => {+ // `../outside/elsewhere` must not traverse out of the named root.+ await expect(resolveProjectHint("../outside/elsewhere", named)).resolves.toBeNull();+ });+});diff --git a/lib/host/project-meta.ts b/lib/host/project-meta.tsindex ff462f68..601576d6 100644--- a/lib/host/project-meta.ts+++ b/lib/host/project-meta.ts@@ -8,6 +8,7 @@// one turns a bounded read into an arbitrary one.import { promises as fs } from "fs";import path from "path";+import { BOUNDED_READ, readBoundedRegularFile } from "./bounded-read";import { runCommand } from "./exec";export type PackageMeta = { name?: string; version?: string; scripts: string[] };@@ -21,15 +22,16 @@ export type GitMeta = {error?: string;};-export async function readRegularText(file: string): Promise<string> {- const stat = await fs.lstat(file).catch(() => null);- if (!stat?.isFile() || stat.isSymbolicLink()) return "";- return fs.readFile(file, "utf8").catch(() => "");+/** Every read here is capped BEFORE any bytes move — see bounded-read.ts. An+ * oversized or symlinked artifact yields "" (no metadata), never a partial parse+ * and never an unbounded allocation. */+export async function readRegularText(file: string, maxBytes = BOUNDED_READ.packageJson): Promise<string> {+ return (await readBoundedRegularFile(file, maxBytes)) ?? "";}export async function packageMeta(dir: string): Promise<PackageMeta> {try {- const raw = await readRegularText(path.join(dir, "package.json"));+ const raw = await readRegularText(path.join(dir, "package.json"), BOUNDED_READ.packageJson);if (!raw) return { scripts: [] };const parsed = JSON.parse(raw) as { name?: unknown; version?: unknown; scripts?: unknown };return {@@ -49,16 +51,16 @@ export async function boundedGitMeta(dir: string): Promise<GitMeta> {const gitDir = path.join(dir, ".git");const gitStat = await fs.lstat(gitDir).catch(() => null);if (!gitStat?.isDirectory() || gitStat.isSymbolicLink()) return { available: false, statusChecked: false };- const head = await readRegularText(path.join(gitDir, "HEAD"));+ const head = await readRegularText(path.join(gitDir, "HEAD"), BOUNDED_READ.gitHead);if (!head) return { available: false, statusChecked: false };const candidateRef = head.trim().startsWith("ref: ") ? head.trim().slice(5) : undefined;const ref = candidateRef && /^refs\/(?:heads|remotes)\/[a-z0-9._\/-]+$/i.test(candidateRef) && !candidateRef.includes("..")? candidateRef: undefined;const branch = ref?.replace(/^refs\/heads\//, "");- let sha = ref ? (await readRegularText(path.join(gitDir, ref))).trim() : head.trim();+ let sha = ref ? (await readRegularText(path.join(gitDir, ref), BOUNDED_READ.gitRef)).trim() : head.trim();if (!sha && ref) {- const packed = await readRegularText(path.join(gitDir, "packed-refs"));+ const packed = await readRegularText(path.join(gitDir, "packed-refs"), BOUNDED_READ.packedRefs);sha = packed.split("\n").find((line) => line.endsWith(` ${ref}`))?.split(" ")[0] ?? "";}return { available: true, branch, statusChecked: false, ...(sha ? { head: { sha } } : {}) };diff --git a/lib/host/project-roots.ts b/lib/host/project-roots.tsindex 26d08092..6ce458df 100644--- a/lib/host/project-roots.ts+++ b/lib/host/project-roots.ts@@ -1,129 +1,155 @@-// EVERY configured project container, not just ~/projects.+// The project WALK: bounded enumeration of the containers project-containers.ts+// authorized, plus the truthful report of everything it could not cover.//-// MSO used to hard-code `~/projects` as "where projects live". That was invisible-// scoping: an owner who set OS_FS_READ_ROOTS to two or three checkout areas still-// had project resolution, skill discovery and the MCP bootstrap looking at exactly-// one of them, and nothing said so. A capability that silently covers a subset of-// what the owner configured is worse than one that refuses.-//-// A container is a directory that HOLDS projects. Every read root is one, plus its-// `projects/` subdirectory when it has one (the default `~` + `~/projects` pair is-// this case). The filesystem root is deliberately NOT a container: "/" as a read-// root means browse-anywhere, not "every top-level system directory is a project".+// `truncated:false` means "this is all of it". Hitting a root, entry, project or time+// cap sets `truncated:true` with a named reason, because a silent slice that claims+// completeness is how a model ends up telling the owner a project does not exist.import { promises as fs } from "fs";import path from "path";-import { isCredentialPath, readRootList } from "./paths";+import { isCredentialPath, isUnderRoot } from "./paths";import { boundedGitMeta, packageMeta } from "./project-meta";+import {+ authorizedRoots, ownedByUs, overflowRoots, projectContainers,+ PROJECT_LIMITS, type ProjectContainer, type ProjectRow, type ScanReport,+} from "./project-containers";-export const PROJECT_LIMITS = {- /** Containers scanned per call. */- maxRoots: 12,- /** Directory entries read per container before the listing is truncated. */- maxEntriesPerRoot: 400,- /** Projects enumerated in total, across all containers. */- maxProjects: 400,- defaultPageSize: 50,- maxPageSize: 200,-} as const;--export type ProjectRow = {- name: string;- path: string;- root: string;- packageName?: string;- packageVersion?: string;- git?: { branch?: string; head?: string };-};+export {+ authorizedRoots, containerFor, projectContainers, projectRoots, PROJECT_LIMITS,+} from "./project-containers";+export type { AuthorizedRoot, ProjectContainer, ProjectRow, ScanReport } from "./project-containers";-async function realDir(p: string): Promise<string | null> {- const real = await fs.realpath(p).catch(() => null);- if (!real) return null;- const stat = await fs.stat(real).catch(() => null);- return stat?.isDirectory() ? real : null;-}+type Walk = { dirs: string[]; hitEntryCap: boolean; skipped: number };/**- * Deterministic: configured read-root order, each root followed by its `projects/`- * child, deduped by realpath. Order is the contract — two calls on an unchanged box- * must enumerate identically, or pagination lies.+ * Bounded `opendir` iteration. Names are collected into an array capped at+ * `maxEntriesPerRoot`, so a container with a million entries costs a bounded walk and+ * a bounded array rather than one `readdir` that materializes the lot before slicing.*/-export async function projectRoots(): Promise<string[]> {- const out: string[] = [];- const seen = new Set<string>();- for (const configured of readRootList()) {- for (const candidate of [configured, path.join(configured, "projects")]) {- const real = await realDir(candidate);- if (!real || real === "/" || seen.has(real) || isCredentialPath(real)) continue;- seen.add(real);- out.push(real);- if (out.length >= PROJECT_LIMITS.maxRoots) return out;+async function walkContainer(container: ProjectContainer, containers: Set<string>, authorized: string[], deadlineAt: number): Promise<Walk> {+ const names: string[] = [];+ let hitEntryCap = false;+ let skipped = 0;+ const handle = await fs.opendir(container.path).catch(() => null);+ if (!handle) return { dirs: [], hitEntryCap: false, skipped: 0 };+ try {+ for await (const entry of handle) {+ if (names.length >= PROJECT_LIMITS.maxEntriesPerRoot || Date.now() > deadlineAt) { hitEntryCap = true; break; }+ // isDirectory() is false for a symlink, so a link out of the container is+ // dropped here rather than realpath-checked (and possibly followed) later.+ if (!entry.isDirectory() || entry.name.startsWith(".")) { if (!entry.isDirectory()) skipped += 1; continue; }+ names.push(entry.name);}+ } catch {+ // A directory that vanishes mid-walk yields what we already have.}- return out;-}+ names.sort((a, b) => a.localeCompare(b));-/** A project directory: real, owner-visible, not hidden, not a symlink, not a- * credential path, and not a container in its own right (`~/projects` under `~`). */-async function projectDirsIn(root: string, containers: Set<string>): Promise<string[]> {- const entries = (await fs.readdir(root, { withFileTypes: true }).catch(() => []))- // isDirectory() is false for a symlink, so a link out of the container is- // dropped here rather than realpath-checked later.- .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))- .sort((a, b) => a.name.localeCompare(b.name))- .slice(0, PROJECT_LIMITS.maxEntriesPerRoot);- const out: string[] = [];- for (const entry of entries) {- const full = path.join(root, entry.name);- if (containers.has(full) || isCredentialPath(full)) continue;- out.push(full);+ const dirs: string[] = [];+ for (const name of names) {+ const full = path.join(container.path, name);+ if (containers.has(full) || isCredentialPath(full)) { skipped += 1; continue; }+ const stat = await fs.lstat(full).catch(() => null);+ if (!stat?.isDirectory() || stat.isSymbolicLink()) { skipped += 1; continue; }+ // Defence in depth against a swap between opendir and here: the entry must still+ // canonicalize to itself, inside its exact container AND inside an authorized root.+ const real = await fs.realpath(full).catch(() => null);+ if (real !== full || !isUnderRoot(real, container.path) || !authorized.some((a) => isUnderRoot(real, a))) { skipped += 1; continue; }+ if (!(await ownedByUs(real))) { skipped += 1; continue; }+ dirs.push(full);}- return out;+ return { dirs, hitEntryCap, skipped };}-/** Every project directory across every container, in root-then-name order. */-export async function listProjectDirs(): Promise<{ roots: string[]; dirs: Array<{ root: string; dir: string }>; truncated: boolean }> {- const roots = await projectRoots();- const containers = new Set(roots);- const dirs: Array<{ root: string; dir: string }> = [];- let truncated = false;- for (const root of roots) {- for (const dir of await projectDirsIn(root, containers)) {- if (dirs.length >= PROJECT_LIMITS.maxProjects) { truncated = true; break; }- dirs.push({ root, dir });+export type ProjectDirs = {+ containers: ProjectContainer[];+ dirs: Array<{ container: ProjectContainer; dir: string }>;+ scan: ScanReport;+};++/** The one walk. `listProjectDirs()` is this over every discovered container; an+ * explicit `rootHint` is this over exactly one. */+export async function listProjectDirsIn(containers: ProjectContainer[], extraAuthorized: string[] = []): Promise<ProjectDirs> {+ const deadlineAt = Date.now() + PROJECT_LIMITS.maxScanMs;+ const authorized = [...(await authorizedRoots()).map((r) => r.path), ...extraAuthorized];+ const paths = new Set(containers.map((c) => c.path));+ const dirs: Array<{ container: ProjectContainer; dir: string }> = [];+ const reasons: string[] = [];+ const scannedRoots: string[] = [];+ const skippedRoots = extraAuthorized.length ? [] : await overflowRoots();+ let skippedProjects = 0;++ if (skippedRoots.length) reasons.push("maxRoots");+ for (const container of containers) {+ if (Date.now() > deadlineAt) {+ reasons.push("deadline");+ skippedRoots.push({ path: container.path, reason: "deadline" });+ continue;+ }+ const walk = await walkContainer(container, paths, authorized, deadlineAt);+ scannedRoots.push(container.path);+ skippedProjects += walk.skipped;+ if (walk.hitEntryCap) reasons.push(`maxEntriesPerRoot:${container.path}`);+ for (const dir of walk.dirs) {+ if (dirs.length >= PROJECT_LIMITS.maxProjects) { reasons.push("maxProjects"); break; }+ dirs.push({ container, dir });}- if (truncated) break;+ if (reasons.includes("maxProjects")) break;}- return { roots, dirs, truncated };++ const truncationReasons = [...new Set(reasons)];+ return {+ containers,+ dirs,+ scan: { truncated: truncationReasons.length > 0, truncationReasons, scannedRoots, skippedRoots, skippedProjects },+ };+}++/** Every project directory across every container, in container-then-name order. */+export async function listProjectDirs(): Promise<ProjectDirs> {+ return listProjectDirsIn(await projectContainers());}export type ListProjectsResult = {roots: string[];+ containers: Array<{ id: string; path: string; derived: boolean; authorizedRoot: string }>;total: number;offset: number;limit: number;- truncated: boolean;+ scan: ScanReport;projects: ProjectRow[];};/** Bounded, paginated enumeration. Metadata is read only for the returned PAGE —* `total` counts directories, so a wide box does not pay for 400 package reads. */export async function listProjects(options: { query?: string; limit?: number; offset?: number } = {}): Promise<ListProjectsResult> {- const { roots, dirs, truncated } = await listProjectDirs();+ const { containers, dirs, scan } = await listProjectDirs();const query = options.query?.trim().toLowerCase();const matched = query ? dirs.filter(({ dir }) => path.basename(dir).toLowerCase().includes(query)) : dirs;const limit = Math.min(Math.max(Math.round(options.limit ?? PROJECT_LIMITS.defaultPageSize), 1), PROJECT_LIMITS.maxPageSize);const offset = Math.max(Math.round(options.offset ?? 0), 0);const page = matched.slice(offset, offset + limit);- const projects = await Promise.all(page.map(async ({ root, dir }) => {+ const projects = await Promise.all(page.map(async ({ container, dir }) => {const [pkg, git] = await Promise.all([packageMeta(dir), boundedGitMeta(dir)]);+ const name = path.basename(dir);return {- name: path.basename(dir),+ id: `${container.id}/${name}`,+ name,path: dir,- root,+ rootId: container.id,+ root: container.path,+ authorizedRoot: container.authorizedRoot,...(pkg.name ? { packageName: pkg.name } : {}),...(pkg.version ? { packageVersion: pkg.version } : {}),...(git.available ? { git: { branch: git.branch, head: git.head?.sha?.slice(0, 12) } } : {}),};}));- return { roots, total: matched.length, offset, limit, truncated, projects };+ return {+ roots: containers.map((c) => c.path),+ containers: containers.map(({ id, path: p, derived, authorizedRoot }) => ({ id, path: p, derived, authorizedRoot })),+ total: matched.length,+ offset,+ limit,+ scan,+ projects,+ };}diff --git a/lib/host/projects.ts b/lib/host/projects.tsindex 86a5906d..12f2ec3c 100644--- a/lib/host/projects.ts+++ b/lib/host/projects.ts@@ -2,68 +2,103 @@ import { promises as fs } from "fs";import path from "path";import { normalizeProjectKey, projectAliasesFor, projectAliasTarget } from "./project-aliases";import { boundedGitMeta, fullGitMeta, packageMeta } from "./project-meta";-import { resolveReadable } from "./paths";-import { listProjectDirs, projectRoots } from "./project-roots";+import { isUnderRoot, resolveReadable } from "./paths";+import { containerFor, listProjectDirsIn, projectContainers, type ProjectContainer } from "./project-roots";export type ProjectResolution = {hint: string;+ /** Globally unique `<rootId>/<name>`, matching projects_list. */+ id: string;name: string;path: string;- root?: string;+ rootId: string;+ root: string;packageName?: string;aliases: string[];matchedBy: "path" | "name" | "alias" | "package" | "fuzzy";};-async function resolvedDir(p: string): Promise<string | null> {- const resolved = await resolveReadable(p).catch(() => null);- if (!resolved) return null;- return (await fs.stat(resolved).catch(() => null))?.isDirectory() ? resolved : null;-}--async function resolutionFor(dir: string, hint: string, matchedBy: ProjectResolution["matchedBy"], root?: string): Promise<ProjectResolution> {+async function resolutionFor(container: ProjectContainer, dir: string, hint: string, matchedBy: ProjectResolution["matchedBy"]): Promise<ProjectResolution> {const name = path.basename(dir);const meta = await packageMeta(dir);- return { hint, name, path: dir, ...(root ? { root } : {}), packageName: meta.name, aliases: projectAliasesFor(name), matchedBy };+ return {+ hint, id: `${container.id}/${name}`, name, path: dir, rootId: container.id, root: container.path,+ packageName: meta.name, aliases: projectAliasesFor(name), matchedBy,+ };+}++/**+ * The exact-name / alias probe. It must refuse exactly what `projects_list` refuses,+ * or a hint quietly reaches a hidden directory or walks a symlink that enumeration+ * would never have shown — resolving through `resolveReadable` alone only proves the+ * TARGET is inside a read root, not that the ENTRY is a real child of this container.+ */+async function probeExactChild(container: ProjectContainer, name: string): Promise<string | null> {+ if (!name || name.startsWith(".") || name.includes("/") || name.includes("\\")) return null;+ const full = path.join(container.path, name);+ const stat = await fs.lstat(full).catch(() => null);+ if (!stat?.isDirectory() || stat.isSymbolicLink()) return null;+ const real = await fs.realpath(full).catch(() => null);+ if (real !== full || !isUnderRoot(real, container.path)) return null;+ // The container itself came from an authorized root (or an explicit, readable+ // rootHint), so containment there is the jail check.+ return full;+}++/** The containers a hint may resolve inside. An explicit `rootHint` wins: the caller+ * named that root, so it is used even when the global container list is at its cap —+ * it still has to pass `resolveReadable`, so it is inside the read jail either way. */+async function containersFor(rootHint?: string): Promise<ProjectContainer[]> {+ if (!rootHint) return projectContainers();+ const real = await resolveReadable(rootHint).catch(() => null);+ if (!real || !(await fs.stat(real).catch(() => null))?.isDirectory()) return [];+ return [containerFor(real)];}/*** Resolve a project hint across EVERY configured container, not just `~/projects`.** Deterministic order, exact before fuzzy: an absolute/`~` path wins outright; then- * an exact directory name or known alias, probed container by container in- * configured order; then one bounded scan that scores exact package names above- * substring matches. Scanning first would let a fuzzy hit in the first container- * beat an exact directory in the second, which is the kind of answer nobody can- * reproduce.+ * an exact directory name or known alias, probed container by container in configured+ * order; then one bounded scan that scores exact package names above substring+ * matches. Scanning first would let a fuzzy hit in the first container beat an exact+ * directory in the second, which is the kind of answer nobody can reproduce.*/export async function resolveProjectHint(hint: string, rootHint?: string): Promise<ProjectResolution | null> {const raw = hint.trim();if (!raw) return null;+ const containers = await containersFor(rootHint);+ if (!containers.length) return null;+const pathHint = raw.startsWith("projects/") ? `~/${raw}` : raw;if (/^(?:~\/|\/|\.\.?\/)/.test(pathHint)) {- const resolved = await resolvedDir(pathHint);- if (resolved) return resolutionFor(resolved, raw, "path");+ const resolved = await resolveReadable(pathHint).catch(() => null);+ const isDir = resolved ? (await fs.stat(resolved).catch(() => null))?.isDirectory() === true : false;+ // With an explicit rootHint a path hint may not leave that root — otherwise+ // `../elsewhere` would silently escape the root the caller scoped the search to.+ const owner = isDir ? containers.find((c) => isUnderRoot(resolved!, c.path)) : undefined;+ if (isDir && (!rootHint || owner)) return resolutionFor(owner ?? containerFor(resolved!), resolved!, raw, "path");+ if (rootHint && isDir && !owner) return null;}- const roots = rootHint ? [await resolveReadable(rootHint).catch(() => null)].filter((r): r is string => !!r) : await projectRoots();const query = normalizeProjectKey(raw);const aliasTarget = projectAliasTarget(raw);- // Known aliases and exact directory names are the common path. Resolve them in- // one bounded stat per container instead of scanning and parsing every package.+ // Known aliases and exact directory names are the common path. Resolve them in one+ // bounded lstat per container instead of scanning and parsing every package.const directName = aliasTarget ?? (/^[a-z0-9._-]+$/i.test(raw) ? raw : undefined);if (directName) {- for (const root of roots) {- const candidate = await resolvedDir(path.join(root, directName));- if (candidate) return resolutionFor(candidate, raw, aliasTarget ? "alias" : "name", root);+ for (const container of containers) {+ const candidate = await probeExactChild(container, directName);+ if (candidate) return resolutionFor(container, candidate, raw, aliasTarget ? "alias" : "name");}}- const { dirs } = rootHint- ? { dirs: (await listProjectDirs()).dirs.filter(({ root }) => roots.includes(root)) }- : await listProjectDirs();- const candidates = await Promise.all(dirs.map(async ({ root, dir }) => {+ // Package/fuzzy runs over the SAME containers the exact probe used — including an+ // explicit rootHint that is absent from the globally capped list. Filtering a global+ // walk by root was the bug: a named-but-uncapped root could never match here.+ const { dirs } = await listProjectDirsIn(containers, rootHint ? containers.map((c) => c.path) : []);+ const candidates = await Promise.all(dirs.map(async ({ container, dir }) => {const name = path.basename(dir);const meta = await packageMeta(dir);const nameKey = normalizeProjectKey(name);@@ -75,13 +110,14 @@ export async function resolveProjectHint(hint: string, rootHint?: string): Promielse if (packageKey && packageKey === query) { score = 94; matchedBy = "package"; }else if (nameKey.includes(query) || query.includes(nameKey)) score = 65;else if (packageKey && (packageKey.includes(query) || query.includes(packageKey))) score = 60;- return { name, dir, root, meta, score, matchedBy };+ return { name, dir, container, meta, score, matchedBy };}));// Ties break on name then path, so the same box always answers the same way.const best = candidates.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name) || a.dir.localeCompare(b.dir))[0];if (!best || best.score < 60) return null;return {- hint: raw, name: best.name, path: best.dir, root: best.root, packageName: best.meta.name,+ hint: raw, id: `${best.container.id}/${best.name}`, name: best.name, path: best.dir,+ rootId: best.container.id, root: best.container.path, packageName: best.meta.name,aliases: projectAliasesFor(best.name), matchedBy: best.matchedBy,};}diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.tsindex d7cf767f..7c8954cc 100644--- a/lib/mcp/dispatch.test.ts+++ b/lib/mcp/dispatch.test.ts@@ -44,7 +44,7 @@ describe("protocol", () => {it("publishes server and toolset metadata so action drift is visible", async () => {const r = await dispatch({ id: 1, method: "initialize" }, "exec");const result = r.result as { serverInfo: { version: string }; _meta: { toolset: { toolCount: number; hash: string } } };- expect(result.serverInfo.version).toBe("1.5.0");+ expect(result.serverInfo.version).toBe("1.5.1");expect(result._meta.toolset.toolCount).toBe(TOOLS.length);expect(result._meta.toolset.hash).toMatch(/^[a-f0-9]{16}$/);});diff --git a/lib/mcp/tools-discovery.test.ts b/lib/mcp/tools-discovery.test.tsindex 2d3f7b6d..fee84094 100644--- a/lib/mcp/tools-discovery.test.ts+++ b/lib/mcp/tools-discovery.test.ts@@ -4,42 +4,57 @@ import { promises as fs } from "fs";import os from "os";import path from "path";-// One temp container holding two projects. OS_FS_READ_ROOTS is pointed at it so the-// project half of the catalog is deterministic; the GLOBAL half still comes from the-// real repo (`claude-skills/`), which is exactly what these tools are supposed to-// merge, so assertions below check containment rather than exact equality.-const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "mso-discovery-"));-const widget = path.join(workspace, "widget");-const gadget = path.join(workspace, "gadget");-await fs.mkdir(path.join(widget, ".claude/skills/widget-deploy"), { recursive: true });-await fs.writeFile(- path.join(widget, ".claude/skills/widget-deploy/SKILL.md"),- "---\nname: widget-deploy\ndescription: Ship the widget service.\n---\n\n# Widget deploy\n\nstep one\n",-);-await fs.writeFile(path.join(widget, "package.json"), JSON.stringify({ name: "widget", version: "0.1.0" }));+// TWO configured containers, each holding a project called `widget`. That duplicate is+// the point: it is exactly the case that used to collapse into one row, hiding a whole+// project's skills from every client. OS_FS_READ_ROOTS is pointed at both so the project+// half of the catalog is deterministic; the GLOBAL half still comes from the real repo+// (`claude-skills/`), which is what these tools are supposed to merge, so assertions+// check containment rather than exact equality.+const base = await fs.mkdtemp(path.join(os.tmpdir(), "mso-discovery-"));+const rootA = path.join(base, "root-a");+const rootB = path.join(base, "root-b");+const widgetA = path.join(rootA, "widget");+const widgetB = path.join(rootB, "widget");+const gadget = path.join(rootA, "gadget");++async function skill(dir: string, name: string, description: string, body = "step one\n") {+ const target = path.join(dir, name);+ await fs.mkdir(target, { recursive: true });+ await fs.writeFile(path.join(target, "SKILL.md"), `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n\n${body}`);+}++await skill(path.join(widgetA, ".claude/skills"), "widget-deploy", "Ship the widget service from root A.");+await fs.writeFile(path.join(widgetA, "package.json"), JSON.stringify({ name: "widget", version: "0.1.0" }));+await skill(path.join(widgetB, ".claude/skills"), "widget-deploy", "Ship the widget service from root B.");// A project skill whose SKILL.md is a symlink: discoverable, but never trusted.await fs.mkdir(path.join(gadget, ".codex/skills/gadget-wild"), { recursive: true });await fs.writeFile(path.join(gadget, "SKILL.md"), "---\nname: gadget-wild\ndescription: Unverified.\n---\n\n# wild\n");await fs.symlink(path.join(gadget, "SKILL.md"), path.join(gadget, ".codex/skills/gadget-wild/SKILL.md"));const previous = process.env.OS_FS_READ_ROOTS;-process.env.OS_FS_READ_ROOTS = workspace;+process.env.OS_FS_READ_ROOTS = `${rootA}:${rootB}`;const { DISCOVERY_TOOLS } = await import("./tools-discovery");+const { projectRefFor } = await import("@/lib/skills/project-skills");++/** Ids are COMPUTED the way the catalog computes them — never typed by hand, because+ * the whole fix is that they depend on which configured root the project came from. */+const projectId = async (dir: string) => projectRefFor(dir, await fs.realpath(path.dirname(dir))).id;+const skillId = async (dir: string, name: string) => `${await projectId(dir)}/${name}`;const tool = (name: string) => {const found = DISCOVERY_TOOLS.find((t) => t.name === name);if (!found) throw new Error(`missing ${name}`);return found;};-const run = (name: string, args: Record<string, unknown> = {}) =>- tool(name).run(args, { scope: "read" as const });+const run = (name: string, args: Record<string, unknown> = {}) => tool(name).run(args, { scope: "read" as const });-type SkillRow = { id: string; trust: string; instructionsReadable: boolean; project?: { name: string } };+type SkillRow = { id: string; trust: string; instructionsReadable: boolean; project?: { id: string; name: string } };+type Scan = { truncated: boolean; truncationReasons: string[] };afterAll(async () => {if (previous === undefined) delete process.env.OS_FS_READ_ROOTS;else process.env.OS_FS_READ_ROOTS = previous;- await fs.rm(workspace, { recursive: true, force: true });+ await fs.rm(base, { recursive: true, force: true });});describe("projects_list", () => {@@ -48,41 +63,75 @@ describe("projects_list", () => {expect(tool("projects_list").annotations?.readOnlyHint).toBe(true);});- it("enumerates every project in the configured container with bounded metadata", async () => {- const result = await run("projects_list") as { total: number; projects: Array<{ name: string; packageName?: string }> };- expect(result.projects.map((p) => p.name)).toEqual(["gadget", "widget"]);- expect(result.projects.find((p) => p.name === "widget")?.packageName).toBe("widget");- expect(result.total).toBe(2);+ it("enumerates every project across BOTH containers, keeping same-named ones distinct", async () => {+ const result = await run("projects_list") as {+ total: number; scan: Scan; projects: Array<{ id: string; name: string; rootId: string; packageName?: string }>;+ };+ expect(result.projects.map((p) => p.name)).toEqual(["gadget", "widget", "widget"]);+ expect(new Set(result.projects.map((p) => p.id)).size).toBe(3);+ expect(result.total).toBe(3);+ expect(result.projects.find((p) => p.packageName === "widget")).toBeDefined();+ });++ it("reports a truthful scan report on a complete enumeration", async () => {+ const { scan } = await run("projects_list") as { scan: Scan & { scannedRoots: string[] } };+ expect(scan).toMatchObject({ truncated: false, truncationReasons: [] });+ expect(scan.scannedRoots.length).toBeGreaterThanOrEqual(2);});it("filters and paginates", async () => {const result = await run("projects_list", { query: "wid", limit: 1 }) as { total: number; limit: number; projects: Array<{ name: string }> };- expect(result).toMatchObject({ total: 1, limit: 1 });+ expect(result).toMatchObject({ total: 2, limit: 1 });expect(result.projects.map((p) => p.name)).toEqual(["widget"]);});});describe("skills_list spans global and project roots", () => {it("returns official repo skills AND per-project skills in one catalog", async () => {- const { skills } = await run("skills_list", { limit: 200 }) as { skills: SkillRow[] };+ const { skills, scan } = await run("skills_list", { limit: 200 }) as { skills: SkillRow[]; scan: Scan };const ids = skills.map((s) => s.id);+ const deployA = await skillId(widgetA, "widget-deploy");expect(ids).toContain("mso"); // official, from this repo's claude-skills/- expect(ids).toContain("widget/widget-deploy");- expect(skills.find((s) => s.id === "widget/widget-deploy")).toMatchObject({+ expect(ids).toContain(deployA);+ expect(skills.find((s) => s.id === deployA)).toMatchObject({trust: "local", instructionsReadable: true, project: { name: "widget" },});+ expect(scan).toHaveProperty("truncated");+ });++ it("keeps BOTH same-named projects' skills visible under distinct ids", async () => {+ const { skills } = await run("skills_list", { limit: 200 }) as { skills: SkillRow[] };+ const a = await skillId(widgetA, "widget-deploy");+ const b = await skillId(widgetB, "widget-deploy");+ expect(a).not.toBe(b);+ expect(skills.map((s) => s.id)).toEqual(expect.arrayContaining([a, b]));});it("marks a project skill with a symlinked SKILL.md untrusted and unreadable", async () => {const { skills } = await run("skills_list", { limit: 200 }) as { skills: SkillRow[] };- expect(skills.find((s) => s.id === "gadget/gadget-wild")).toMatchObject({+ const wild = await skillId(gadget, "gadget-wild");+ expect(skills.find((s) => s.id === wild)).toMatchObject({trust: "untrusted", instructionsReadable: false,});});- it("filters by project and by trust", async () => {- const byProject = await run("skills_list", { project: "widget" }) as { skills: SkillRow[] };- expect(byProject.skills.map((s) => s.id)).toEqual(["widget/widget-deploy"]);+ it("filters by an exact projectId", async () => {+ const only = await run("skills_list", { project: await projectId(widgetA) }) as { skills: SkillRow[]; ambiguousProjects?: unknown };+ expect(only.skills.map((s) => s.id)).toEqual([await skillId(widgetA, "widget-deploy")]);+ expect(only.ambiguousProjects).toBeUndefined();+ });++ it("keeps a bare ambiguous project name inclusive, and says which ids it could mean", async () => {+ const both = await run("skills_list", { project: "widget" }) as {+ skills: SkillRow[]; ambiguousProjects?: Array<{ projectId: string; name: string }>;+ };+ expect(both.skills).toHaveLength(2);+ expect(both.ambiguousProjects).toHaveLength(2);+ expect(both.ambiguousProjects!.map((p) => p.projectId).sort())+ .toEqual([await projectId(widgetA), await projectId(widgetB)].sort());+ });++ it("filters by trust", async () => {const official = await run("skills_list", { trust: "official", limit: 200 }) as { skills: SkillRow[] };expect(official.skills.every((s) => s.trust === "official")).toBe(true);expect(official.skills.some((s) => s.project)).toBe(false);@@ -91,10 +140,12 @@ describe("skills_list spans global and project roots", () => {describe("skills_read reads the exact catalog id only", () => {it("returns instructions for a trusted project skill", async () => {- const result = await run("skills_read", { name: "widget/widget-deploy" }) as { content: string; project: { name: string }; trust: string };+ const result = await run("skills_read", { name: await skillId(widgetA, "widget-deploy") }) as+ { content: string; project: { name: string }; trust: string };expect(result.trust).toBe("local");expect(result.project.name).toBe("widget");- expect(result.content).toContain("# Widget deploy");+ expect(result.content).toContain("# widget-deploy");+ expect(result.content).toContain("root A");});it("returns instructions for an official global skill", async () => {@@ -104,16 +155,25 @@ describe("skills_read reads the exact catalog id only", () => {});it("withholds instructions for an untrusted skill but still reports metadata", async () => {- const result = await run("skills_read", { name: "gadget/gadget-wild" }) as {- instructionsWithheld: boolean; reason: string; content?: string; trust: string;- };+ const result = await run("skills_read", { name: await skillId(gadget, "gadget-wild") }) as+ { instructionsWithheld: boolean; reason: string; content?: string; trust: string };expect(result).toMatchObject({ instructionsWithheld: true, trust: "untrusted" });expect(result.content).toBeUndefined();expect(result.reason).toContain("~/.mso/skills");});- it("refuses the bare name of a project skill — the namespaced id is the address", async () => {- await expect(run("skills_read", { name: "widget-deploy" })).rejects.toThrow(/unknown skill id/);+ it("REFUSES an ambiguous bare name and lists the exact ids", async () => {+ // Two projects called `widget`, each shipping `widget-deploy`. Guessing here would+ // hand the model another project's instructions under the name it asked for.+ await expect(run("skills_read", { name: "widget-deploy" })).rejects.toThrow(/ambiguous across projects/);+ await expect(run("skills_read", { name: "widget/widget-deploy" })).rejects.toThrow(/ambiguous across projects/);+ await expect(run("skills_read", { name: "widget-deploy" })).rejects.toThrow(await projectId(widgetA));+ });++ it("resolves an UNambiguous bare project-skill name", async () => {+ await expect(run("skills_read", { name: "gadget-wild" })).resolves.toMatchObject({+ id: await skillId(gadget, "gadget-wild"),+ });});it("refuses an unknown id rather than guessing", async () => {diff --git a/lib/mcp/tools-discovery.ts b/lib/mcp/tools-discovery.tsindex 35e06d6f..668f9918 100644--- a/lib/mcp/tools-discovery.ts+++ b/lib/mcp/tools-discovery.ts@@ -1,5 +1,5 @@import { listProjects, PROJECT_LIMITS } from "@/lib/host";-import { catalogSkills, findSkill, readSkillFile, skillIsExecutableByDefault } from "@/lib/skills/catalog";+import { catalogSkillsDetailed, resolveSkill, readSkillFile, skillIsExecutableByDefault, SKILL_SCAN_LIMITS } from "@/lib/skills/catalog";import { type McpTool, str, opt, S, READ_ONLY } from "./tool-kit";// GLOBAL discovery: every project container the owner configured, and every skill@@ -8,8 +8,11 @@ import { type McpTool, str, opt, S, READ_ONLY } from "./tool-kit";// multi-project box had one project and no project skills. All three tools are// `read` — enumerating what exists changes nothing, and a read token is exactly the// grant an agent should need to plan its work.+//+// Every one of them returns a `scan` report. A truncated enumeration that looks+// complete is the failure mode worth engineering against: a model that believes it+// has seen every project will confidently tell the owner a project does not exist.-const SKILL_CONTENT_LIMIT = 24_000;const SKILL_PAGE_MAX = 200;const page = (a: Record<string, unknown>, max: number, fallback: number) => ({@@ -22,16 +25,17 @@ export const DISCOVERY_TOOLS: McpTool[] = [name: "projects_list",description:"Enumerate the owner's projects across EVERY configured project container (each OS_FS_READ_ROOTS entry and its projects/ subdirectory), not just ~/projects. " +- "Returns name, absolute path, its container root, package name/version and bounded Git branch/head read straight off .git with no shell. " +- "USE THIS FIRST when the user names a project you have not located — it is one call, needs no shell scope, and is the input to workflow_start's project hint. " +- "Hidden directories, symlinks and credential paths are excluded; results are paginated.",+ "Returns a globally unique id (<rootId>/<name>, so two roots may hold a project of the same name), absolute path, its container root, package name/version and bounded Git branch/head read straight off .git with no shell. " ++ "USE THIS FIRST when the user names a project you have not located — it is one call, needs no shell scope, and its id or path is the input to workflow_start. " ++ "Hidden directories, symlinks, credential paths and directories not owned by the MSO user are excluded. " ++ "ALWAYS check `scan.truncated`: when true the listing is incomplete and `scan.truncationReasons` says which cap was hit — do not report that a project is absent from a truncated scan.",scope: "read",annotations: READ_ONLY,limit: { key: "projects.list", max: 30, windowMs: 60_000 },inputSchema: S({query: { type: "string", description: "Optional case-insensitive substring matched against the directory name." },limit: { type: "number", minimum: 1, maximum: PROJECT_LIMITS.maxPageSize, description: `Page size. Default ${PROJECT_LIMITS.defaultPageSize}.` },- offset: { type: "number", minimum: 0, description: "Page offset into the deterministic root-then-name ordering. Default 0." },+ offset: { type: "number", minimum: 0, description: "Page offset into the deterministic container-then-name ordering. Default 0." },}),run: (a) => listProjects({ query: opt(a, "query"), ...page(a, PROJECT_LIMITS.maxPageSize, PROJECT_LIMITS.defaultPageSize) }),},@@ -40,13 +44,14 @@ export const DISCOVERY_TOOLS: McpTool[] = [description:"List every SKILL.md MSO can see: the global roots (operator ~/.mso/skills, official MSO skills, hash-verified bundles, generic agent registries) AND the per-project roots " +"(.mso/skills, .claude/skills, .hermes/skills, .agents/skills, .codex/skills) of every project across every configured container. " +- "Each row carries the exact catalog id to pass to skills_read — a project skill is addressed as <project>/<name>, so two projects may ship the same skill name — plus trust, source and its project. " +- "Trust is earned, not assumed: a project skill is only `local` after realpath containment, owner uid and a regular non-symlink SKILL.md.",+ "Each row carries the exact catalog id to pass to skills_read — a project skill is <rootId>/<project>/<name>, so two projects may ship the same skill name in the same or different roots — plus trust, source and its project. " ++ "Trust is earned, not assumed: a project skill is only `local` after realpath containment, owner uid and a regular non-symlink SKILL.md. " ++ "Check `scan.truncated` before concluding a skill does not exist.",scope: "read",annotations: READ_ONLY,limit: { key: "skills.list", max: 30, windowMs: 60_000 },inputSchema: S({- project: { type: "string", description: "Optional project name or absolute path; keeps only skills belonging to that project." },+ project: { type: "string", description: "Optional project filter: an exact projectId (<rootId>/<name>), an absolute project path, or a bare name. A bare name matching projects in several roots keeps them all and reports them in ambiguousProjects." },trust: { type: "string", enum: ["official", "verified", "local", "untrusted"], description: "Optional exact trust filter." },query: { type: "string", description: "Optional case-insensitive substring matched against id and description." },limit: { type: "number", minimum: 1, maximum: SKILL_PAGE_MAX, description: "Page size. Default 100." },@@ -56,18 +61,27 @@ export const DISCOVERY_TOOLS: McpTool[] = [const project = opt(a, "project");const trust = opt(a, "trust");const query = opt(a, "query")?.toLowerCase();- const all = await catalogSkills();+ const { skills: all, scan } = await catalogSkillsDetailed();const matched = all.filter((skill) => {- if (project && skill.project?.name !== project && skill.project?.path !== project) return false;+ if (project && !(skill.project?.id === project || skill.project?.path === project || skill.project?.name === project)) return false;if (trust && skill.trust !== trust) return false;if (query && !`${skill.id} ${skill.description}`.toLowerCase().includes(query)) return false;return true;});+ // A bare project name that hits more than one root is AMBIGUOUS, not wrong: the+ // rows all stay, and the client is told which exact ids it could have meant.+ const projectIds = [...new Set(matched.map((s) => s.project?.id).filter((id): id is string => !!id))];+ const ambiguousProjects = project && projectIds.length > 1+ ? matched.filter((s) => s.project).map((s) => ({ projectId: s.project!.id, name: s.project!.name, path: s.project!.path, rootId: s.project!.rootId }))+ .filter((row, i, rows) => rows.findIndex((r) => r.projectId === row.projectId) === i)+ : undefined;const { limit, offset } = page(a, SKILL_PAGE_MAX, 100);return {total: matched.length,offset,limit,+ scan,+ ...(ambiguousProjects ? { ambiguousProjects } : {}),skills: matched.slice(offset, offset + limit).map((skill) => ({id: skill.id,name: skill.name,@@ -84,20 +98,27 @@ export const DISCOVERY_TOOLS: McpTool[] = [{name: "skills_read",description:- "Read one skill's SKILL.md by its EXACT catalog id from skills_list or skills_search (a project skill is <project>/<name>). " ++ "Read one skill's SKILL.md by its EXACT catalog id from skills_list or skills_search (a project skill is <rootId>/<project>/<name>). " ++ "A bare name is accepted only when it is unambiguous; when several projects ship that name the call is refused and lists the exact ids, rather than guessing which project's instructions you meant. " +"Instructions are returned for official, hash-verified, operator-local and ownership-verified project skills. " +"An untrusted skill returns metadata only — inspect it as a file and move it into ~/.mso/skills after review to promote it. " +- "The reader opens only a realpath'd file named SKILL.md, so a link pointing elsewhere is refused rather than followed.",+ "The reader opens only a realpath'd file named SKILL.md, refuses a symlink at that name, and skips anything over the size cap.",scope: "read",annotations: READ_ONLY,limit: { key: "skills.read", max: 60, windowMs: 60_000 },inputSchema: S({- name: { type: "string", description: "Exact catalog id from skills_list. Fuzzy names are not resolved here." },+ name: { type: "string", description: "Exact catalog id from skills_list, or an unambiguous bare name." },}, ["name"]),run: async (a) => {const id = str(a, "name");- const skill = findSkill(await catalogSkills(), id);- if (!skill) throw new Error(`unknown skill id "${id}" — call skills_list for the exact ids`);+ const { skills, scan } = await catalogSkillsDetailed();+ const { skill, ambiguous } = resolveSkill(skills, id);+ if (ambiguous)+ throw new Error(`"${id}" is ambiguous across projects — call skills_read with one exact id: ${ambiguous.join(", ")}`);+ if (!skill) {+ const hint = scan.truncated ? " (the catalog scan was truncated: " + scan.truncationReasons.join(", ") + ")" : "";+ throw new Error(`unknown skill id "${id}" — call skills_list for the exact ids${hint}`);+ }const meta = {id: skill.id, name: skill.name, description: skill.description, source: skill.source, trust: skill.trust,...(skill.project ? { project: skill.project } : {}),@@ -110,8 +131,9 @@ export const DISCOVERY_TOOLS: McpTool[] = [};}const content = await readSkillFile(skill.path);- if (content === null) throw new Error(`skill "${id}" no longer has a readable SKILL.md`);- return { ...meta, content: content.slice(0, SKILL_CONTENT_LIMIT), truncated: content.length > SKILL_CONTENT_LIMIT };+ if (content === null)+ throw new Error(`skill "${skill.id}" has no readable SKILL.md (missing, a symlink, or over the ${SKILL_SCAN_LIMITS.maxSkillBytes}-byte cap)`);+ return { ...meta, content, truncated: false };},},];diff --git a/lib/mcp/tools-learning.test.ts b/lib/mcp/tools-learning.test.tsindex 1d6fcb5f..0a6fa305 100644--- a/lib/mcp/tools-learning.test.ts+++ b/lib/mcp/tools-learning.test.ts@@ -30,8 +30,13 @@ process.env.OS_FS_READ_ROOTS = dir;process.env.OS_FS_WRITE_ROOTS = dir;process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");const { resetSkillMemoryCache } = await import("@/lib/skills/memory");+const { projectRefFor } = await import("@/lib/skills/project-skills");const { LEARNING_TOOLS } = await import("./tools-learning");+/** The root-qualified id the catalog assigns, computed the same way it does. */+const siblingSkillId = async () =>+ `${projectRefFor(sibling, await fs.realpath(dir)).id}/orchard-harvest`;+describe("workflow_start bootstrap", () => {beforeEach(async () => {await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });@@ -96,12 +101,24 @@ describe("workflow_start bootstrap", () => {};expect(result.search.hits).toEqual(expect.arrayContaining([expect.objectContaining({- kind: "skill", id: "orchard/orchard-harvest", name: "orchard-harvest",- trust: "local", project: { name: "orchard", path: sibling },+ kind: "skill", id: await siblingSkillId(), name: "orchard-harvest",+ trust: "local", project: expect.objectContaining({ name: "orchard", path: sibling }),}),]));});+ it("tells the client when the discovery scan was incomplete", async () => {+ const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;+ const result = await start.run({ intent: "check discovery completeness", project }, {+ actor: "mcp:discovery", scope: "write" as const,+ }) as { bootstrap: { discovery: { complete: boolean; catalog: { truncated: boolean; truncationReasons: string[] } }; trace: string[] } };+ // This fixture fits well inside every cap, so the honest answer is "complete" —+ // and the trace carries no partial-scan warning.+ expect(result.bootstrap.discovery.complete).toBe(true);+ expect(result.bootstrap.discovery.catalog.truncated).toBe(false);+ expect(result.bootstrap.trace.some((line) => line.startsWith("[Discovery]"))).toBe(false);+ });+it("supports parallel conversations and exposes explicit cancel/finish ids", async () => {const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;const cancel = LEARNING_TOOLS.find((tool) => tool.name === "workflow_cancel")!;diff --git a/lib/mcp/tools-learning.ts b/lib/mcp/tools-learning.tsindex d8f6d550..2c6fc3c0 100644--- a/lib/mcp/tools-learning.ts+++ b/lib/mcp/tools-learning.ts@@ -23,7 +23,7 @@ export const LEARNING_TOOLS: McpTool[] = [audit: { action: "workflow.start" as const, targetArg: "project" },inputSchema: S({intent: { type: "string", description: "The user's task in one complete sentence." },- project: { type: "string", description: "Optional project/workspace or alias, e.g. os-vps, mso, projects/mso." },+ project: { type: "string", description: "Optional project id from projects_list, absolute path, name or alias (e.g. os-vps, mso, projects/mso)." },constraints: { type: "string", description: "Optional important constraints, such as no downtime or WebP only." },}, ["intent"]),run: async (a, context) => {@@ -44,6 +44,13 @@ export const LEARNING_TOOLS: McpTool[] = [? await inspectProject(project, { includeGitStatus: context.scope === "exec" }).catch(() => undefined): undefined;const toolset = toolsetInfo(tools, context.scope);+ // Discovery incompleteness travels WITH the bootstrap. A model told "here is the+ // project and the trusted skills" will not re-check whether the scan covered the+ // whole box; if it did not, it has to be told in the same breath.+ const discovery = {+ catalog: search.catalog,+ complete: !search.catalog.truncated,+ };const started = await startWorkflow({actor: context.actor,intent,@@ -60,9 +67,11 @@ export const LEARNING_TOOLS: McpTool[] = [toolset,project: project ?? (projectHint ? { hint: projectHint, matchedBy: "unresolved" } : undefined),repository,+ discovery,trace: [`[MSO] connected · ${context.scope} scope · ${toolset.toolCount} tools · ${toolset.version}/${toolset.hash}`,project ? `[Project] ${project.hint} → ${project.path} (${project.matchedBy})` : `[Project] ${projectHint ?? "not specified"}`,+ ...(discovery.complete ? [] : [`[Discovery] partial scan — ${search.catalog.truncationReasons.join(", ")}; do not conclude something is absent`]),"[Plan] inspect → change → test/build when needed → verify → workflow_finish",],policy: {diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.tsindex 46b699c3..f6fc3492 100644--- a/lib/mcp/toolset.ts+++ b/lib/mcp/toolset.ts@@ -2,9 +2,9 @@ import { createHash } from "crypto";import type { Scope } from "./scope";import type { McpTool } from "./tool-kit";-export const MCP_SERVER_VERSION = "1.5.0";-export const MCP_TOOLSET_VERSION = "2026.08.20.3";-export const MCP_TOOLSET_CHANGED_AT = "2026-08-20T12:00:00Z";+export const MCP_SERVER_VERSION = "1.5.1";+export const MCP_TOOLSET_VERSION = "2026.08.20.4";+export const MCP_TOOLSET_CHANGED_AT = "2026-08-20T15:30:00Z";export type McpToolsetInfo = {serverVersion: string;diff --git a/lib/skills/catalog-bounds.test.ts b/lib/skills/catalog-bounds.test.tsnew file mode 100644index 00000000..b44b822b--- /dev/null+++ b/lib/skills/catalog-bounds.test.ts@@ -0,0 +1,151 @@+import { afterEach, describe, expect, it } from "vitest";+import { mkdir, mkdtemp, rm, symlink, writeFile } from "fs/promises";+import os from "os";+import path from "path";+import { catalogSkills, catalogSkillsDetailed, resolveSkill } from "./catalog";+import { SKILL_SCAN_LIMITS } from "./catalog-types";+import { projectRefFor } from "./project-skills";++const temps: string[] = [];+async function temp() {+ const dir = await mkdtemp(path.join(os.tmpdir(), "mso-catalog-bounds-"));+ temps.push(dir);+ return dir;+}+afterEach(async () => { await Promise.all(temps.splice(0).map((d) => rm(d, { recursive: true, force: true }))); });++async function skill(root: string, name: string, description: string, body = "") {+ const dir = path.join(root, name);+ await mkdir(dir, { recursive: true });+ await writeFile(path.join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n${body}`);+ return dir;+}++/** Project refs the way the catalog builds them, so ids in tests are not hand-rolled. */+const refs = (...dirs: string[]) => dirs.map((dir) => projectRefFor(dir, path.dirname(dir)));++describe("project skill ids are globally unique across roots", () => {+ it("keeps same-named projects in DIFFERENT roots both visible and readable", async () => {+ const app = await temp();+ const home = await temp();+ const rootA = await temp();+ const rootB = await temp();+ const a = path.join(rootA, "widget");+ const b = path.join(rootB, "widget");+ await skill(path.join(a, ".claude/skills"), "deploy", "root A deploy");+ await skill(path.join(b, ".claude/skills"), "deploy", "root B deploy");++ const rows = await catalogSkills({ appDir: app, homeDir: home, projects: refs(a, b) });+ expect(rows).toHaveLength(2);+ expect(new Set(rows.map((r) => r.id)).size).toBe(2);+ expect(rows.map((r) => r.description).sort()).toEqual(["root A deploy", "root B deploy"]);+ // Both are addressable by their exact ids.+ for (const row of rows) expect(resolveSkill(rows, row.id).skill?.description).toBe(row.description);+ });++ it("namespaces a project skill as <rootId>/<project>/<skill>", async () => {+ const rootA = await temp();+ const a = path.join(rootA, "widget");+ await skill(path.join(a, ".claude/skills"), "deploy", "d");+ const [row] = await catalogSkills({ appDir: await temp(), homeDir: await temp(), projects: refs(a) });+ expect(row.project).toBeDefined();+ expect(row.id).toBe(`${row.project!.rootId}/${row.project!.name}/${row.name}`);+ expect(row.project!.rootId).toMatch(/^[a-f0-9]{8}$/);+ expect(row.project!.id).toBe(`${row.project!.rootId}/${row.project!.name}`);+ });++ it("refuses an ambiguous bare name instead of silently picking one", async () => {+ const rootA = await temp();+ const rootB = await temp();+ const a = path.join(rootA, "widget");+ const b = path.join(rootB, "widget");+ await skill(path.join(a, ".claude/skills"), "deploy", "A");+ await skill(path.join(b, ".claude/skills"), "deploy", "B");+ const rows = await catalogSkills({ appDir: await temp(), homeDir: await temp(), projects: refs(a, b) });++ const bare = resolveSkill(rows, "deploy");+ expect(bare.skill).toBeUndefined();+ expect(bare.ambiguous).toHaveLength(2);+ // `widget/deploy` is ALSO ambiguous — same project basename in two roots.+ expect(resolveSkill(rows, "widget/deploy").ambiguous).toHaveLength(2);+ });++ it("still resolves an unambiguous bare project-skill name for convenience", async () => {+ const rootA = await temp();+ const a = path.join(rootA, "widget");+ await skill(path.join(a, ".claude/skills"), "solo", "only one");+ const rows = await catalogSkills({ appDir: await temp(), homeDir: await temp(), projects: refs(a) });+ expect(resolveSkill(rows, "solo").skill?.description).toBe("only one");+ });++ it("keeps a global bare id winning over any project skill of the same name", async () => {+ const app = await temp();+ const rootA = await temp();+ const a = path.join(rootA, "mso");+ await skill(path.join(app, "claude-skills"), "mso", "official");+ await skill(path.join(a, ".claude/skills"), "mso", "project impostor");+ const rows = await catalogSkills({ appDir: app, homeDir: await temp(), projects: refs(a) });+ expect(resolveSkill(rows, "mso").skill).toMatchObject({ trust: "official", description: "official" });+ });+});++describe("catalog scans are bounded and say so", () => {+ it("caps entries in a GLOBAL skill root and reports the truncation", async () => {+ const app = await temp();+ const root = path.join(app, "claude-skills");+ await Promise.all(+ Array.from({ length: SKILL_SCAN_LIMITS.maxEntriesPerRoot + 5 }, (_, i) =>+ skill(root, `s${String(i).padStart(4, "0")}`, "many")),+ );+ const { skills, scan } = await catalogSkillsDetailed({ appDir: app, homeDir: await temp(), projects: [] });+ expect(skills.length).toBeLessThanOrEqual(SKILL_SCAN_LIMITS.maxEntriesPerRoot);+ expect(scan.truncated).toBe(true);+ expect(scan.truncationReasons.some((r) => r.startsWith("maxEntriesPerRoot"))).toBe(true);+ });++ it("reports truncated=false with no reasons when everything fit", async () => {+ const app = await temp();+ await skill(path.join(app, "claude-skills"), "one", "one");+ const { scan } = await catalogSkillsDetailed({ appDir: app, homeDir: await temp(), projects: [] });+ expect(scan).toMatchObject({ truncated: false, truncationReasons: [] });+ });++ it("caps the number of projects scanned and names the reason", async () => {+ const rootA = await temp();+ const projects = [];+ for (let i = 0; i < SKILL_SCAN_LIMITS.maxProjects + 2; i += 1) {+ const dir = path.join(rootA, `p${String(i).padStart(3, "0")}`);+ await skill(path.join(dir, ".claude/skills"), "s", "x");+ projects.push(dir);+ }+ const { scan } = await catalogSkillsDetailed({+ appDir: await temp(), homeDir: await temp(), projects: refs(...projects),+ });+ expect(scan.truncated).toBe(true);+ expect(scan.truncationReasons).toContain("maxProjects");+ });++ it("skips an oversized SKILL.md instead of loading it", async () => {+ const app = await temp();+ const root = path.join(app, "claude-skills");+ await skill(root, "sane", "sane one");+ const huge = path.join(root, "huge");+ await mkdir(huge, { recursive: true });+ await writeFile(path.join(huge, "SKILL.md"), "x".repeat(SKILL_SCAN_LIMITS.maxSkillBytes + 1));++ const rows = await catalogSkills({ appDir: app, homeDir: await temp(), projects: [] });+ expect(rows.map((r) => r.id)).toEqual(["sane"]);+ });++ it("still refuses a SKILL.md symlink whose target is not named SKILL.md", async () => {+ const app = await temp();+ const root = path.join(app, "claude-skills");+ const dir = path.join(root, "sneaky");+ await mkdir(dir, { recursive: true });+ const secret = path.join(app, "config");+ await writeFile(secret, "secret");+ await symlink(secret, path.join(dir, "SKILL.md"));+ const rows = await catalogSkills({ appDir: app, homeDir: await temp(), projects: [] });+ expect(rows).toEqual([]);+ });+});diff --git a/lib/skills/catalog-scan.ts b/lib/skills/catalog-scan.tsnew file mode 100644index 00000000..c723f2fd--- /dev/null+++ b/lib/skills/catalog-scan.ts@@ -0,0 +1,123 @@+// Reading ONE skill root: the bounded walk, the SKILL.md reader, and the ClawHub+// provenance check. Split from catalog.ts so the assembly/precedence logic there stays+// readable — and so every read on this side goes through the same byte-capped,+// O_NOFOLLOW reader rather than a convenient `fs.readFile`.+import { createHash } from "crypto";+import { promises as fs } from "fs";+import path from "path";+import { readBoundedRegularFile } from "@/lib/host/bounded-read";+import { SKILL_FILE, SKILL_SCAN_LIMITS, type ProjectRef, type SkillInfo, type SkillSource, type SkillTrust } from "./catalog-types";+import { projectSkillTrust } from "./project-skills";++export type RootSpec = {+ path: string;+ source: SkillSource;+ trust: SkillTrust;+ priority: number;+ verifyClawHub?: boolean;+ project?: ProjectRef;+};++/**+ * Skills intentionally live outside OS_FS_READ_ROOTS. Only an exact SKILL.md is+ * readable here: the path is realpath'd and its basename checked, so a link to+ * ~/.ssh/config resolves to basename "config" and is refused, while a link to another+ * SKILL.md stays equivalent to placing one in a skill root (handled by trust policy).+ * The realpath is then opened O_NOFOLLOW under a byte cap — an oversized SKILL.md is+ * skipped rather than loaded, because it is untrusted content.+ */+export async function readSkillFile(file: string): Promise<string | null> {+ const real = await fs.realpath(file).catch(() => null);+ if (!real || path.basename(real) !== SKILL_FILE) return null;+ return readBoundedRegularFile(real, SKILL_SCAN_LIMITS.maxSkillBytes);+}++export function skillDescription(md: string): string {+ const yaml = /^---\n([\s\S]*?)\n---/.exec(md)?.[1];+ const fromYaml = yaml?.match(/^description:\s*(.+)$/m)?.[1]?.replace(/^["']|["']$/g, "").trim();+ if (fromYaml) return fromYaml;+ return md.split("\n").find((line) => line.trim() && !line.startsWith("#") && !line.startsWith("---"))?.trim() ?? "";+}++type ClawHubOrigin = {+ registry?: string;+ ownerHandle?: string;+ installedVersion?: string;+ skillFile?: { sha256?: string };+};++async function verifiedBundledSkill(dir: string, md: string): Promise<Pick<SkillInfo, "trust" | "provenance">> {+ const raw = await readBoundedRegularFile(path.join(dir, ".clawhub/origin.json"), 64 * 1024);+ if (!raw) return { trust: "untrusted" };+ let origin: ClawHubOrigin;+ try {+ origin = JSON.parse(raw) as ClawHubOrigin;+ } catch {+ return { trust: "untrusted" };+ }+ const expected = origin.skillFile?.sha256?.toLowerCase();+ const actual = createHash("sha256").update(md).digest("hex");+ if (!expected || expected !== actual) return { trust: "untrusted" };+ return {+ trust: "verified",+ provenance: { registry: origin.registry, owner: origin.ownerHandle, version: origin.installedVersion, sha256: actual },+ };+}++/** Bounded `opendir` walk of ONE skill root — global roots included, which previously+ * had no entry budget at all. Names are capped before anything is stat'd or read. */+async function skillDirNames(root: string, deadlineAt: number): Promise<{ names: string[]; hitCap: boolean }> {+ const names: string[] = [];+ let hitCap = false;+ const handle = await fs.opendir(root).catch(() => null);+ if (!handle) return { names, hitCap };+ try {+ for await (const entry of handle) {+ if (names.length >= SKILL_SCAN_LIMITS.maxEntriesPerRoot || Date.now() > deadlineAt) { hitCap = true; break; }+ if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;+ names.push(entry.name);+ }+ } catch {+ // A root that vanishes mid-walk yields what we already have.+ }+ return { names: names.sort((a, b) => a.localeCompare(b)), hitCap };+}++export async function scanRoot(spec: RootSpec, deadlineAt: number): Promise<{ found: Array<{ skill: SkillInfo; priority: number }>; hitCap: boolean }> {+ const { names, hitCap } = await skillDirNames(spec.path, deadlineAt);+ const found: Array<{ skill: SkillInfo; priority: number }> = [];+ for (const name of names) {+ const dir = path.join(spec.path, name);+ if (!(await fs.stat(dir).catch(() => null))?.isDirectory()) continue;+ const file = path.join(dir, SKILL_FILE);+ const md = await readSkillFile(file);+ if (md === null) continue;++ let trust = spec.trust;+ let provenance: SkillInfo["provenance"];+ if (spec.verifyClawHub) {+ const verified = await verifiedBundledSkill(dir, md);+ trust = verified.trust;+ provenance = verified.provenance;+ } else if (spec.project) {+ // Path alone grants nothing: containment, ownership and SKILL.md shape decide.+ trust = await projectSkillTrust(dir, spec.project.path);+ }++ found.push({+ priority: spec.priority,+ skill: {+ id: spec.project ? `${spec.project.id}/${name}` : name,+ name,+ path: file,+ description: skillDescription(md),+ source: spec.source,+ trust,+ ...(spec.project ? { project: spec.project } : {}),+ ...(provenance ? { provenance } : {}),+ },+ });+ }+ return { found, hitCap };+}+diff --git a/lib/skills/catalog-types.ts b/lib/skills/catalog-types.tsindex 9f0bbbba..4820ee5e 100644--- a/lib/skills/catalog-types.ts+++ b/lib/skills/catalog-types.ts@@ -3,13 +3,33 @@export const SKILL_FILE = "SKILL.md";+export const SKILL_SCAN_LIMITS = {+ /** Directory entries READ from one skill root — global or per-project. */+ maxEntriesPerRoot: 200,+ /** Projects scanned for skills per catalog call. */+ maxProjects: 60,+ /** Project skills cataloged in total. */+ maxProjectSkills: 300,+ /** A SKILL.md larger than this is skipped, not truncated: it is untrusted content+ * and reading it is the cost we are bounding. */+ maxSkillBytes: 256 * 1024,+ /** Wall-clock ceiling for one whole catalog build. */+ maxScanMs: 4000,+} as const;+export type SkillTrust = "official" | "verified" | "local" | "untrusted";export type SkillSource = "mso" | "bundled" | "operator" | "claude" | "agents" | "codex" | "openclaw" | "project";+/** A project as the skill catalog sees it. `rootId` is the container id from+ * `lib/host/project-roots`, which is what makes two same-named projects in different+ * configured roots distinguishable rather than collapsed. */+export type ProjectRef = { id: string; name: string; path: string; rootId: string };+export type SkillInfo = {- /** The exact catalog id, and the ONLY key `skills_read` accepts. Global skills are- * addressed by bare name; a project skill is `<project>/<name>`, so two projects- * may ship `deploy` without either one shadowing the other — or an official skill. */+ /** The exact catalog id, and the ONLY key `skills_read` resolves without ambiguity.+ * A global skill is its bare name; a project skill is `<rootId>/<project>/<name>`,+ * so two projects — in the same root or in different ones — can ship `deploy`+ * without either shadowing the other or an official skill. */id: string;name: string;path: string;@@ -17,7 +37,7 @@ export type SkillInfo = {source: SkillSource;trust: SkillTrust;/** Present only for a skill discovered inside a project checkout. */- project?: { name: string; path: string };+ project?: ProjectRef;provenance?: {registry?: string;owner?: string;@@ -26,4 +46,13 @@ export type SkillInfo = {};};+/** What a catalog build could NOT cover. Mirrors lib/host's ScanReport so the two+ * discovery surfaces report incompleteness the same way. */+export type SkillScanReport = {+ truncated: boolean;+ truncationReasons: string[];+ scannedRoots: number;+ scannedProjects: number;+};+export const skillIsExecutableByDefault = (skill: Pick<SkillInfo, "trust">): boolean => skill.trust !== "untrusted";diff --git a/lib/skills/catalog.test.ts b/lib/skills/catalog.test.tsindex b4202fa6..dbbda4e7 100644--- a/lib/skills/catalog.test.ts+++ b/lib/skills/catalog.test.ts@@ -24,7 +24,7 @@ async function skill(dir: string, name: string, description: string) {return { target, md };}-// `projectDirs: []` keeps these cases about GLOBAL root precedence. Without it the+// `projects: []` keeps these cases about GLOBAL root precedence. Without it the// catalog also walks the real box's project containers, and the assertions would// depend on which projects happen to be checked out on the machine running them.// Per-project discovery has its own file: project-skills.test.ts.@@ -33,7 +33,7 @@ describe("skill catalog trust and precedence", () => {const app = await temp();const home = await temp();await skill(path.join(app, "claude-skills"), "mso", "official");- const rows = await catalogSkills({ appDir: app, homeDir: home, projectDirs: [] });+ const rows = await catalogSkills({ appDir: app, homeDir: home, projects: [] });expect(rows).toMatchObject([{ name: "mso", source: "mso", trust: "official", description: "official" }]);});@@ -42,7 +42,7 @@ describe("skill catalog trust and precedence", () => {const home = await temp();await skill(path.join(app, "claude-skills"), "mso", "official");await skill(path.join(home, ".claude/skills"), "mso", "host override");- const [row] = await catalogSkills({ appDir: app, homeDir: home, projectDirs: [] });+ const [row] = await catalogSkills({ appDir: app, homeDir: home, projects: [] });expect(row).toMatchObject({ name: "mso", source: "mso", trust: "official", description: "official" });});@@ -51,7 +51,7 @@ describe("skill catalog trust and precedence", () => {const home = await temp();await skill(path.join(app, "claude-skills"), "mso", "official");await skill(path.join(home, ".mso/skills"), "mso", "operator override");- const [row] = await catalogSkills({ appDir: app, homeDir: home, projectDirs: [] });+ const [row] = await catalogSkills({ appDir: app, homeDir: home, projects: [] });expect(row).toMatchObject({ name: "mso", source: "operator", trust: "local", description: "operator override" });});@@ -62,11 +62,11 @@ describe("skill catalog trust and precedence", () => {await mkdir(path.join(target, ".clawhub"), { recursive: true });const sha256 = createHash("sha256").update(md).digest("hex");await writeFile(path.join(target, ".clawhub/origin.json"), JSON.stringify({ registry: "https://clawhub.ai", ownerHandle: "alice", installedVersion: "1.2.3", skillFile: { sha256 } }));- let [row] = await catalogSkills({ appDir: app, homeDir: home, projectDirs: [] });+ let [row] = await catalogSkills({ appDir: app, homeDir: home, projects: [] });expect(row).toMatchObject({ trust: "verified", provenance: { owner: "alice", version: "1.2.3", sha256 } });await writeFile(path.join(target, "SKILL.md"), md + "tampered\n");- [row] = await catalogSkills({ appDir: app, homeDir: home, projectDirs: [] });+ [row] = await catalogSkills({ appDir: app, homeDir: home, projects: [] });expect(row.trust).toBe("untrusted");});diff --git a/lib/skills/catalog.ts b/lib/skills/catalog.tsindex 4fa5ab39..fc99e1b0 100644--- a/lib/skills/catalog.ts+++ b/lib/skills/catalog.ts@@ -1,28 +1,22 @@-import { createHash } from "crypto";-import { promises as fs } from "fs";import os from "os";import path from "path";-import { SKILL_FILE, skillIsExecutableByDefault, type SkillInfo, type SkillSource, type SkillTrust } from "./catalog-types";-import { PROJECT_SKILL_LIMITS, projectSkillRoots, projectSkillTrust, type ProjectRef } from "./project-skills";+import { scanRoot, type RootSpec } from "./catalog-scan";+import {+ SKILL_FILE, SKILL_SCAN_LIMITS, skillIsExecutableByDefault,+ type ProjectRef, type SkillInfo, type SkillScanReport, type SkillSource, type SkillTrust,+} from "./catalog-types";+import { discoveredProjects, projectSkillRoots } from "./project-skills";-export { SKILL_FILE, skillIsExecutableByDefault };-export type { SkillInfo, SkillSource, SkillTrust };--type RootSpec = {- path: string;- source: SkillSource;- trust: SkillTrust;- priority: number;- verifyClawHub?: boolean;- project?: ProjectRef;-};+export { SKILL_FILE, SKILL_SCAN_LIMITS, skillIsExecutableByDefault };+export { readSkillFile, skillDescription } from "./catalog-scan";+export type { ProjectRef, SkillInfo, SkillScanReport, SkillSource, SkillTrust };type CatalogOptions = {appDir?: string;homeDir?: string;- /** Project directories to scan for per-project skill roots. Defaults to every- * project across every configured container; pass `[]` to catalog global roots only. */- projectDirs?: Array<{ dir: string }>;+ /** Projects to scan for per-project skill roots. Defaults to every project across+ * every configured container; pass `[]` to catalog global roots only. */+ projects?: ProjectRef[];};/**@@ -34,9 +28,9 @@ type CatalogOptions = {* MSO's own instructions. Bundled third-party skills are verified by their ClawHub* SKILL.md hash. Generic discovered roots are visible but untrusted.*- * Per-project roots sit BELOW all of these (priority 56–60, see project-skills.ts)- * and are addressed by a `<project>/<name>` id, so a project skill can neither- * outrank nor collide with an operator or official one.+ * Per-project roots sit BELOW all of these (priority 56–60) and are addressed by a+ * `<rootId>/<project>/<name>` id, so a project skill can neither outrank nor collide+ * with an operator or official one — nor with the same-named project in another root.*/export function skillRoots(appDir = process.cwd(), homeDir = os.homedir()): RootSpec[] {return [@@ -51,123 +45,79 @@ export function skillRoots(appDir = process.cwd(), homeDir = os.homedir()): Root];}-/**- * Skills intentionally live outside OS_FS_READ_ROOTS. Only an exact SKILL.md is- * readable here. A symlink to ~/.ssh/config resolves to basename "config" and is- * refused. A symlink to another SKILL.md is equivalent to placing a SKILL.md in a- * skill root and is therefore handled by the trust/source policy above.- */-export async function readSkillFile(file: string): Promise<string | null> {- const real = await fs.realpath(file).catch(() => null);- if (!real || path.basename(real) !== SKILL_FILE) return null;- return fs.readFile(real, "utf8").catch(() => null);-}--async function isSkillDir(root: string, entry: { name: string; isDirectory(): boolean; isSymbolicLink(): boolean }): Promise<boolean> {- if (entry.isDirectory()) return true;- if (!entry.isSymbolicLink()) return false;- return (await fs.stat(path.join(root, entry.name)).catch(() => null))?.isDirectory() ?? false;-}--export function skillDescription(md: string): string {- const yaml = /^---\n([\s\S]*?)\n---/.exec(md)?.[1];- const fromYaml = yaml?.match(/^description:\s*(.+)$/m)?.[1]?.replace(/^["']|["']$/g, "").trim();- if (fromYaml) return fromYaml;- return md.split("\n").find((line) => line.trim() && !line.startsWith("#") && !line.startsWith("---"))?.trim() ?? "";-}+export type SkillCatalog = { skills: SkillInfo[]; scan: SkillScanReport };-type ClawHubOrigin = {- registry?: string;- ownerHandle?: string;- installedVersion?: string;- skillFile?: { sha256?: string };-};+/** The full build, including what it could not cover. Callers that surface+ * completeness to a model or an operator must use this, not `catalogSkills`. */+export async function catalogSkillsDetailed(options: CatalogOptions = {}): Promise<SkillCatalog> {+ const appDir = options.appDir ?? process.cwd();+ const homeDir = options.homeDir ?? os.homedir();+ const deadlineAt = Date.now() + SKILL_SCAN_LIMITS.maxScanMs;+ const reasons: string[] = [];++ let projects = options.projects;+ if (!projects) {+ const discovered = await discoveredProjects();+ projects = discovered.projects;+ reasons.push(...discovered.truncationReasons);+ }+ const { roots: projectRoots, truncated: projectsCapped } = await projectSkillRoots(projects);+ if (projectsCapped) reasons.push("maxProjects");++ const specs: RootSpec[] = [+ ...skillRoots(appDir, homeDir),+ ...projectRoots.map((root): RootSpec => ({+ path: root.path, source: "project", trust: "untrusted", priority: root.priority, project: root.project,+ })),+ ];-async function verifiedBundledSkill(dir: string, md: string): Promise<Pick<SkillInfo, "trust" | "provenance">> {- const originPath = path.join(dir, ".clawhub/origin.json");- const raw = await fs.readFile(originPath, "utf8").catch(() => "");- if (!raw) return { trust: "untrusted" };- let origin: ClawHubOrigin;- try {- origin = JSON.parse(raw) as ClawHubOrigin;- } catch {- return { trust: "untrusted" };+ const chosen = new Map<string, { skill: SkillInfo; priority: number }>();+ let projectSkills = 0;+ for (const spec of specs) {+ if (Date.now() > deadlineAt) { reasons.push("deadline"); break; }+ if (spec.project && projectSkills >= SKILL_SCAN_LIMITS.maxProjectSkills) { reasons.push("maxProjectSkills"); break; }+ const { found, hitCap } = await scanRoot(spec, deadlineAt);+ if (hitCap) reasons.push(`maxEntriesPerRoot:${spec.path}`);+ for (const candidate of found) {+ if (spec.project) projectSkills += 1;+ const current = chosen.get(candidate.skill.id);+ if (!current || candidate.priority > current.priority) chosen.set(candidate.skill.id, candidate);+ }}- const expected = origin.skillFile?.sha256?.toLowerCase();- const actual = createHash("sha256").update(md).digest("hex");- if (!expected || expected !== actual) return { trust: "untrusted" };++ const truncationReasons = [...new Set(reasons)];return {- trust: "verified",- provenance: {- registry: origin.registry,- owner: origin.ownerHandle,- version: origin.installedVersion,- sha256: actual,+ skills: [...chosen.values()].map(({ skill }) => skill).sort((a, b) => a.id.localeCompare(b.id)),+ scan: {+ truncated: truncationReasons.length > 0,+ truncationReasons,+ scannedRoots: specs.length,+ scannedProjects: Math.min(projects.length, SKILL_SCAN_LIMITS.maxProjects),},};}-async function scanRoot(spec: RootSpec, budget: { left: number }): Promise<Array<{ skill: SkillInfo; priority: number }>> {- const entries = await fs.readdir(spec.path, { withFileTypes: true }).catch(() => []);- const found: Array<{ skill: SkillInfo; priority: number }> = [];- const limit = spec.project ? PROJECT_SKILL_LIMITS.maxSkillsPerRoot : entries.length;- for (const entry of entries.slice().sort((a, b) => a.name.localeCompare(b.name))) {- if (found.length >= limit || (spec.project && budget.left <= 0)) break;- if (!(await isSkillDir(spec.path, entry))) continue;- const dir = path.join(spec.path, entry.name);- const file = path.join(dir, SKILL_FILE);- const md = await readSkillFile(file);- if (!md) continue;-- let trust = spec.trust;- let provenance: SkillInfo["provenance"];- if (spec.verifyClawHub) {- const verified = await verifiedBundledSkill(dir, md);- trust = verified.trust;- provenance = verified.provenance;- } else if (spec.project) {- // Path alone grants nothing: containment, ownership and SKILL.md shape decide.- trust = await projectSkillTrust(dir, spec.project.path);- budget.left -= 1;- }-- found.push({- priority: spec.priority,- skill: {- id: spec.project ? `${spec.project.name}/${entry.name}` : entry.name,- name: entry.name,- path: file,- description: skillDescription(md),- source: spec.source,- trust,- ...(spec.project ? { project: spec.project } : {}),- ...(provenance ? { provenance } : {}),- },- });- }- return found;-}-export async function catalogSkills(options: CatalogOptions = {}): Promise<SkillInfo[]> {- const appDir = options.appDir ?? process.cwd();- const homeDir = options.homeDir ?? os.homedir();- const projectRoots = (await projectSkillRoots(options.projectDirs))- .map((root): RootSpec => ({ path: root.path, source: "project", trust: "untrusted", priority: root.priority, project: root.project }));- const chosen = new Map<string, { skill: SkillInfo; priority: number }>();- const budget = { left: PROJECT_SKILL_LIMITS.maxProjectSkills };-- for (const spec of [...skillRoots(appDir, homeDir), ...projectRoots]) {- for (const candidate of await scanRoot(spec, budget)) {- const current = chosen.get(candidate.skill.id);- if (!current || candidate.priority > current.priority) chosen.set(candidate.skill.id, candidate);- }- }+ return (await catalogSkillsDetailed(options)).skills;+}- return [...chosen.values()].map(({ skill }) => skill).sort((a, b) => a.id.localeCompare(b.id));+/**+ * Resolve a catalog id. The exact id always wins. A bare name is a CONVENIENCE, and+ * only when it is unambiguous: two projects may legitimately ship `deploy`, and+ * silently picking one would hand a model the wrong instructions. An ambiguous hint+ * returns the candidate ids instead of a guess.+ */+export function resolveSkill(skills: SkillInfo[], idOrName: string): { skill?: SkillInfo; ambiguous?: string[] } {+ const exact = skills.find((s) => s.id === idOrName);+ if (exact) return { skill: exact };+ const loose = skills.filter((s) =>+ s.name === idOrName || (s.project ? `${s.project.name}/${s.name}` === idOrName : false));+ if (loose.length === 1) return { skill: loose[0] };+ if (loose.length > 1) return { ambiguous: loose.map((s) => s.id) };+ return {};}-/** Resolve a catalog id. Falls back to the bare `name` so pre-id callers and the- * `mso skills read <name>` CLI keep working for global skills. */+/** Unambiguous-only lookup, for callers that just want a skill or a 404. */export function findSkill(skills: SkillInfo[], idOrName: string): SkillInfo | undefined {- return skills.find((s) => s.id === idOrName) ?? skills.find((s) => s.name === idOrName && !s.project);+ return resolveSkill(skills, idOrName).skill;}diff --git a/lib/skills/project-skills.test.ts b/lib/skills/project-skills.test.tsindex 6d730020..fb308b06 100644--- a/lib/skills/project-skills.test.ts+++ b/lib/skills/project-skills.test.ts@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, rm, symlink, writeFile } from "fs/promises";import os from "os";import path from "path";import { catalogSkills } from "./catalog";-import { PROJECT_SKILL_DIRS, projectSkillTrust } from "./project-skills";+import { PROJECT_SKILL_DIRS, projectRefFor, projectSkillTrust } from "./project-skills";const temps: string[] = [];async function temp() {@@ -22,9 +22,14 @@ async function skill(root: string, name: string, description: string) {return dir;}-/** Catalog with an explicit project list, so the box's real checkouts never leak in. */+/** Catalog with an explicit project list, so the box's real checkouts never leak in.+ * Refs are built the way the catalog builds them, so ids are never hand-rolled. */const catalog = (app: string, home: string, dirs: string[]) =>- catalogSkills({ appDir: app, homeDir: home, projectDirs: dirs.map((dir) => ({ dir })) });+ catalogSkills({ appDir: app, homeDir: home, projects: dirs.map((dir) => projectRefFor(dir, path.dirname(dir))) });++/** The root-qualified id the catalog assigns `<project>/<skill>`. Computed, never+ * typed by hand — the whole point is that it depends on the container path. */+const idFor = (dir: string, skillName: string) => `${projectRefFor(dir, path.dirname(dir)).id}/${skillName}`;describe("per-project skill discovery", () => {it("catalogs skills from every supported project root, in every project", async () => {@@ -37,7 +42,8 @@ describe("per-project skill discovery", () => {await skill(path.join(two, ".codex/skills"), "audit", "project two audit");const rows = await catalog(app, home, [one, two]);- expect(rows.map((r) => `${r.id}:${r.trust}`)).toEqual(["one/ship:local", "two/audit:local"]);+ expect(rows.map((r) => `${r.id}:${r.trust}`).sort()).toEqual(+ [`${idFor(one, "ship")}:local`, `${idFor(two, "audit")}:local`].sort());expect(rows[0]).toMatchObject({ name: "ship", source: "project", project: { name: "one", path: one } });});@@ -51,8 +57,8 @@ describe("per-project skill discovery", () => {await skill(path.join(two, ".claude/skills"), "deploy", "two deploy");const rows = await catalog(app, home, [one, two]);- expect(rows.map((r) => r.id)).toEqual(["one/deploy", "two/deploy"]);- expect(rows.map((r) => r.description)).toEqual(["one deploy", "two deploy"]);+ expect(rows.map((r) => r.id).sort()).toEqual([idFor(one, "deploy"), idFor(two, "deploy")].sort());+ expect(rows.map((r) => r.description).sort()).toEqual(["one deploy", "two deploy"]);});it("never lets a project skill shadow an operator or official skill of the same name", async () => {@@ -69,7 +75,7 @@ describe("per-project skill discovery", () => {expect(rows.find((r) => r.id === "mso")).toMatchObject({ source: "mso", trust: "official", description: "official" });expect(rows.find((r) => r.id === "ops")).toMatchObject({ source: "operator", trust: "local", description: "operator" });// The project copies remain visible, but only under their own namespaced ids.- expect(rows.map((r) => r.id).sort()).toEqual(["mso", "one/mso", "one/ops", "ops"]);+ expect(rows.map((r) => r.id).sort()).toEqual(["mso", "ops", idFor(proj, "mso"), idFor(proj, "ops")].sort());});it("ranks the explicit .mso/skills root above the agent-tool roots within one project", async () => {@@ -81,7 +87,7 @@ describe("per-project skill discovery", () => {await skill(path.join(proj, ".mso/skills"), "release", "explicit mso copy");const rows = await catalog(app, home, [proj]);- expect(rows).toEqual([expect.objectContaining({ id: "one/release", description: "explicit mso copy" })]);+ expect(rows).toEqual([expect.objectContaining({ id: idFor(proj, "release"), description: "explicit mso copy" })]);});it("lists every documented project skill root", () => {@@ -100,7 +106,7 @@ describe("project skill trust is earned, not assumed", () => {await expect(projectSkillTrust(evil, proj)).resolves.toBe("untrusted");const rows = await catalog(await temp(), await temp(), [proj]);- expect(rows).toEqual([expect.objectContaining({ id: "one/escape", trust: "untrusted", source: "project" })]);+ expect(rows).toEqual([expect.objectContaining({ id: idFor(proj, "escape"), trust: "untrusted", source: "project" })]);});it("refuses a SKILL.md that is a symlink rather than a regular file", async () => {diff --git a/lib/skills/project-skills.ts b/lib/skills/project-skills.tsindex 381c3721..bbccdafe 100644--- a/lib/skills/project-skills.ts+++ b/lib/skills/project-skills.ts@@ -15,10 +15,11 @@// Anything else is cataloged as `untrusted`: visible for inspection, instructions// withheld. The generic HOME agent roots (~/.claude/skills, …) keep their existing// untrusted behaviour — this promotion is for project-scoped roots only.+import { createHash } from "crypto";import { promises as fs } from "fs";import path from "path";import { listProjectDirs } from "@/lib/host/project-roots";-import { SKILL_FILE, type SkillTrust } from "./catalog-types";+import { SKILL_FILE, SKILL_SCAN_LIMITS, type ProjectRef, type SkillTrust } from "./catalog-types";/** Where a project may keep skills. `.mso/skills` is the explicit MSO root — the* per-project counterpart of `~/.mso/skills` — and therefore ranks above the@@ -31,16 +32,6 @@ export const PROJECT_SKILL_DIRS = [".codex/skills",] as const;-export const PROJECT_SKILL_LIMITS = {- /** Projects scanned for skills per catalog call. */- maxProjects: 60,- /** Skill directories taken from one project root. */- maxSkillsPerRoot: 100,- /** Project skills cataloged in total. */- maxProjectSkills: 300,-} as const;--export type ProjectRef = { name: string; path: string };export type ProjectSkillRoot = { path: string; project: ProjectRef; priority: number };function currentUid(): number | undefined {@@ -59,6 +50,14 @@ function contains(parent: string, child: string): boolean {return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));}+/** The same short-hash identity `lib/host/project-roots` assigns a container, so a+ * skill's `project.rootId` and a `projects_list` row's `rootId` are the same value. */+export function projectRefFor(dir: string, containerPath: string): ProjectRef {+ const rootId = createHash("sha256").update(containerPath).digest("hex").slice(0, 8);+ const name = path.basename(dir);+ return { id: `${rootId}/${name}`, name, path: dir, rootId };+}+/*** The trust decision for ONE project skill directory. Exported so the catalog and* its tests exercise the same three checks rather than a reimplementation.@@ -74,24 +73,32 @@ export async function projectSkillTrust(skillDir: string, projectPath: string):return "local";}+/** Every project on the box, already containment- and ownership-checked by+ * `listProjectDirs`, as catalog-facing refs plus that walk's truncation report. */+export async function discoveredProjects(): Promise<{ projects: ProjectRef[]; truncationReasons: string[] }> {+ const { dirs, scan } = await listProjectDirs();+ return {+ projects: dirs.map(({ container, dir }) => projectRefFor(dir, container.path)),+ truncationReasons: scan.truncationReasons.map((reason) => `projects:${reason}`),+ };+}+/**- * Every per-project skill root on the box, in deterministic order: project order- * from `listProjectDirs()` (configured container order, then name), then- * `PROJECT_SKILL_DIRS` order. `priority` ranks a project skill BELOW every global- * root, so a project can never shadow an operator or official skill.+ * Every per-project skill root, in deterministic order: project order from the+ * container walk, then `PROJECT_SKILL_DIRS` order. `priority` ranks a project skill+ * BELOW every global root, so a project can never shadow an operator or official one.*/-export async function projectSkillRoots(projectDirs?: Array<{ dir: string }>): Promise<ProjectSkillRoot[]> {- const dirs = (projectDirs ?? (await listProjectDirs()).dirs).slice(0, PROJECT_SKILL_LIMITS.maxProjects);+export async function projectSkillRoots(projects: ProjectRef[]): Promise<{ roots: ProjectSkillRoot[]; truncated: boolean }> {+ const capped = projects.slice(0, SKILL_SCAN_LIMITS.maxProjects);const out: ProjectSkillRoot[] = [];- for (const { dir } of dirs) {- const project: ProjectRef = { name: path.basename(dir), path: dir };+ for (const project of capped) {for (const [index, sub] of PROJECT_SKILL_DIRS.entries()) {- const root = path.join(dir, sub);- const stat = await fs.lstat(root).catch(() => null);- if (!stat?.isDirectory() && !stat?.isSymbolicLink()) continue;+ const root = path.join(project.path, sub);+ // A symlinked skill root is still LISTED (projectSkillTrust downgrades it to+ // untrusted); what must not happen is it silently becoming `local`.if (!(await fs.stat(root).catch(() => null))?.isDirectory()) continue;out.push({ path: root, project, priority: 60 - index });}}- return out;+ return { roots: out, truncated: projects.length > capped.length };}diff --git a/lib/skills/search.ts b/lib/skills/search.tsindex 7ca01013..60e99690 100644--- a/lib/skills/search.ts+++ b/lib/skills/search.ts@@ -1,4 +1,4 @@-import { catalogSkills, readSkillFile, type SkillInfo } from "./catalog";+import { catalogSkillsDetailed, readSkillFile, type ProjectRef, type SkillInfo, type SkillScanReport } from "./catalog";import { listLearnedRecipes, type LearnedRecipe } from "./memory";import { embedSkillText, hybridSemanticScore, SKILL_EMBEDDING_VERSION } from "./semantic";@@ -14,7 +14,7 @@ export type SkillSearchHit = {id: string;name: string;/** Set when the hit is a skill that lives inside a project checkout. */- project?: { name: string; path: string };+ project?: ProjectRef;score: number;description: string;source?: string;@@ -34,7 +34,7 @@ export type SkillSearchOptions = {appDir?: string;homeDir?: string;/** Forwarded to catalogSkills; `[]` restricts the search to global roots. */- projectDirs?: Array<{ dir: string }>;+ projects?: ProjectRef[];};function skillQuality(skill: SkillInfo): number {@@ -54,6 +54,9 @@ export async function searchSkillMemory(query: string, options: SkillSearchOptioengine: string;query: string;hits: SkillSearchHit[];+ /** What the underlying catalog build could NOT cover. A search over a truncated+ * catalog is a search over part of the box, and the caller has to be able to say so. */+ catalog: SkillScanReport;recommendedRecipe?: SkillSearchHit;}> {const q = query.trim();@@ -90,7 +93,7 @@ export async function searchSkillMemory(query: string, options: SkillSearchOptio});}- const skills = await catalogSkills({ appDir: options.appDir, homeDir: options.homeDir, projectDirs: options.projectDirs });+ const { skills, scan } = await catalogSkillsDetailed({ appDir: options.appDir, homeDir: options.homeDir, projects: options.projects });for (const skill of skills) {if (!options.includeUntrusted && skill.trust === "untrusted") continue;const content = skill.trust === "untrusted" ? "" : (await readSkillFile(skill.path))?.slice(0, 18_000) ?? "";@@ -131,6 +134,7 @@ export async function searchSkillMemory(query: string, options: SkillSearchOptioengine: SKILL_EMBEDDING_VERSION,query: q,hits: sorted,+ catalog: scan,recommendedRecipe: sorted.find((h) => h.kind === "recipe" && h.score >= 0.22),};}diff --git a/skills/README.md b/skills/README.mdindex 856937b3..e530474e 100644--- a/skills/README.md+++ b/skills/README.md@@ -16,11 +16,18 @@ The assistant lists/loads only `official`, `verified`, and `local` instructions## Ids: a project skill cannot shadow anything-A global skill is addressed by its bare **name**. A project skill is `<project>/<name>`.-So two projects may both ship `deploy`, and neither can displace the operator or-official skill of the same name — the collision is impossible rather than resolved.-`skills_read` / `skills.read` accept the **exact id only**; they do not fuzzy-resolve-`deploy` into `widget/deploy`.+A global skill is addressed by its bare **name**. A project is `<rootId>/<name>` and a+project skill is `<rootId>/<project>/<name>`, where `rootId` is a short sha256 of the+canonical container path. That makes ids **globally unique**, which the bare+`<project>/<name>` form was not: two *different configured roots* may each hold a+`widget` shipping `deploy`, and both stay visible, readable and searchable instead of+one silently winning. The derived `projects/` container gets its own `rootId` for the+same reason, so `~/widget` and `~/projects/widget` cannot collide either.++`skills_read` / `skills.read` take the **exact id**. A bare name is accepted only when+it is unambiguous; when several projects ship it the call is **refused** and lists the+exact ids, because returning one project's instructions under another's name is exactly+the failure this id scheme exists to prevent.## Project skills earn `local` trust; they do not inherit it@@ -35,8 +42,16 @@ only when all three hold:Anything else is cataloged `untrusted`. The generic HOME agent roots keep their existinguntrusted behaviour; this promotion applies to project-scoped roots only.-Scans are bounded: 60 projects, 100 skills per root, 300 project skills and 24,000-characters of instructions per read.+Scans are bounded and say so. Caps: 12 containers, 400 entries per container, 400+projects, 60 projects scanned for skills, 200 entries per skill root, 300 project+skills, a 256 KiB `SKILL.md`, and a 4-second wall clock per walk. Directory iteration+uses `opendir` and stops at the cap rather than reading the whole listing first, and+every file read goes through one byte-capped `O_NOFOLLOW` reader that checks the cap+against `fstat` before any bytes move.++Every discovery response carries a **scan report**. `truncated:false` means "this is all+of it"; hitting a cap sets `truncated:true` and names the reason. Do not conclude a skill+is absent from a truncated scan.## Contract