@sublang/playbook 17.5.0 → 17.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.5.0",
+  "version": "17.7.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,251 @@
+// 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;
+}
+
+/** One store's or coordinator's lazy resolution (playbook-cli-97): the
+ * first identity it resolves is kept for its lifetime, and a refusal is
+ * not, so its next lease or claim resolves again once the file is
+ * repaired. */
+export function lazyMachineIdentity(resolve) {
+  let pending;
+  return () => {
+    if (pending === undefined) {
+      const attempt = Promise.resolve(resolve());
+      pending = attempt;
+      attempt.catch(() => {
+        if (pending === attempt) pending = undefined;
+      });
+    }
+    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,13 @@ import {
   snapshotJsonValue,
 } from '../../../../src/xstate-runtime.js';
 import { applyEffectLedgerCommands } from './session-store.js';
+import {
+  classifyOwnerMachine,
+  describeOwnerMachine,
+  isMachineIdentity,
+  lazyMachineIdentity,
+  resolveMachineIdentity,
+} from './machine-identity.js';
 
 const CLAIM_SCHEMA = 1;
 const CLAIM_OWNER_FILE = 'owner.json';
@@ -1321,13 +1328,34 @@ 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 at the first claim and kept once read, while a refusal is read
+  // again at the next (playbook-cli-97); 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());
+  const currentIdentity = lazyMachineIdentity(() =>
+    explicitHostname !== undefined
+      ? 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

@@ -28,7 +28,7 @@ import {
   unlink,
 } from 'node:fs/promises';
 import { homedir, hostname as systemHostname } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { 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';
@@ -44,6 +44,14 @@ import {
   assertPlaybookCaptainShellSnapshot,
   assertPlaybookCaptainUnresolvedEffects,
 } from '../playbook-captain.js';
+import {
+  classifyOwnerMachine,
+  describeOwnerMachine,
+  isMachineIdentity,
+  lazyMachineIdentity,
+  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 +219,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,27 +638,55 @@ 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
+  // at the first lease boundary and kept once read, while a refusal is
+  // read again at the next (playbook-cli-97); 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());
+  const localIdentity = lazyMachineIdentity(() =>
+    explicitHostname !== undefined
+      ? 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));
   const fs = { ...DEFAULT_FS_OPERATIONS, ...(options.fsOps ?? {}) };
+  // session-storage-11: a host that prepared the directory may forbid
+  // creating it or an ancestor, so a directory that moves or vanishes
+  // mid-operation is refused rather than recreated at its former path.
+  const createSessionsDir =
+    options.createSessionsDir === undefined ? true : options.createSessionsDir;
+  const mayCreateDirectory = (directory) =>
+    createSessionsDir || !isPathOrAncestor(directory, sessionsDir);
   const replayReadCursors = new Map();
   const replayReadQueues = new Map();
   const portableWriters = new Map();
   const assetStores = new Map();
   const assetStoreFor = (sessionId) => {
     assertSessionId(sessionId);
-    if (!assetStores.has(sessionId)) assetStores.set(sessionId, createAssetStore({ directory: join(sessionsDir, `${sessionId}.assets`), ...(options.maxAssetBytes === undefined ? {} : { maxAssetBytes: options.maxAssetBytes }) }));
+    if (!assetStores.has(sessionId)) assetStores.set(sessionId, createAssetStore({ directory: join(sessionsDir, `${sessionId}.assets`), createAncestors: createSessionsDir, ...(options.maxAssetBytes === undefined ? {} : { maxAssetBytes: options.maxAssetBytes }) }));
     return assetStores.get(sessionId);
   };
 
   if (!isAbsolute(sessionsDir)) {
     throw new Error('Captain session store path must be absolute');
   }
+  if (typeof createSessionsDir !== 'boolean') {
+    throw new TypeError('Captain session store createSessionsDir must be a boolean');
+  }
   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');
   }
@@ -1075,7 +1111,7 @@ export function createCaptainSessionStore(options = {}) {
       : await portableWriters.get(recordValue.sessionId)?.checkpoint(recordValue);
     if (record === undefined) throw new Error('session persistence requires its owning lifecycle');
     const destination = recordPathFor(record.sessionId);
-    await ensurePrivateDirectory(sessionsDir, fs);
+    await ensurePrivateDirectory(sessionsDir, fs, mayCreateDirectory);
 
     if (noReplace) {
       await assertPathMissing(
@@ -1242,7 +1278,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 +1291,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);
@@ -1326,7 +1368,7 @@ export function createCaptainSessionStore(options = {}) {
   };
 
   const makeLeaseStage = async (sessionId) => {
-    await ensurePrivateDirectory(sessionsDir, fs);
+    await ensurePrivateDirectory(sessionsDir, fs, mayCreateDirectory);
     const ownerToken = createLeaseToken();
     assertUuid(ownerToken, 'Captain session lease owner token');
     const retiredPath = retiredPathFor(sessionId, ownerToken);
@@ -1350,7 +1392,7 @@ export function createCaptainSessionStore(options = {}) {
       sessionId,
       ownerToken,
       pid: localPid,
-      hostname: localHostname,
+      hostname: await localIdentity(),
       acquiredAt: timestampFrom(now(), 'lease timestamp'),
     });
     let handle;
@@ -1593,10 +1635,10 @@ export function createCaptainSessionStore(options = {}) {
     // the lease below; a preflight read never authorizes migration writes.
     try { decodeSource(await readPrivateRegularFile(sourcePath, 0o600, fs, 'migration source')); }
     catch (cause) { if (cause?.code !== 'ENOENT' || !sidecar && !external) throw cause; }
-    let sourceLease, lease;
+    let sourceLease, lease, failure;
     try {
       if (external) {
-        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, env, homeDir: home, fsOps: fs, hostname: localHostname, pid: localPid, probeProcess });
+        const sourceStore = createCaptainSessionStore({ sessionsDir: sourceDir, createSessionsDir, env, homeDir: home, fsOps: fs, resolveHostname: localIdentity, legacyHostname, pid: localPid, probeProcess });
         sourceLease = await sourceStore.acquireManagement(sessionId);
       }
       lease = await acquire(sessionId, true);
@@ -1687,7 +1729,7 @@ export function createCaptainSessionStore(options = {}) {
           if (existing !== `${JSON.stringify(manifest)}\n`) throw new Error('migration destination manifest diverged');
         } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
       }
-      await ensurePrivateDirectory(inputsDir, fs);
+      await ensurePrivateDirectory(inputsDir, fs, mayCreateDirectory);
       const inputs = [{ path: sourcePath, bytes: Buffer.from(sourceBytes, 'utf8') }, ...(originalReplay === undefined ? [] : [{ path: sourceReplayPath, bytes: originalReplay }])];
       for (const [index, input] of inputs.entries()) {
         const path = join(inputsDir, String(index));
@@ -1711,8 +1753,11 @@ export function createCaptainSessionStore(options = {}) {
       if (sidecar || external) { await fs.unlink(sourcePath); await syncDirectory(sourceDir, fs); }
       await writePrivateJson(receiptPath, { ...receipt, complete: true }, fs);
       return { manifest, migrated: true, reasons: [] };
+    } catch (cause) {
+      failure = { cause };
+      throw cause;
     } finally {
-      try { await lease?.release(); } finally { await sourceLease?.release(); }
+      await releaseInOrder([lease, sourceLease], failure, `cannot migrate Captain session ${JSON.stringify(sessionId)} without leaving ownership uncertain`);
     }
   };
 
@@ -1722,7 +1767,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, createSessionsDir, 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; }
@@ -1746,8 +1791,10 @@ export function createCaptainSessionStore(options = {}) {
 
   const remove = async (sessionId) => {
     const lease = await acquire(sessionId, true);
+    let failure;
     try { await lease.assertOwner(); await deleteRecord(sessionId); }
-    finally { await lease.release(); }
+    catch (cause) { failure = { cause }; throw cause; }
+    finally { await releaseInOrder([lease], failure, `cannot delete Captain session ${JSON.stringify(sessionId)} without leaving ownership uncertain`); }
   };
 
   const exportBundle = async (sessionId) => {
@@ -2444,9 +2491,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,17 +6720,8 @@ 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) {
+async function ensurePrivateDirectory(path, fs, mayCreate = () => true) {
   try {
     await assertPrivateDirectory(path, fs);
     return;
@@ -6708,6 +6743,15 @@ async function ensurePrivateDirectory(path, fs) {
       cursor = parent;
     }
   }
+  // Refuse before creating anything, so a forbidden ancestor is never
+  // recreated beneath a permitted descendant (session-storage-11).
+  const forbidden = missing.find((directory) => !mayCreate(directory));
+  if (forbidden !== undefined) {
+    throw Object.assign(
+      new Error(`Captain session store directory ${JSON.stringify(forbidden)} is missing and this store may not create it`),
+      { code: 'ENOENT' },
+    );
+  }
   for (const directory of missing.reverse()) {
     let created = false;
     try {
@@ -6730,6 +6774,32 @@ async function ensurePrivateDirectory(path, fs) {
   await assertPrivateDirectory(path, fs);
 }
 
+// Releases every acquired lease in order. Without an earlier failure the
+// last release error propagates, as nested try/finally releases would; a
+// release error never hides the failure that preceded it.
+async function releaseInOrder(leases, failure, message) {
+  const errors = [];
+  for (const lease of leases) {
+    try {
+      await lease?.release();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 0) return;
+  if (failure === undefined) throw errors.at(-1);
+  throw new AggregateError([failure.cause, ...errors], message);
+}
+
+function isPathOrAncestor(directory, path) {
+  const fromDirectory = relative(directory, path);
+  return fromDirectory === '' || (
+    fromDirectory !== '..' &&
+    !fromDirectory.startsWith(`..${sep}`) &&
+    !isAbsolute(fromDirectory)
+  );
+}
+
 async function assertPrivateDirectory(path, fs) {
   const stat = await assertDirectoryNotLink(path, fs);
   if ((stat.mode & 0o7777) !== 0o700) {
@@ -6755,24 +6825,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 } : {}),
+  });
+}

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

@@ -87,9 +87,15 @@ export function createAssetStore(options) {
   const directory = resolve(options.directory);
   const maxAssetBytes = options.maxAssetBytes ?? DEFAULT_MAX_ASSET_BYTES;
   if (!Number.isSafeInteger(maxAssetBytes) || maxAssetBytes <= 0) throw new TypeError('maximum asset bytes must be a positive safe integer');
+  // A session store forbidding creation of its sessions directory creates
+  // only this leaf inside it (session-storage-11).
+  const createAncestors = options.createAncestors ?? true;
   let importTail = Promise.resolve();
   const ensureDirectory = async (create) => {
-    if (create) await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (create) {
+      try { await mkdir(directory, { recursive: createAncestors, mode: 0o700 }); }
+      catch (error) { if (createAncestors || error.code !== 'EEXIST') throw error; }
+    }
     assertDirectory(await lstat(directory));
   };
   const prepare = async () => {

package/reference/sdlc/code.playbook/session-store.d.ts

@@ -285,7 +285,19 @@ export interface SharedSessionStore {
   migrateLegacyDefault(options?: { env?: Readonly<Record<string, string | undefined>>; homeDir?: string }): Promise<{ sourceDir: string; migrated: readonly string[]; skipped: readonly { sessionId: string; reason: string }[] }>;
   migrate(sessionId: string, options?: { sourcePath?: string; cwd?: string; backupDir?: string }): Promise<{ manifest: SessionManifest; migrated: boolean; reasons: readonly string[] }>;
 }
-export declare function createSessionStore(options?: { maxAssetBytes?: number; sessionsDir?: string; env?: Readonly<Record<string, string | undefined>>; homeDir?: string; [key: string]: any }): SharedSessionStore;
+export declare function createSessionStore(options?: {
+  maxAssetBytes?: number;
+  sessionsDir?: string;
+  /**
+   * Default `true`. `false` refuses, rather than creates, a missing sessions directory or ancestor when preparing
+   * session payload, lease, asset or migration directories. Machine-identity provisioning keeps its own rule and may
+   * still create its directory, including an ancestor it shares with the sessions directory.
+   */
+  createSessionsDir?: boolean;
+  env?: Readonly<Record<string, string | undefined>>;
+  homeDir?: string;
+  [key: string]: any;
+}): SharedSessionStore;
 export declare function validateSessionManifest(value: unknown): SessionManifest;
 export declare function validateSessionContext(value: unknown): SessionContext;
 export declare function projectCaptainSessionStructure(value: SessionExecutionProjection): SessionStructuralProjection;

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

@@ -21,9 +21,19 @@ export function openSessionStore(sessionsDir) {
 }
 
 function wrapStore(store) {
+  // Preparation is kept once it succeeds; a refusal is not, so the next
+  // operation prepares again once the directory is repaired
+  // (session-storage-1).
   let preparation;
   const prepared = async (operation) => {
-    await (preparation ??= store.prepare());
+    if (preparation === undefined) {
+      const attempt = store.prepare();
+      preparation = attempt;
+      attempt.catch(() => {
+        if (preparation === attempt) preparation = undefined;
+      });
+    }
+    await preparation;
     return operation();
   };
   return Object.freeze({