Skip to content

armgit / mso

Public Imported from GitHub
0

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

fix(mcp): contain, bound and uniquely identify project discovery

rahmanef63bf8e810fae28
diff --git a/app/api/skills/route.ts b/app/api/skills/route.ts
index 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.md
index 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 storage
diff --git a/docs/CONNECTORS-GATEWAY-INTEGRATION.md b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
index 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.md
index 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 public
names 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 remov
MSO 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 workflows
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 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 new
tools 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.md
index 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` and
every 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 library
grid; 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 still
say "Skill" for the localStorage type.
diff --git a/frontend/slices/assistant/host-tools/catalog-skills.ts b/frontend/slices/assistant/host-tools/catalog-skills.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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): Promi
else 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: SkillSearchOptio
engine: 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: SkillSearchOptio
engine: 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.md
index 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 existing
untrusted 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