@sublang/playbook 18.1.0 → 18.1.1

package/docs/releases/18.1.1-preparation.md

@@ -0,0 +1,33 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Playbook 18.1.1 preparation
+
+## Scope and version classification
+
+The reviewed source range is v18.1.0 through a5592537bbface6eeb1af9b334f0c49a6cc84c24: native Windows private storage, preserved opened-directory validation and the corresponding CI required-check correction.
+The owner selected a PATCH release for the reviewed existing consumers; public API declarations, persisted formats, the POSIX Node floor and storage/evidence requirements remain unchanged.
+The 24 public typed entry points match the registry-published 18.1.0 declarations byte for byte.
+The Windows Node minimum is 22.19; directory fsync durability is not claimed equivalent to POSIX.
+
+The Cligent adoption must use the actually published 0.36.2 package, with its prepared and registry integrity matched, before this package is tagged.
+The accepted Cligent legacy-export removal and raw U+2028/U+2029 output limitations remain disclosed upstream; this release does not fix or waive them for unknown consumers.
+SLC remains outside this release scope because its existing Cligent and Playbook ranges admit these PATCH versions.
+
+## Verification and explicit exceptions
+
+- [x] Adopt registry Cligent 0.36.2 with dependency floor `^0.36.2`; frozen registry installation succeeded. The official SHA-512 matches the locally prepared archive when packed using the CI runtime (Node 22.23.4, npm 11.8.0); the npm gitHead is 8f61490171f109af9d3abfbcdb3ee6de50f4100d and its provenance subjects match that archive.
+- [x] Canonical local `pnpm test`: 2910 main-suite tests and 146 Cligent capability checks passed; 26 tests skipped by the existing suite on Mac.
+- [x] Final build after registry adoption passed with no compiled `.js` / `.d.ts` drift. Spec lint, SPDX, prepush and all 4322 relative documentation links passed.
+- [x] Canonical local model-free `pnpm smoke:release` passed all 11 steps (1039.1 seconds), including packed installation, shared-Captain continuation, compiled-artifact fidelity, release capabilities, persistence/assets and host capabilities.
+- [x] Real Claude Code acceptance: NOT RUN, explicitly waived by the owner on 2026-11-02 after the configured local provider rejected authentication. No credential is recorded here.
+- [x] The canonical mixed Claude/Codex pnpm test:acceptance suite is NOT claimed passed: its workflows require Claude Code. The owner-authorized omission is release-specific; no test source or general release rule is disabled.
+- [x] A packed, globally installed candidate plus the official Codex SDK 0.159.0 completed the built-in `/inspect` workflow using the existing Mac login and gpt-6.1-sol. Exit 0, expected README marker returned, durable session ID present, repository HEAD/README/status unchanged. This is narrower evidence than the canonical mixed-agent acceptance suite; it is not a Windows or SPEX APP test.
+- [x] Conditional manual tmux UX check: NOT RUN, explicitly waived by the owner on 2026-11-02. Computer Use denied access to Terminal; the owner separately authorized this release-specific exception. No visual or manual interaction pass is claimed and no general release rule is disabled.
+- [ ] Commit and push the prepared candidate, require its CI, and create the matching v18.1.1 tag only after the remaining gates or explicit owner exceptions are settled.
+
+Local prepush (spec lint and tsc --noEmit) passed; SPDX passed for all 558 tracked files.
+The lockfile changes only the Cligent version, caret floor, snapshot key and registry integrity; unchanged Linux libc selectors remain intact.
+Local pre-adoption storage checks passed 102 tests with two Windows-only cases skipped on Mac.
+The final candidate still requires CI, including native Windows storage at Node 22.19; Mac checks alone are not Windows evidence.
+This pre-tag checkpoint does not claim publication or all-platform/all-agent acceptance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "18.1.0",
+  "version": "18.1.1",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -290,7 +290,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.36.1",
+    "@sublang/cligent": "^0.36.2",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
@@ -302,5 +302,8 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "@openclaw/fs-safe": "0.26.13"
   }
 }

package/reference/sdlc/code.playbook/bin/machine-identity.js

@@ -12,7 +12,7 @@ import { constants } from 'node:fs';
 import { chmod, link, lstat, mkdir, open, unlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { sameFileIdentity, syncDirectory, tightenPrivateEntry } from './private-paths.js';
+import { sameFileIdentity, syncDirectory, tightenPrivateEntry, mkdirPrivate } from './private-paths.js';
 
 export const MACHINE_IDENTITY_TAG_PREFIX = 'machine-id:v1:';
 export const PLAYBOOK_MACHINE_IDENTITY_UNAVAILABLE =
@@ -150,7 +150,7 @@ async function prepareDirectory(directory, path, fs) {
       throw new MachineIdentityUnavailableError(path, `its directory cannot be read: ${errorMessage(cause)}`);
     }
     try {
-      await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+      await mkdirPrivate(directory, fs, { recursive: true });
       await fs.chmod(directory, 0o700);
       stat = await fs.lstat(directory);
     } catch (creation) {

package/reference/sdlc/code.playbook/bin/private-paths.js

@@ -11,18 +11,55 @@
 // applies it to its state directory and file (playbook-cli-97).
 
 import { constants } from 'node:fs';
+import { dirname } from 'node:path';
+import { createRequire } from 'node:module';
+// POSIX hosts retain the existing Node floor and never load the optional
+// Windows mechanism. Native Windows requires Node 22.19 or newer.
+const windowsPermissions = process.platform === 'win32'
+  ? createRequire(import.meta.url)('@openclaw/fs-safe/permissions') : undefined;
+
+// The library owns Windows descriptor inspection and creation. This is the
+// store's admission policy, deliberately conservative even for unusual ACEs.
+export function privatePermissions(stat, mode, path) {
+  if (process.platform !== 'win32') return (Number(stat.mode) & 0o7777) === mode;
+  if (!path) throw new Error('private Windows permission checks require the entry path');
+  const facts = windowsPermissions.readOwnerAndDacl(path);
+  if (facts.status !== 'supported' || !facts.complete || !facts.isLocal || !facts.daclPresent || facts.unsupportedAceTypes.length) return false;
+  const trusted = new Set([facts.currentUserSid, 's-1-5-18', 's-1-5-32-544']);
+  return trusted.has(facts.ownerSid) && facts.aces.every(ace =>
+    ace.aceType === 'deny' || ace.mask === 0 || trusted.has(ace.sid));
+}
+
+export async function mkdirPrivate(path, fs, options = {}) {
+  if (process.platform !== 'win32') return fs.mkdir(path, { ...options, mode: 0o700 });
+  if (options.recursive) {
+    try { await fs.lstat(dirname(path)); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await mkdirPrivate(dirname(path), fs, { recursive: true });
+    }
+  }
+  try { await windowsPermissions.createPrivateDirectory(path); }
+  catch (error) {
+    if (error.code !== 'EEXIST' || !options.recursive) throw error;
+  }
+  const stat = await fs.lstat(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory() || !privatePermissions(stat, 0o700, path)) {
+    throw new Error('private Windows directory permission verification failed');
+  }
+}
 
 export function sameFileIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino;
 }
 
-export function verifyPrivateEntry(stat, directory, label, uid = process.getuid?.()) {
+export function verifyPrivateEntry(stat, directory, label, uid = process.getuid?.(), path) {
   const required = directory ? 0o700 : 0o600;
   if (
     stat.isSymbolicLink() ||
     (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1) ||
     (uid !== undefined && stat.uid !== uid) ||
-    (stat.mode & required) !== required
+    (process.platform === 'win32' ? !privatePermissions(stat, required, path) : (stat.mode & required) !== required)
   ) {
     throw new Error(`${label} refuses unsafe ownership, links, type, or owner access`);
   }
@@ -30,7 +67,9 @@ export function verifyPrivateEntry(stat, directory, label, uid = process.getuid?
 
 export async function tightenPrivateEntry(path, before, directory, fs, label) {
   const uid = process.getuid?.();
-  verifyPrivateEntry(before, directory, label, uid);
+  verifyPrivateEntry(before, directory, label, uid, path);
+  // Keep descriptor identity checks on both platforms; Windows admits ACLs
+  // without attempting POSIX fchmod on the opened directory.
   const handle = await fs.open(
     path,
     constants.O_RDONLY |
@@ -40,20 +79,20 @@ export async function tightenPrivateEntry(path, before, directory, fs, label) {
   );
   try {
     const opened = await handle.stat();
-    verifyPrivateEntry(opened, directory, label, uid);
+    verifyPrivateEntry(opened, directory, label, uid, path);
     if (!sameFileIdentity(before, opened)) {
       throw new Error(`${label}: the entry changed during permission preparation`);
     }
     const mode = directory ? 0o700 : 0o600;
-    if ((opened.mode & 0o7777) !== mode) await handle.chmod(mode);
+    if (process.platform !== 'win32' && (opened.mode & 0o7777) !== mode) await handle.chmod(mode);
     const after = await handle.stat();
-    verifyPrivateEntry(after, directory, label, uid);
+    verifyPrivateEntry(after, directory, label, uid, path);
     const current = await fs.lstat(path);
-    verifyPrivateEntry(current, directory, label, uid);
+    verifyPrivateEntry(current, directory, label, uid, path);
     if (
       !sameFileIdentity(after, current) ||
-      (after.mode & 0o7777) !== mode ||
-      (current.mode & 0o7777) !== mode
+      !privatePermissions(after, mode, path) ||
+      !privatePermissions(current, mode, path)
     ) {
       throw new Error(`${label}: permission tightening could not be verified`);
     }
@@ -64,6 +103,7 @@ export async function tightenPrivateEntry(path, before, directory, fs, label) {
 }
 
 export async function syncDirectory(path, fs) {
+  if (process.platform === 'win32') return;
   let directory;
   try {
     directory = await fs.open(path, 'r');

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
+import { privatePermissions, mkdirPrivate } from "./private-paths.js";
 import { execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
@@ -242,6 +243,7 @@ async function runGitText(cwd, args, options = {}) {
 }
 
 async function syncDirectory(path) {
+  if (process.platform === 'win32') return;
   let directory;
   try {
     directory = await open(path, 'r');
@@ -1167,7 +1169,7 @@ async function assertPrivateDirectory(path, label) {
   if (!info.isDirectory() || info.isSymbolicLink()) {
     throw new Error(`${label} is not a private directory`);
   }
-  if ((info.mode & 0o7777) !== 0o700) {
+  if (!privatePermissions(info, 0o700, path)) {
     throw new Error(`${label} permissions must be 0700`);
   }
   return info;
@@ -1176,7 +1178,7 @@ async function assertPrivateDirectory(path, label) {
 async function ensureClaimRoot(path) {
   let created = false;
   try {
-    await mkdir(path, { mode: 0o700 });
+    await mkdirPrivate(path, { mkdir, lstat });
     created = true;
   } catch (error) {
     if (errorCode(error) !== 'EEXIST') throw error;
@@ -1199,7 +1201,7 @@ async function readClaimOwner(activePath) {
   if (
     !pathInfo.isFile() ||
     pathInfo.isSymbolicLink() ||
-    (pathInfo.mode & 0o7777) !== 0o600
+    !privatePermissions(pathInfo, 0o600, filePath)
   ) {
     throw new Error('repository claim owner is not a private regular file');
   }
@@ -1213,7 +1215,7 @@ async function readClaimOwner(activePath) {
     const info = await handle.stat();
     if (
       !info.isFile() ||
-      (info.mode & 0o7777) !== 0o600 ||
+      !privatePermissions(info, 0o600, filePath) ||
       info.dev !== pathInfo.dev ||
       info.ino !== pathInfo.ino
     ) {
@@ -1234,7 +1236,7 @@ async function readClaimOwner(activePath) {
 
 async function createClaimStage(root, owner) {
   const stagePath = join(root, `.stage-${owner.ownerToken}`);
-  await mkdir(stagePath, { mode: 0o700 });
+  await mkdirPrivate(stagePath, { mkdir, lstat });
   await chmod(stagePath, 0o700);
   let handle;
   try {

package/reference/sdlc/code.playbook/bin/session-chunks.js

@@ -8,7 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { constants } from 'node:fs';
 import * as nativeFs from 'node:fs/promises';
 import { dirname, isAbsolute, join } from 'node:path';
-import { sameFileIdentity, tightenPrivateEntry, verifyPrivateEntry } from './private-paths.js';
+import { sameFileIdentity, tightenPrivateEntry, verifyPrivateEntry, mkdirPrivate, privatePermissions } from './private-paths.js';
 
 export const MAX_SESSION_CHUNK_BYTES = 8 * 1024 * 1024;
 const INLINE_BYTES = 16 * 1024;
@@ -28,14 +28,14 @@ function reference(value) {
       value.byteLength < 1 || value.byteLength > MAX_SESSION_CHUNK_BYTES) fail();
   return value;
 }
-function privateStat(stat, directory) {
+function privateStat(stat, directory, path) {
   if (typeof stat.mode === 'bigint') {
     const original = stat;
     stat = { ...stat, mode: Number(stat.mode), uid: Number(stat.uid), nlink: Number(stat.nlink),
       isFile: () => original.isFile(), isDirectory: () => original.isDirectory(), isSymbolicLink: () => original.isSymbolicLink() };
   }
-  verifyPrivateEntry(stat, directory, 'session chunk');
-  if ((stat.mode & 0o7777) !== (directory ? 0o700 : 0o600)) throw new Error('session chunk permissions must be private');
+  verifyPrivateEntry(stat, directory, 'session chunk', undefined, path);
+  if (!privatePermissions(stat, directory ? 0o700 : 0o600, path)) throw new Error('session chunk permissions must be private');
 }
 function unchanged(before, after) {
   const precise = before.mtimeNs !== undefined && after.mtimeNs !== undefined;
@@ -64,7 +64,7 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
     while (cachedBytes > CACHE_BYTES || verified.size > CACHE_NODES) forget(verified.keys().next().value);
   };
   const operations = new AsyncLocalStorage();
-  const freshDirectory = async () => { const stat = await fs.lstat(directory); privateStat(stat, true); return stat; };
+  const freshDirectory = async () => { const stat = await fs.lstat(directory); privateStat(stat, true, directory); return stat; };
   const checkDirectory = async () => {
     const context = operations.getStore();
     if (context?.owner) return context.owner;
@@ -82,10 +82,10 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
   const sync = async (path, expected) => {
     const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_DIRECTORY ?? 0));
     try {
-      const opened = await handle.stat(); privateStat(opened, true);
+      const opened = await handle.stat(); privateStat(opened, true, path);
       if (expected && !sameFileIdentity(expected, opened)) throw new Error('session chunk directory changed');
-      await handle.sync();
-      const current = await fs.lstat(path); privateStat(current, true);
+      if (process.platform !== 'win32') await handle.sync();
+      const current = await fs.lstat(path); privateStat(current, true, path);
       if (!sameFileIdentity(opened, current)) throw new Error('session chunk directory changed');
     } finally { await handle.close(); }
   };
@@ -95,8 +95,8 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
     try { stat = await fs.lstat(directory); }
     catch (error) {
       if (error.code !== 'ENOENT' || !createDirectory) throw error;
-      const parent = await fs.lstat(dirname(directory)); privateStat(parent, true);
-      try { await fs.mkdir(directory, { mode: 0o700 }); }
+      const parent = await fs.lstat(dirname(directory)); privateStat(parent, true, dirname(directory));
+      try { await mkdirPrivate(directory, fs); }
       catch (cause) { if (cause.code !== 'EEXIST') throw cause; }
       stat = await fs.lstat(directory);
       await sync(dirname(directory), parent);
@@ -113,12 +113,12 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
       if (!match) continue;
       const path = join(directory, name);
       const temporary = await fs.lstat(path);
-      if (temporary.nlink === 1) privateStat(temporary, false);
+      if (temporary.nlink === 1) privateStat(temporary, false, path);
       else {
         // A crash between exclusive link publication and alias removal may
         // leave precisely these two names for one private store-owned inode.
         if (temporary.isSymbolicLink() || !temporary.isFile() || temporary.nlink !== 2 ||
-            (process.getuid && temporary.uid !== process.getuid()) || (temporary.mode & 0o7777) !== 0o600) throw new Error('unsafe interrupted session chunk publication');
+            (process.getuid && temporary.uid !== process.getuid()) || !privatePermissions(temporary, 0o600, path)) throw new Error('unsafe interrupted session chunk publication');
         const destination = await fs.lstat(join(directory, match[1]));
         if (!unchanged(temporary, destination) || destination.isSymbolicLink()) throw new Error('session chunk temporary alias differs from publication');
         pendingAliases.set(match[1], temporary);
@@ -144,7 +144,7 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
     reference(ref);
     const owner = await checkDirectory();
     const path = join(directory, ref.sha256);
-    const before = await fs.lstat(path, { bigint: true }); privateStat(before, false);
+    const before = await fs.lstat(path, { bigint: true }); privateStat(before, false, path);
     if (BigInt(before.size) !== BigInt(ref.byteLength)) throw new Error('session chunk length mismatch');
     const cached = verified.get(ref.sha256);
     if (!operations.getStore()?.force && cached && before.mtimeNs !== undefined &&
@@ -155,7 +155,7 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
     forget(ref.sha256);
     const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
     try {
-      const opened = await handle.stat({ bigint: true }); privateStat(opened, false);
+      const opened = await handle.stat({ bigint: true }); privateStat(opened, false, path);
       if (!unchanged(before, opened)) throw new Error('session chunk changed before read');
       // Read the proven bounded length, rather than readFile on a growing file.
       const bytes = Buffer.alloc(ref.byteLength);
@@ -165,8 +165,8 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
         if (!bytesRead) throw new Error('session chunk truncated during read');
         offset += bytesRead;
       }
-      const after = await handle.stat({ bigint: true }); privateStat(after, false);
-      const current = await fs.lstat(path, { bigint: true }); privateStat(current, false);
+      const after = await handle.stat({ bigint: true }); privateStat(after, false, path);
+      const current = await fs.lstat(path, { bigint: true }); privateStat(current, false, path);
       if (!unchanged(opened, after) || !unchanged(after, current) || !sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk changed during read');
       if (hash(bytes) !== ref.sha256) throw new Error('session chunk digest mismatch');
       if ([before, opened, after, current].every((stat) => stat.mtimeNs !== undefined && stat.ctimeNs !== undefined)) remember(ref.sha256, bytes, current, owner);
@@ -202,10 +202,10 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
     try {
       handle = await fs.open(temporary, 'wx', 0o600);
       await handle.chmod(0o600);
-      const opened = await handle.stat(); privateStat(opened, false);
+      const opened = await handle.stat(); privateStat(opened, false, temporary);
       await handle.writeFile(bytes); await handle.sync();
-      const after = await handle.stat(); privateStat(after, false);
-      const current = await fs.lstat(temporary); privateStat(current, false);
+      const after = await handle.stat(); privateStat(after, false, temporary);
+      const current = await fs.lstat(temporary); privateStat(current, false, temporary);
       if (!sameFileIdentity(opened, after) || !unchanged(after, current) || after.size !== bytes.length || !sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk changed during write');
       await handle.close(); handle = undefined;
       // link is exclusive publication; remove its temporary alias before any
@@ -384,9 +384,9 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
         const temporary = /^\.write-([0-9a-f]{64})-[0-9a-f-]{36}\.tmp$/.exec(name);
         if (temporary && stat.nlink === 2) {
           if (stat.isSymbolicLink() || !stat.isFile() ||
-              (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o7777) !== 0o600 ||
+              (process.getuid && stat.uid !== process.getuid()) || !privatePermissions(stat, 0o600, path) ||
               !unchanged(stat, await fs.lstat(join(directory, temporary[1])))) throw new Error('unsafe interrupted session chunk publication');
-        } else privateStat(stat, false);
+        } else privateStat(stat, false, join(directory, name));
         continue;
       }
       if (stat.size > MAX_SESSION_CHUNK_BYTES) throw new Error('session chunk exceeds file bound');
@@ -409,10 +409,10 @@ export function createSessionChunks({ directory, fsOps, createDirectory = true }
     const names = await fs.readdir(directory);
     // Validate every candidate before removing any; links and subdirectories
     // are never followed or recursively removed.
-    for (const name of names) privateStat(await fs.lstat(join(directory, name)), false);
+    for (const name of names) privateStat(await fs.lstat(join(directory, name)), false, join(directory, name));
     for (const name of names) {
       if (!sameFileIdentity(owner, await checkDirectory())) throw new Error('session chunk directory changed during deletion');
-      const path = join(directory, name); privateStat(await fs.lstat(path), false); await fs.unlink(path);
+      const path = join(directory, name); privateStat(await fs.lstat(path), false, path); await fs.unlink(path);
     }
     await sync(directory, owner);
     await fs.rmdir(directory);

package/reference/sdlc/code.playbook/bin/session-replay.js

@@ -8,7 +8,7 @@ import { constants } from 'node:fs';
 import * as nativeFs from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
 import { createSessionChunks, MAX_SESSION_CHUNK_BYTES } from './session-chunks.js';
-import { sameFileIdentity, tightenPrivateEntry, verifyPrivateEntry } from './private-paths.js';
+import { sameFileIdentity, tightenPrivateEntry, verifyPrivateEntry, privatePermissions } from './private-paths.js';
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const DIGEST = /^[0-9a-f]{64}$/;
@@ -21,9 +21,9 @@ function reference(value) {
       !count(value.byteLength) || value.byteLength < 1 || value.byteLength > MAX_SESSION_CHUNK_BYTES) invalid();
   return value;
 }
-function privateStat(stat, directory) {
-  verifyPrivateEntry(stat, directory, 'session replay');
-  if ((stat.mode & 0o7777) !== (directory ? 0o700 : 0o600)) throw new Error('session replay permissions must be private');
+function privateStat(stat, directory, path) {
+  verifyPrivateEntry(stat, directory, 'session replay', undefined, path);
+  if (!privatePermissions(stat, directory ? 0o700 : 0o600, path)) throw new Error('session replay permissions must be private');
 }
 const unchanged = (left, right) => sameFileIdentity(left, right) && left.size === right.size &&
   left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
@@ -32,8 +32,8 @@ function rootChanged(message) {
   error.replayRootRetry = true;
   return error;
 }
-function privateRootStat(stat) {
-  try { privateStat(stat, false); }
+function privateRootStat(stat, path) {
+  try { privateStat(stat, false, path); }
   catch (error) {
     // A complete initial root can briefly have its staging link, and an
     // already opened old root loses its last link on atomic replacement.
@@ -81,14 +81,14 @@ export async function createBoundedReplay({ sessionId, sessionsDir, fsOps, asser
     return result;
   };
   const directory = async () => {
-    const stat = await fs.lstat(sessionsDir); privateStat(stat, true); return stat;
+    const stat = await fs.lstat(sessionsDir); privateStat(stat, true, sessionsDir); return stat;
   };
   const syncDirectory = async (expected) => {
     const handle = await fs.open(sessionsDir, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_DIRECTORY ?? 0));
     try {
-      const stat = await handle.stat(); privateStat(stat, true);
+      const stat = await handle.stat(); privateStat(stat, true, sessionsDir);
       if (!sameFileIdentity(expected, stat)) throw new Error('session replay directory changed');
-      await handle.sync();
+      if (process.platform !== 'win32') await handle.sync();
       if (!sameFileIdentity(stat, await directory())) throw new Error('session replay directory changed');
     } finally { await handle.close(); }
   };
@@ -104,11 +104,11 @@ export async function createBoundedReplay({ sessionId, sessionsDir, fsOps, asser
     let before;
     try { before = await fs.lstat(path); }
     catch (error) { if (error.code === 'ENOENT') return { root: null, rootBytes: null, stat: null, owner }; throw error; }
-    privateRootStat(before);
+    privateRootStat(before, path);
     if (before.size > MAX_SESSION_CHUNK_BYTES) throw new Error('session replay root exceeds file bound');
     const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
     try {
-      const opened = await handle.stat(); privateRootStat(opened);
+      const opened = await handle.stat(); privateRootStat(opened, path);
       if (!unchanged(before, opened)) throw rootChanged('session replay root changed before read');
       const bytes = Buffer.alloc(opened.size);
       let offset = 0;
@@ -117,7 +117,7 @@ export async function createBoundedReplay({ sessionId, sessionsDir, fsOps, asser
         if (!bytesRead) throw rootChanged('session replay root truncated during read');
         offset += bytesRead;
       }
-      const after = await handle.stat(); privateRootStat(after);
+      const after = await handle.stat(); privateRootStat(after, path);
       if (!unchanged(opened, after)) throw rootChanged('session replay root changed during read');
       if (!sameFileIdentity(owner, await directory())) throw new Error('session replay directory changed during read');
       return { root: validateRoot(JSON.parse(bytes.toString('utf8'))), rootBytes: bytes, stat: after, owner };
@@ -137,7 +137,7 @@ export async function createBoundedReplay({ sessionId, sessionsDir, fsOps, asser
       throw new Error('session replay root changed before publication');
     }
     if (snapshot.stat !== null) {
-      const latest = await fs.lstat(path); privateStat(latest, false);
+      const latest = await fs.lstat(path); privateStat(latest, false, path);
       if (!unchanged(snapshot.stat, latest)) throw new Error('session replay root changed before publication');
     }
   };
@@ -177,10 +177,10 @@ export async function createBoundedReplay({ sessionId, sessionsDir, fsOps, asser
       await assertSnapshot(snapshot);
       handle = await fs.open(temporary, 'wx', 0o600);
       await handle.chmod(0o600);
-      temporaryStat = await handle.stat(); privateStat(temporaryStat, false);
+      temporaryStat = await handle.stat(); privateStat(temporaryStat, false, temporary);
       await handle.writeFile(bytes); await handle.sync();
-      const after = await handle.stat(); privateStat(after, false);
-      const current = await fs.lstat(temporary); privateStat(current, false);
+      const after = await handle.stat(); privateStat(after, false, temporary);
+      const current = await fs.lstat(temporary); privateStat(current, false, temporary);
       if (!sameFileIdentity(temporaryStat, after) || !sameFileIdentity(after, current)) throw new Error('session replay temporary root changed');
       await handle.close(); handle = undefined;
       await assertOwner();
@@ -191,7 +191,7 @@ export async function createBoundedReplay({ sessionId, sessionsDir, fsOps, asser
       // name before readers' single-link verification and directory syncing.
       if (exclusive || snapshot.root === null) await fs.unlink(temporary);
       await syncDirectory(snapshot.owner);
-      const published = await fs.lstat(path); privateStat(published, false);
+      const published = await fs.lstat(path); privateStat(published, false, path);
       if (!sameFileIdentity(temporaryStat, published) || published.size !== bytes.length) throw new Error('session replay root changed after publication');
       const completed = { owner: snapshot.owner, stat: published, rootBytes: bytes };
       mutationAnchor = proofOf(completed);

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -28,7 +28,7 @@ import {
   unlink,
 } from 'node:fs/promises';
 import { homedir, hostname as systemHostname } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import { assertSupportedEffort } from '@sublang/cligent';
@@ -51,7 +51,7 @@ import {
   lazyMachineIdentity,
   resolveMachineIdentity,
 } from './machine-identity.js';
-import { sameFileIdentity, syncDirectory, tightenPrivateEntry } from './private-paths.js';
+import { sameFileIdentity, syncDirectory, tightenPrivateEntry, mkdirPrivate, privatePermissions } from './private-paths.js';
 import { createSessionChunks } from './session-chunks.js';
 import { createBoundedReplay } from './session-replay.js';
 import { decodeStoredManifest, encodeStoredManifest, SESSION_STORAGE_VERSION } from './storage-manifest.js';
@@ -309,7 +309,7 @@ export function sanitizeReplayRecord(value) {
 // Bounded physical replay preserves the public readable/durable distinction.
 // A failed append latches history incompleteness; recovery writes remain open.
 async function createLeaseReplayWriter({ sessionsDir, path, fs, assertOwner, readStream, chunks }) {
-  const sessionId = path.slice(path.lastIndexOf('/') + 1, -'.records.jsonl'.length);
+  const sessionId = basename(path, '.records.jsonl');
   const backend = await createBoundedReplay({ sessionId, sessionsDir, fsOps: fs, assertOwner, chunks });
   let lastReadableSeq = null, lastDurableSeq = null, incomplete = true, closed = false;
   let tail = Promise.resolve();
@@ -895,7 +895,7 @@ export function createCaptainSessionStore(options = {}) {
       ownsTemporary = true;
       await handle.chmod(0o600);
       const tempStat = await handle.stat();
-      if (!tempStat.isFile() || (tempStat.mode & 0o7777) !== 0o600) {
+      if (!tempStat.isFile() || !privatePermissions(tempStat, 0o600, temporary)) {
         throw new Error('Captain session temporary path is not a private regular file');
       }
       await handle.writeFile(encoded);
@@ -991,7 +991,7 @@ export function createCaptainSessionStore(options = {}) {
       if (
         directoryStat.isSymbolicLink() ||
         !directoryStat.isDirectory() ||
-        (directoryStat.mode & 0o7777) !== 0o700
+        !privatePermissions(directoryStat, 0o700, path)
       ) {
         throw new Error('lease path is not a private real directory');
       }
@@ -1160,21 +1160,21 @@ export function createCaptainSessionStore(options = {}) {
     let handle;
     let created = false;
     try {
-      await fs.mkdir(stagePath, { mode: 0o700 });
+      await mkdirPrivate(stagePath, fs);
       created = true;
       await fs.chmod(stagePath, 0o700);
       const stageStat = await fs.lstat(stagePath);
       if (
         stageStat.isSymbolicLink() ||
         !stageStat.isDirectory() ||
-        (stageStat.mode & 0o7777) !== 0o700
+        !privatePermissions(stageStat, 0o700, stagePath)
       ) {
         throw new Error('Captain session lease stage is not a private directory');
       }
       handle = await fs.open(join(stagePath, LEASE_OWNER_FILE), 'wx', 0o600);
       await handle.chmod(0o600);
       const ownerStat = await handle.stat();
-      if (!ownerStat.isFile() || (ownerStat.mode & 0o7777) !== 0o600) {
+      if (!ownerStat.isFile() || !privatePermissions(ownerStat, 0o600, join(stagePath, LEASE_OWNER_FILE))) {
         throw new Error('Captain session lease owner is not a private regular file');
       }
       await handle.writeFile(`${JSON.stringify(owner)}\n`, 'utf8');
@@ -1922,7 +1922,7 @@ async function readReplaySnapshot({
 
   // During explicit migration the old root remains authoritative until the
   // new manifest publishes. New replay-only sessions have no manifest yet.
-  const sessionId = path.slice(path.lastIndexOf('/') + 1, -'.records.jsonl'.length);
+  const sessionId = basename(path, '.records.jsonl');
   let storedRoot;
   try { storedRoot = JSON.parse(await readPrivateRegularFile(join(sessionsDir, `${sessionId}.json`), 0o600, fs, 'record')); }
   catch (cause) { if (cause?.code !== 'ENOENT' && !(cause instanceof SyntaxError)) throw cause; }
@@ -1963,7 +1963,7 @@ async function readReplaySnapshot({
 
   try {
     const openedStat = await handle.stat();
-    assertPrivateRegularStat(openedStat, 0o600, 'replay stream');
+    assertPrivateRegularStat(openedStat, 0o600, 'replay stream', path);
     if (!sameFileIdentity(pathStat, openedStat)) {
       throw new ReplaySnapshotChangedError(
         'replay stream was replaced while opening its snapshot',
@@ -1987,7 +1987,7 @@ async function readReplaySnapshot({
     const bytes = await readReplayRange(handle, startOffset, snapshotLength);
 
     const finalHandleStat = await handle.stat();
-    assertPrivateRegularStat(finalHandleStat, 0o600, 'replay stream');
+    assertPrivateRegularStat(finalHandleStat, 0o600, 'replay stream', path);
     if (
       !sameFileIdentity(openedStat, finalHandleStat) ||
       requireReplayFileSize(finalHandleStat.size) < snapshotLength
@@ -2225,11 +2225,11 @@ function requireReplayFileSize(value) {
   return value;
 }
 
-function assertPrivateRegularStat(stat, mode, label) {
+function assertPrivateRegularStat(stat, mode, label, path) {
   if (!stat.isFile()) {
     throw new Error(`${label} path is not a regular file`);
   }
-  if ((stat.mode & 0o7777) !== mode) {
+  if (!privatePermissions(stat, mode, path)) {
     throw new Error(`${label} permissions must be ${octal(mode)}`);
   }
 }
@@ -6412,7 +6412,7 @@ async function readPrivateRegularFile(path, mode, fs, label, raw = false) {
     if (!stat.isFile()) {
       throw new Error(`${label} path is not a regular file`);
     }
-    if ((stat.mode & 0o7777) !== mode) {
+    if (!privatePermissions(stat, mode, path)) {
       throw new Error(`${label} permissions must be ${octal(mode)}`);
     }
     if (!sameFileIdentity(before, stat)) throw privateFileChanged(label, 'open');
@@ -6431,7 +6431,7 @@ async function assertPrivateRegularPath(path, mode, fs, label) {
   if (stat.isSymbolicLink() || !stat.isFile()) {
     throw new Error(`${label} path is not a real regular file`);
   }
-  if ((stat.mode & 0o7777) !== mode) {
+  if (!privatePermissions(stat, mode, path)) {
     throw new Error(`${label} permissions must be ${octal(mode)}`);
   }
   return stat;
@@ -6486,7 +6486,7 @@ async function ensurePrivateDirectory(path, fs, mayCreate = () => true) {
   for (const directory of missing.reverse()) {
     let created = false;
     try {
-      await fs.mkdir(directory, { mode: 0o700 });
+      await mkdirPrivate(directory, fs);
       created = true;
     } catch (cause) {
       if (cause?.code !== 'EEXIST') throw cause;
@@ -6497,7 +6497,7 @@ async function ensurePrivateDirectory(path, fs, mayCreate = () => true) {
       await syncDirectory(dirname(directory), fs);
     } else if (
       directory === path &&
-      (stat.mode & 0o7777) !== 0o700
+      !privatePermissions(stat, 0o700, path)
     ) {
       throw new Error('Captain session store directory permissions must be 0700');
     }
@@ -6533,7 +6533,7 @@ function isPathOrAncestor(directory, path) {
 
 async function assertPrivateDirectory(path, fs) {
   const stat = await assertDirectoryNotLink(path, fs);
-  if ((stat.mode & 0o7777) !== 0o700) {
+  if (!privatePermissions(stat, 0o700, path)) {
     throw new Error('Captain session store directory permissions must be 0700');
   }
 }

package/reference/sdlc/code.playbook/session-assets.js

@@ -3,6 +3,7 @@
 
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
+import { mkdirPrivate, privatePermissions } from './bin/private-paths.js';
 import { link, lstat, mkdir, open, readdir, unlink } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
 
@@ -64,21 +65,21 @@ export async function externalizeAgentEvent(store, event) {
 function assertOwner(stat, label) {
   if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) throw new Error(`${label} is not owned by the current user`);
 }
-function assertDirectory(stat) {
+function assertDirectory(stat, path) {
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('asset owner directory must be a real directory');
   assertOwner(stat, 'asset owner directory');
-  if (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o700) throw new Error('asset owner directory must have private 0700 permissions');
+  if (process.platform === 'win32' ? !privatePermissions(stat, 0o700, path) : (stat.mode & 0o777) !== 0o700) throw new Error('asset owner directory must have private 0700 permissions');
 }
-function assertFile(stat, label) {
+function assertFile(stat, label, path) {
   if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error(`${label} must be a single-link regular file`);
   assertOwner(stat, label);
-  if (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o600) throw new Error(`${label} must have private 0600 permissions`);
+  if (process.platform === 'win32' ? !privatePermissions(stat, 0o600, path) : (stat.mode & 0o777) !== 0o600) throw new Error(`${label} must have private 0600 permissions`);
 }
 function sameFile(a, b) { return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs; }
 async function syncDirectory(directory) {
   if (process.platform === 'win32') return;
   const handle = await open(directory, constants.O_RDONLY | noFollow);
-  try { assertDirectory(await handle.stat()); await handle.sync(); } finally { await handle.close(); }
+  try { assertDirectory(await handle.stat(), directory); await handle.sync(); } finally { await handle.close(); }
 }
 
 /** One immutable owner. A session host holds its ordinary lease around mutations. */
@@ -93,10 +94,10 @@ export function createAssetStore(options) {
   let importTail = Promise.resolve();
   const ensureDirectory = async (create) => {
     if (create) {
-      try { await mkdir(directory, { recursive: createAncestors, mode: 0o700 }); }
+      try { await mkdirPrivate(directory, { mkdir, lstat }, { recursive: createAncestors }); }
       catch (error) { if (createAncestors || error.code !== 'EEXIST') throw error; }
     }
-    assertDirectory(await lstat(directory));
+    assertDirectory(await lstat(directory), directory);
   };
   const prepare = async () => {
     let before;
@@ -107,6 +108,7 @@ export function createAssetStore(options) {
     const directoryHandle = await open(directory, constants.O_RDONLY | noFollow);
     try {
       const opened = await directoryHandle.stat();
+      if (process.platform === 'win32') assertDirectory(opened, directory);
       if (opened.dev !== before.dev || opened.ino !== before.ino) throw new Error('asset owner directory changed during preparation');
       // fchmod always moves ctime, which verified readers pin: change only modes that differ.
       if (process.platform !== 'win32' && (opened.mode & 0o777) !== 0o700) await directoryHandle.chmod(0o700);
@@ -123,25 +125,25 @@ export function createAssetStore(options) {
           const pinned = await handle.stat();
           if (!sameFile(stat, pinned)) throw new Error('asset entry changed during preparation');
           if (process.platform !== 'win32' && (pinned.mode & 0o777) !== 0o600) await handle.chmod(0o600);
-          assertFile(await handle.stat(), 'asset entry');
+          assertFile(await handle.stat(), 'asset entry', path);
           const final = await lstat(path);
           if (final.dev !== pinned.dev || final.ino !== pinned.ino || final.nlink !== 1) throw new Error('asset entry changed during preparation');
         } finally { await handle.close(); }
       }
       const final = await lstat(directory);
       if (final.dev !== opened.dev || final.ino !== opened.ino || final.isSymbolicLink()) throw new Error('asset owner directory changed during preparation');
-      assertDirectory(await directoryHandle.stat());
+      assertDirectory(await directoryHandle.stat(), directory);
     } finally { await directoryHandle.close(); }
   };
   const checkedOpen = async (filename, label) => {
     await ensureDirectory(false);
     const path = join(directory, filename);
     const before = await lstat(path);
-    assertFile(before, label);
+    assertFile(before, label, path);
     const handle = await open(path, constants.O_RDONLY | noFollow);
     try {
       const after = await handle.stat();
-      assertFile(after, label);
+      assertFile(after, label, path);
       if (!sameFile(before, after)) throw new Error(`${label} changed while opening`);
       return { handle, stat: after };
     } catch (error) { await handle.close(); throw error; }