docs(client): Agent Skills — close out the security review's SDK-side remainder

[XieX]

Stacked on #35. The Node half of the four items left open in our response to the Agent Skills security design review.

Three documentation items and one test item. No behavior changes — the only change to safe-fs.ts is its module docstring.

1. Privilege separation (row 9 docs half + counter-proposal for row 26)

The proposed mitigation for AZ-1, the review's most serious finding.

The README now documents reconcile-identity ≠ agent-identity as the recommended deployment, which is the whole reason the 0644/0755 modes deny anything: the agent reads its instructions and cannot rewrite them, or the manifest. Write access to the manifest is the worse half — it is what tells the next reconcile which paths the SDK may delete — which is why the prune path re-validates every entry from scratch rather than trusting it.

It matters more here than in Python. This runtime's residual race requires write permission on the managed root, and privilege separation is exactly what denies it. The security-posture note now points at the new section instead of ending on a bare "keep the root writable only by the process running the SDK".

ReconcileReport deliberately grows no writability field. Row 26 asked for one; we declined. The SDK knows only its own identity, which trivially has write access, having just written there. Any check it could make would answer a different question than the one asked and manufacture false confidence exactly where the review wants caution. agents.md records that reasoning so the field is not added later by someone reading its absence as an oversight.

2. Three hostile-manifest prune tests (row 12 remainder)

A well-formed manifest listing /etc/passwd, ../../../etc/passwd, and a path under a parent that has since become a symlink. The prune path already refuses all three; these turn asserted into verified, and they mirror the Python suite case for case.

Two things make them worth more than their line count:

• They are deliberately well-formed. The corrupt-manifest block above them proves nothing here — a corrupt manifest suppresses every destructive action wholesale, whereas these manifests give the implementation everything it needs to prune, and it must refuse anyway because the recorded path is not one this SDK could own.
• "Deleted nothing" runs through an fsOps.unlink spy, not through checking that /etc/passwd still exists. The test process cannot delete that file anyway, so the obvious assertion would pass against an implementation with no path check at all — permissions would be doing the work. The spy proves the removal is never attempted.

3. One sentence on '*' (row 16 remainder)

It materializes the whole project library, so every skill's description enters the agent's context — including skills no AI Config references and skills belonging to other teams.

4. Platform bound (row 2 residual) — deferred, explicitly, and sharper here

Decision: defer, with the bound written down. Reparse-point checks (GetFileAttributesW / FILE_FLAG_OPEN_REPARSE_POINT) are not implemented, and that is now recorded in safe-fs.ts, agents.md and the README.

The bound is stronger in this SDK than in Python, and the README understated it. It previously said Node's missing renameat/unlinkat affects "the final rename". In fact Node exposes no *at() family at all, so no destructive step can be descriptor-relative, and the racy per-component lstat floor is the only implementation — Linux included, not a Windows-only fallback as it is in Python. That is now stated plainly.

Rationale for deferring the Windows work:

• Windows is not a supported or tested platform for this release, and neither repository has a Windows CI runner — every matrix job is ubuntu-latest. agents.md already cites that absence as a reason not to add process.platform branches.
• Node offers no primitive that would make such checks meaningful here anyway, so the checks would harden Python only and break cross-language parity.

This retroactively lowers the priority of the row 25 reserved-device-name work, noted where that code lives. That code stays — it keeps a root written on Linux usable when read from Windows — but it is not evidence that Windows is hardened.

Parity

The Python half is launchdarkly/python-ai-sdk#66, case for case. No customer-visible surface moved: the ld.skills.integrity_failure event name, the eight reason_code tokens, the five SkillOutcomeReason tokens, and the log-record serialization are untouched.

Verification

• yarn test — all workspaces pass (client: 646 passed, 2 skipped; the 2 skips are the pre-existing TOCTOU tests gated off SUPPORTS_DIR_FD)
• yarn typecheck — clean
• yarn code:check (Biome) — clean

🤖 Generated with Claude Code

---

Note

Overview
This PR closes Agent Skills security-review follow-ups with real runtime hardening, not docs-only work. writeSkills now pins the managed root for the whole reconcile and routes child paths through /proc/self/fd/<fd>/… on Linux (SUPPORTS_PROC_FD, directoryAddress), closing the case where swapping the root (or a parent) for a symlink could redirect writes, updates, or prunes outside the tree. atomicWriteIn is removed; manifest and skill I/O use PinnedDirectory (path for reports, address for syscalls), and descriptor paths are stripped from operator-facing errors.

Untrusted SkillStore answers are tightened: allRawObjects returns { objects, error } instead of treating throws or non-object listings as “empty,” so '*' reconcile will not prune everything on a broken list; resolveFromStore rejects objects whose key does not match the request (accessors and materialization). Matching tests cover root-swap races (new skills-fs-root-swap.test.ts), store aliasing, listing failures, and well-formed manifest prune refusals (absolute/traversal paths and symlinked parents), plus TOCTOU tests now run when SUPPORTS_PROC_FD is true.

Documentation expands '*' scope, Linux vs macOS/Windows TOCTOU bounds, privilege separation (reconcile user ≠ agent, ancestor writability checklist), and agents.md guidance not to add Windows reparse checks or a managed-root writability field on ReconcileReport.

^{Reviewed by Cursor Bugbot for commit 19acd23. Bugbot is set up for automated code reviews on this repo. Configure here.}