@sublang/playbook 17.5.0 → 17.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.5.0",
+  "version": "17.6.0",
   "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",
@@ -81,6 +81,8 @@
     "reference/sdlc/code.playbook/session-store.d.ts",
     "reference/sdlc/code.playbook/host-capabilities.js",
     "reference/sdlc/code.playbook/host-capabilities.d.ts",
+    "reference/sdlc/code.playbook/machine-identity.js",
+    "reference/sdlc/code.playbook/machine-identity.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
@@ -89,6 +91,8 @@
     "reference/sdlc/code.playbook/bin/interactive-session.js",
     "reference/sdlc/code.playbook/bin/replay-observer.js",
     "reference/sdlc/code.playbook/bin/session-store.js",
+    "reference/sdlc/code.playbook/bin/private-paths.js",
+    "reference/sdlc/code.playbook/bin/machine-identity.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
     "reference/sdlc/code.playbook/bin/repository-effects.js",
@@ -201,6 +205,10 @@
       "types": "./reference/sdlc/code.playbook/host-capabilities.d.ts",
       "default": "./reference/sdlc/code.playbook/host-capabilities.js"
     },
+    "./machine-identity": {
+      "types": "./reference/sdlc/code.playbook/machine-identity.d.ts",
+      "default": "./reference/sdlc/code.playbook/machine-identity.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",

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

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// One machine identity per user and machine (DR-087, playbook-cli-97): a
+// tagged value read from a private file under the XDG state directory,
+// published once and exclusively, never replaced, and carried in the
+// `hostname` field of session leases and repository claims in place of
+// `os.hostname()`, which the network renames.
+
+import { randomUUID } from 'node:crypto';
+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';
+
+export const MACHINE_IDENTITY_TAG_PREFIX = 'machine-id:v1:';
+export const PLAYBOOK_MACHINE_IDENTITY_UNAVAILABLE =
+  'PLAYBOOK_MACHINE_IDENTITY_UNAVAILABLE';
+
+const IDENTITY_FILE = 'machine-id';
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const PUBLISH_ATTEMPTS = 3;
+// A publication links its complete temporary into place and unlinks the
+// temporary right after, so a reader can meet the file with two links for
+// an instant; it re-reads a few times before calling that a hard link.
+const LINK_SETTLE_ATTEMPTS = 10;
+const LINK_SETTLE_DELAY_MS = 20;
+const DEFAULT_FS_OPERATIONS = Object.freeze({
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  open,
+  unlink,
+});
+const resolved = new Map();
+
+/** Exactly the tagged form: the prefix and one lowercase UUID. */
+export function isMachineIdentity(value) {
+  return (
+    typeof value === 'string' &&
+    value.startsWith(MACHINE_IDENTITY_TAG_PREFIX) &&
+    UUID_PATTERN.test(value.slice(MACHINE_IDENTITY_TAG_PREFIX.length))
+  );
+}
+
+/** How a lease or claim reader reads an owner's `hostname` field
+ * (playbook-cli-23): the exact tag is an identity compared with this
+ * machine's; a value that begins like the tag but fails its form is
+ * unverifiable; anything else is a legacy host name compared with the
+ * current one. */
+export function classifyOwnerMachine(value, localIdentity, legacyHostname) {
+  if (isMachineIdentity(value)) {
+    return value === localIdentity ? 'local' : 'foreign';
+  }
+  if (typeof value === 'string' && value.startsWith('machine-id:')) {
+    return 'unverifiable';
+  }
+  return value === legacyHostname ? 'local' : 'foreign';
+}
+
+/** A reader's word for an owner's `hostname` value in a diagnostic. */
+export function describeOwnerMachine(value) {
+  return isMachineIdentity(value)
+    ? `another machine (identity ${JSON.stringify(value)})`
+    : `foreign host ${JSON.stringify(value)}`;
+}
+
+export function machineIdentityPath(env = process.env, home = homedir()) {
+  const stateHome =
+    typeof env.XDG_STATE_HOME === 'string' && env.XDG_STATE_HOME.trim().length > 0
+      ? env.XDG_STATE_HOME
+      : join(
+          typeof env.HOME === 'string' && env.HOME.trim().length > 0 ? env.HOME : home,
+          '.local',
+          'state',
+        );
+  return join(stateHome, 'playbook', IDENTITY_FILE);
+}
+
+class MachineIdentityUnavailableError extends Error {
+  constructor(path, reason) {
+    super(`machine identity file ${path} is unavailable: ${reason}`);
+    this.name = 'MachineIdentityUnavailableError';
+    this.code = PLAYBOOK_MACHINE_IDENTITY_UNAVAILABLE;
+    this.path = path;
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Read the identity, publishing one when none exists; the result is kept
+ * for the process, and a refusal is not, so a repaired file is read next
+ * time. */
+export function resolveMachineIdentity(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.homeDir ?? env.HOME ?? homedir();
+  const path = machineIdentityPath(env, home);
+  if (options.fsOps === undefined && resolved.has(path)) return resolved.get(path);
+  const pending = readOrPublish(path, {
+    ...DEFAULT_FS_OPERATIONS,
+    ...(options.fsOps ?? {}),
+  }, options.createIdentity ?? randomUUID);
+  if (options.fsOps === undefined) {
+    resolved.set(path, pending);
+    pending.catch(() => resolved.delete(path));
+  }
+  return pending;
+}
+
+async function readOrPublish(path, fs, createIdentity) {
+  const directory = dirname(path);
+  await prepareDirectory(directory, path, fs);
+  for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt += 1) {
+    const existing = await readIdentity(path, fs);
+    if (existing !== undefined) return existing;
+    await publish(path, directory, fs, createIdentity);
+  }
+  throw new MachineIdentityUnavailableError(path, 'the identity could not be published');
+}
+
+async function prepareDirectory(directory, path, fs) {
+  let stat;
+  try {
+    stat = await fs.lstat(directory);
+  } catch (cause) {
+    if (cause?.code !== 'ENOENT') {
+      throw new MachineIdentityUnavailableError(path, `its directory cannot be read: ${errorMessage(cause)}`);
+    }
+    try {
+      await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+      await fs.chmod(directory, 0o700);
+      stat = await fs.lstat(directory);
+    } catch (creation) {
+      throw new MachineIdentityUnavailableError(path, `its directory cannot be created: ${errorMessage(creation)}`);
+    }
+  }
+  try {
+    await tightenPrivateEntry(directory, stat, true, fs, 'machine identity directory');
+  } catch (cause) {
+    throw new MachineIdentityUnavailableError(path, errorMessage(cause));
+  }
+}
+
+async function readIdentity(path, fs) {
+  let before;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      before = await fs.lstat(path);
+    } catch (cause) {
+      if (cause?.code === 'ENOENT') return undefined;
+      throw new MachineIdentityUnavailableError(path, `it cannot be read: ${errorMessage(cause)}`);
+    }
+    if (
+      before.nlink <= 1 ||
+      before.isSymbolicLink() ||
+      !before.isFile() ||
+      attempt >= LINK_SETTLE_ATTEMPTS
+    ) {
+      break;
+    }
+    await new Promise((settle) => setTimeout(settle, LINK_SETTLE_DELAY_MS));
+  }
+  let current;
+  try {
+    current = await tightenPrivateEntry(path, before, false, fs, 'machine identity file');
+  } catch (cause) {
+    throw new MachineIdentityUnavailableError(path, errorMessage(cause));
+  }
+  let text;
+  const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || !sameFileIdentity(current, opened)) {
+      throw new MachineIdentityUnavailableError(path, 'it changed while being read');
+    }
+    text = new TextDecoder('utf-8', { fatal: true }).decode(await handle.readFile());
+  } catch (cause) {
+    if (cause instanceof MachineIdentityUnavailableError) throw cause;
+    throw new MachineIdentityUnavailableError(path, `it cannot be read: ${errorMessage(cause)}`);
+  } finally {
+    await handle.close();
+  }
+  const value = text.endsWith('\n') ? text.slice(0, -1) : text;
+  if (!isMachineIdentity(value) || value.includes('\n')) {
+    throw new MachineIdentityUnavailableError(path, 'it does not hold one machine identity');
+  }
+  return value;
+}
+
+async function publish(path, directory, fs, createIdentity) {
+  const uuid = createIdentity();
+  const value = `${MACHINE_IDENTITY_TAG_PREFIX}${uuid}`;
+  if (!isMachineIdentity(value)) {
+    throw new MachineIdentityUnavailableError(path, 'the identity generator returned an invalid value');
+  }
+  const temporary = join(directory, `.${IDENTITY_FILE}.${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await fs.open(temporary, 'wx', 0o600);
+    await handle.chmod(0o600);
+    await handle.writeFile(`${value}\n`, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    try {
+      await fs.link(temporary, path);
+    } catch (cause) {
+      // Another creator published first; its complete file is read next.
+      if (cause?.code === 'EEXIST') return;
+      throw cause;
+    }
+    await fs.unlink(temporary);
+    await syncDirectory(directory, fs);
+  } catch (cause) {
+    throw new MachineIdentityUnavailableError(path, `it cannot be published: ${errorMessage(cause)}`);
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+      // The publication failure stands.
+    }
+    try {
+      await fs.unlink(temporary);
+    } catch {
+      // A temporary already gone leaves nothing to remove.
+    }
+  }
+}

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

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// The one verified tighten-only rule for private entries (session-storage-1):
+// an entry qualifies only as current-user-owned and non-symlink — a file
+// also as a single-link regular file — with its owner bits present; a
+// qualifying entry with excess permissions is restricted through an opened
+// handle whose identity is compared before and after, so a link swapped in
+// between check and use cannot be tightened in its place. The session store
+// applies it to the sessions directory and its files; the machine identity
+// applies it to its state directory and file (playbook-cli-97).
+
+import { constants } from 'node:fs';
+
+export function sameFileIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+export function verifyPrivateEntry(stat, directory, label, uid = process.getuid?.()) {
+  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
+  ) {
+    throw new Error(`${label} refuses unsafe ownership, links, type, or owner access`);
+  }
+}
+
+export async function tightenPrivateEntry(path, before, directory, fs, label) {
+  const uid = process.getuid?.();
+  verifyPrivateEntry(before, directory, label, uid);
+  const handle = await fs.open(
+    path,
+    constants.O_RDONLY |
+      (constants.O_NOFOLLOW ?? 0) |
+      (constants.O_NONBLOCK ?? 0) |
+      (directory ? constants.O_DIRECTORY ?? 0 : 0),
+  );
+  try {
+    const opened = await handle.stat();
+    verifyPrivateEntry(opened, directory, label, uid);
+    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);
+    const after = await handle.stat();
+    verifyPrivateEntry(after, directory, label, uid);
+    const current = await fs.lstat(path);
+    verifyPrivateEntry(current, directory, label, uid);
+    if (
+      !sameFileIdentity(after, current) ||
+      (after.mode & 0o7777) !== mode ||
+      (current.mode & 0o7777) !== mode
+    ) {
+      throw new Error(`${label}: permission tightening could not be verified`);
+    }
+    return current;
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function syncDirectory(path, fs) {
+  let directory;
+  try {
+    directory = await fs.open(path, 'r');
+    await directory.sync();
+  } finally {
+    await directory?.close();
+  }
+}

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

@@ -26,6 +26,12 @@ import {
   snapshotJsonValue,
 } from '../../../../src/xstate-runtime.js';
 import { applyEffectLedgerCommands } from './session-store.js';
+import {
+  classifyOwnerMachine,
+  describeOwnerMachine,
+  isMachineIdentity,
+  resolveMachineIdentity,
+} from './machine-identity.js';
 
 const CLAIM_SCHEMA = 1;
 const CLAIM_OWNER_FILE = 'owner.json';
@@ -1321,13 +1327,35 @@ function validateCohort(options) {
 }
 
 export function createRepositoryEffectCoordinator(options = {}) {
-  const currentHostname = options.hostname ?? systemHostname();
+  // DR-087: the claim owner's `hostname` carries this machine's identity,
+  // read once at the first claim; an explicit value stands in for it
+  // (tests). An untagged owner is a legacy host name compared with the
+  // current one — or with an explicit untagged value, which then names
+  // this machine both ways.
+  const explicitHostname = options.hostname;
+  const legacyHostname =
+    options.legacyHostname ??
+    (typeof explicitHostname === 'string' && !isMachineIdentity(explicitHostname)
+      ? explicitHostname
+      : systemHostname());
+  let currentIdentityPending;
+  const currentIdentity = () =>
+    (currentIdentityPending ??=
+      explicitHostname !== undefined
+        ? Promise.resolve(explicitHostname)
+        : resolveMachineIdentity({
+            ...(options.env !== undefined ? { env: options.env } : {}),
+            ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+          }));
   const currentPid = options.pid ?? process.pid;
   const pollIntervalMs = options.pollIntervalMs ?? 10;
   const probeProcess = options.probeProcess ?? defaultProbeProcess;
   const createOwnerToken = options.createOwnerToken ?? randomUUID;
   const afterClaimPublished = options._testAfterClaimPublished;
-  if (typeof currentHostname !== 'string' || currentHostname.length === 0) {
+  if (
+    explicitHostname !== undefined &&
+    (typeof explicitHostname !== 'string' || explicitHostname.length === 0)
+  ) {
     throw new TypeError('repository coordinator hostname must be nonempty');
   }
   if (!Number.isSafeInteger(currentPid) || currentPid <= 0) {
@@ -1426,7 +1454,7 @@ export function createRepositoryEffectCoordinator(options = {}) {
       schema: CLAIM_SCHEMA,
       ownerToken,
       pid: currentPid,
-      hostname: currentHostname,
+      hostname: await currentIdentity(),
     });
 
     // A directory that is not a repository yet has no `.git` to publish a
@@ -1468,9 +1496,15 @@ export function createRepositoryEffectCoordinator(options = {}) {
         if (activeOwner.ownerToken === owner.ownerToken) {
           throw new Error('repository claim owner token was reused');
         }
-        if (activeOwner.hostname !== currentHostname) {
+        const machine = classifyOwnerMachine(activeOwner.hostname, owner.hostname, legacyHostname);
+        if (machine === 'foreign') {
+          throw new Error(
+            `repository claim is owned by ${describeOwnerMachine(activeOwner.hostname)}`,
+          );
+        }
+        if (machine !== 'local') {
           throw new Error(
-            `repository claim is owned by foreign host ${JSON.stringify(activeOwner.hostname)}`,
+            `repository claim owner machine ${JSON.stringify(activeOwner.hostname)} cannot be verified`,
           );
         }
         const state = await probeProcess(activeOwner.pid);

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

@@ -44,6 +44,13 @@ import {
   assertPlaybookCaptainShellSnapshot,
   assertPlaybookCaptainUnresolvedEffects,
 } from '../playbook-captain.js';
+import {
+  classifyOwnerMachine,
+  describeOwnerMachine,
+  isMachineIdentity,
+  resolveMachineIdentity,
+} from './machine-identity.js';
+import { sameFileIdentity, syncDirectory, tightenPrivateEntry } from './private-paths.js';
 
 export const CAPTAIN_SESSION_RECORD_SCHEMA_VERSION = 6;
 export const CAPTAIN_SESSION_RECORD_KIND = 'captain-session';
@@ -211,7 +218,7 @@ class CaptainSessionLeaseActiveError extends Error {
 
 function foreignCaptainSessionLeaseActiveError(sessionId, hostname) {
   const error = new Error(
-    `Captain session ${JSON.stringify(sessionId)} lease is owned by foreign host ${JSON.stringify(hostname)}`,
+    `Captain session ${JSON.stringify(sessionId)} lease is owned by ${describeOwnerMachine(hostname)}`,
   );
   error.code = PLAYBOOK_SESSION_LEASE_ACTIVE;
   error[ACTIVE_LEASE_ERROR] = true;
@@ -630,7 +637,25 @@ export function createCaptainSessionStore(options = {}) {
   const now = options.now ?? (() => new Date());
   const createTempId = options.createTempId ?? randomUUID;
   const createLeaseToken = options.createLeaseToken ?? randomUUID;
-  const localHostname = options.hostname ?? systemHostname();
+  // DR-087: the owner's `hostname` carries this machine's identity, read
+  // once at the first lease boundary; an explicit value stands in for it
+  // (tests, migration sub-stores). An untagged owner is a legacy host
+  // name, compared with the current one — or with an explicit untagged
+  // value, which then names this machine both ways.
+  const explicitHostname = options.hostname;
+  const legacyHostname =
+    options.legacyHostname ??
+    (typeof explicitHostname === 'string' && !isMachineIdentity(explicitHostname)
+      ? explicitHostname
+      : systemHostname());
+  let localIdentityPending;
+  const localIdentity = () =>
+    (localIdentityPending ??=
+      explicitHostname !== undefined
+        ? Promise.resolve(explicitHostname)
+        : options.resolveHostname !== undefined
+          ? options.resolveHostname()
+          : resolveMachineIdentity({ env, homeDir: home }));
   const localPid = options.pid ?? process.pid;
   const probeProcess =
     options.probeProcess ?? ((pid) => process.kill(pid, 0));
@@ -649,8 +674,9 @@ export function createCaptainSessionStore(options = {}) {
     throw new Error('Captain session store path must be absolute');
   }
   if (
-    typeof localHostname !== 'string' ||
-    localHostname.trim().length === 0
+    explicitHostname !== undefined &&
+    (typeof explicitHostname !== 'string' ||
+      explicitHostname.trim().length === 0)
   ) {
     throw new Error('Captain session lease hostname must be a non-empty string');
   }
@@ -1242,7 +1268,7 @@ export function createCaptainSessionStore(options = {}) {
     } catch (cause) { return cause?.code === 'ENOENT' ? 'idle' : 'unknown'; }
     try {
       const owner = await readLeaseOwner(sessionId);
-      if (owner.hostname !== localHostname) return 'unknown';
+      if (classifyOwnerMachine(owner.hostname, await localIdentity(), legacyHostname) !== 'local') return 'unknown';
       let state = 'active';
       try { await probeProcess(owner.pid); }
       catch (cause) {
@@ -1255,12 +1281,18 @@ export function createCaptainSessionStore(options = {}) {
   };
 
   const activeLeaseErrorFor = async (sessionId, owner) => {
-    if (owner.hostname !== localHostname) {
+    const machine = classifyOwnerMachine(owner.hostname, await localIdentity(), legacyHostname);
+    if (machine === 'foreign') {
       return foreignCaptainSessionLeaseActiveError(
         sessionId,
         owner.hostname,
       );
     }
+    if (machine !== 'local') {
+      throw new Error(
+        `Captain session ${JSON.stringify(sessionId)} lease owner machine ${JSON.stringify(owner.hostname)} cannot be verified`,
+      );
+    }
     try {
       await probeProcess(owner.pid);
       return new CaptainSessionLeaseActiveError(sessionId, owner.pid);
@@ -1350,7 +1382,7 @@ export function createCaptainSessionStore(options = {}) {
       sessionId,
       ownerToken,
       pid: localPid,
-      hostname: localHostname,
+      hostname: await localIdentity(),
       acquiredAt: timestampFrom(now(), 'lease timestamp'),
     });
     let handle;
@@ -1596,7 +1628,7 @@ export function createCaptainSessionStore(options = {}) {
     let sourceLease, lease;
     try {
       if (external) {
-        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env, homeDir: home, fsOps: fs, hostname: localHostname, pid: localPid, probeProcess });
+        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env, homeDir: home, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
         sourceLease = await sourceStore.acquireManagement(sessionId);
       }
       lease = await acquire(sessionId, true);
@@ -1722,7 +1754,7 @@ export function createCaptainSessionStore(options = {}) {
     const sourceDir = join(sourceEnv.XDG_STATE_HOME || join(sourceHome, '.local', 'state'), 'playbook', 'sessions');
     const result = { sourceDir, migrated: [], skipped: [] };
     if (sourceDir === sessionsDir) return result;
-    const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env: sourceEnv, homeDir: sourceHome, fsOps: fs, hostname: localHostname, pid: localPid, probeProcess });
+    const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env: sourceEnv, homeDir: sourceHome, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
     await sourceStore.prepare();
     try { await assertPrivateDirectory(sourceDir, fs); }
     catch (cause) { if (cause?.code === 'ENOENT') return result; throw cause; }
@@ -2444,9 +2476,6 @@ function replayFileIdentity(stat) {
   return Object.freeze({ dev: stat.dev, ino: stat.ino });
 }
 
-function sameFileIdentity(left, right) {
-  return left.dev === right.dev && left.ino === right.ino;
-}
 
 function sameReplayIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino;
@@ -6676,15 +6705,6 @@ async function assertPathMissing(path, fs, message) {
   throw new Error(message);
 }
 
-async function syncDirectory(path, fs) {
-  let directory;
-  try {
-    directory = await fs.open(path, 'r');
-    await directory.sync();
-  } finally {
-    await directory?.close();
-  }
-}
 
 async function ensurePrivateDirectory(path, fs) {
   try {
@@ -6755,24 +6775,9 @@ async function prepareSessionPermissions(sessionsDir, fs, selectedSessionId, inc
   let initial;
   try { initial = await fs.lstat(sessionsDir); }
   catch (cause) { if (cause?.code === 'ENOENT') return; throw cause; }
-  const uid = process.getuid?.();
-  const verify = (stat, directory) => {
-    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) throw new Error('session permission preparation refuses unsafe ownership, links, type, or owner access');
-  };
-  const tighten = async (path, before, directory) => {
-    verify(before, directory);
-    const handle = await fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0) | (directory ? constants.O_DIRECTORY ?? 0 : 0));
-    try {
-      const opened = await handle.stat(); verify(opened, directory);
-      if (!sameFileIdentity(before, opened)) throw new Error('session entry changed during permission preparation');
-      const mode = directory ? 0o700 : 0o600;
-      if ((opened.mode & 0o7777) !== mode) await handle.chmod(mode);
-      const after = await handle.stat(); verify(after, directory);
-      const current = await fs.lstat(path); verify(current, directory);
-      if (!sameFileIdentity(after, current) || (after.mode & 0o7777) !== mode || (current.mode & 0o7777) !== mode) throw new Error('session permission tightening could not be verified');
-    } finally { await handle.close(); }
-  };
+  // The one verified tighten-only rule, shared with the machine identity
+  // (session-storage-1, playbook-cli-97).
+  const tighten = (path, before, directory) => tightenPrivateEntry(path, before, directory, fs, 'session permission preparation');
   await tighten(sessionsDir, initial, true);
   for (const name of await fs.readdir(sessionsDir)) {
     const eligible = /^[0-9a-f-]{36}\.(?:json|records\.jsonl|hints\.json)$/.test(name)

package/reference/sdlc/code.playbook/machine-identity.d.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export declare const MACHINE_IDENTITY_TAG_PREFIX: 'machine-id:v1:';
+export declare function isMachineIdentity(value: unknown): value is string;
+export declare function machineIdentityPath(env?: NodeJS.ProcessEnv, home?: string): string;
+export interface ResolveMachineIdentityOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly homeDir?: string;
+}
+export declare function resolveMachineIdentity(options?: ResolveMachineIdentityOptions): Promise<string>;

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

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// DR-087: the public `@sublang/playbook/machine-identity` facade. Every
+// member is the CLI host's own identity implementation; this module only
+// narrows the accepted arguments to the declared surface (playbook-cli-98).
+
+import {
+  MACHINE_IDENTITY_TAG_PREFIX,
+  isMachineIdentity,
+  machineIdentityPath,
+  resolveMachineIdentity as resolve,
+} from './bin/machine-identity.js';
+
+export { MACHINE_IDENTITY_TAG_PREFIX, isMachineIdentity, machineIdentityPath };
+
+export function resolveMachineIdentity(options = {}) {
+  return resolve({
+    ...(options.env !== undefined ? { env: options.env } : {}),
+    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+  });
+}