@sublang/playbook 17.6.0 → 17.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.6.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",

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

@@ -112,6 +112,24 @@ export function resolveMachineIdentity(options = {}) {
   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);

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

@@ -30,6 +30,7 @@ import {
   classifyOwnerMachine,
   describeOwnerMachine,
   isMachineIdentity,
+  lazyMachineIdentity,
   resolveMachineIdentity,
 } from './machine-identity.js';
 
@@ -1328,8 +1329,9 @@ function validateCohort(options) {
 
 export function createRepositoryEffectCoordinator(options = {}) {
   // 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
+  // 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;
@@ -1338,15 +1340,13 @@ export function createRepositoryEffectCoordinator(options = {}) {
     (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 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;

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';
@@ -48,6 +48,7 @@ import {
   classifyOwnerMachine,
   describeOwnerMachine,
   isMachineIdentity,
+  lazyMachineIdentity,
   resolveMachineIdentity,
 } from './machine-identity.js';
 import { sameFileIdentity, syncDirectory, tightenPrivateEntry } from './private-paths.js';
@@ -638,41 +639,50 @@ export function createCaptainSessionStore(options = {}) {
   const createTempId = options.createTempId ?? randomUUID;
   const createLeaseToken = options.createLeaseToken ?? randomUUID;
   // 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.
+  // 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());
-  let localIdentityPending;
-  const localIdentity = () =>
-    (localIdentityPending ??=
-      explicitHostname !== undefined
-        ? Promise.resolve(explicitHostname)
-        : options.resolveHostname !== undefined
-          ? options.resolveHostname()
-          : resolveMachineIdentity({ env, homeDir: home }));
+  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 (
     explicitHostname !== undefined &&
     (typeof explicitHostname !== 'string' ||
@@ -1101,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(
@@ -1358,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);
@@ -1625,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, resolveHostname: localIdentity, legacyHostname, 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);
@@ -1719,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));
@@ -1743,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`);
     }
   };
 
@@ -1754,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, resolveHostname: localIdentity, legacyHostname, 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; }
@@ -1778,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) => {
@@ -6706,7 +6721,7 @@ async function assertPathMissing(path, fs, message) {
 }
 
 
-async function ensurePrivateDirectory(path, fs) {
+async function ensurePrivateDirectory(path, fs, mayCreate = () => true) {
   try {
     await assertPrivateDirectory(path, fs);
     return;
@@ -6728,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 {
@@ -6750,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) {

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({