@sublang/playbook 8.0.0 → 10.0.0

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

@@ -8,7 +8,7 @@
 
 import { randomUUID } from 'node:crypto';
 import { constants, realpathSync } from 'node:fs';
-import { lstat, open, readFile, realpath, unlink } from 'node:fs/promises';
+import { lstat, open, realpath, unlink } from 'node:fs/promises';
 import {
   basename,
   dirname,
@@ -30,6 +30,8 @@ import {
   CaptainSessionHostCleanupError,
   captainOptionsFromConfig,
   createCaptainSessionHost,
+  installRetainedGenerationsForLaunch,
+  reportSkippedCaptainSession,
   validateFrozenExecutionConfig,
 } from './run.js';
 import { prepareConfiguredRegistries } from './provision.js';
@@ -47,6 +49,8 @@ export const MANAGED_INTERACTIVE_PAYLOAD_FILE =
 export const MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION = 1;
 export const MANAGED_INTERACTIVE_PAYLOAD_KIND =
   'playbook-managed-interactive-launch';
+export const MANAGED_INTERACTIVE_READINESS_WITNESS_FILE =
+  'playbook-managed-readiness';
 
 const PAYLOAD_KEYS = [
   'schemaVersion',
@@ -156,6 +160,18 @@ export async function writeManagedInteractivePayload(workDir, value) {
   return path;
 }
 
+export async function publishManagedInteractiveReadinessWitness(
+  workDir,
+  sessionId,
+) {
+  return writeManagedInteractiveReadinessClaim({
+    workDir,
+    sessionId,
+    claim: 'ready',
+    rejectExisting: true,
+  });
+}
+
 export async function readManagedInteractivePayload(path) {
   assertCanonicalAbsolutePath(path, 'managed interactive launch descriptor');
   assertManagedDescriptorPath(path);
@@ -300,6 +316,7 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
   let leaseQuarantined = false;
   let activeTurn;
   let executionProjection;
+  let freshLaunchRecord;
 
   const release = async () => {
     if (released || lease === undefined) return;
@@ -309,6 +326,30 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
     released = true;
   };
 
+  const abandonFreshLaunchRecord = async ({ claim = false } = {}) => {
+    const record = freshLaunchRecord;
+    if (
+      record === undefined ||
+      lease === undefined ||
+      Object.keys(record.retainedGenerations ?? {}).length !== 0
+    ) {
+      return;
+    }
+    if (
+      claim &&
+      !(await writeManagedInteractiveReadinessClaim({
+        workDir: payload.workDir,
+        sessionId: payload.sessionId,
+        claim: 'abandon',
+        rejectExisting: false,
+      }))
+    ) {
+      return;
+    }
+    freshLaunchRecord = undefined;
+    await lease.abandonFreshSettled({ expected: record });
+  };
+
   return Object.freeze({
     async initializeRuntime(context) {
       if (initialized || lease !== undefined || released) {
@@ -328,7 +369,11 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
       let host;
       try {
         lease = await store.acquire(payload.sessionId);
-        const authoritative = await lease.read();
+        const authoritative =
+          typeof lease.recoverUnresolvedEffectAbandonment === 'function'
+            ? await lease.recoverUnresolvedEffectAbandonment()
+            : await lease.read();
+        let retainedGenerations = {};
         let restoreSnapshot;
         const prepareRegistryModule =
           options.prepareRegistryModule ??
@@ -381,12 +426,14 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
             { loadModule, prepareRegistryModule },
           );
           restoreSnapshot = record.snapshot;
+          retainedGenerations = record.retainedGenerations ?? {};
         }
 
         const created = await createSessionHost({
           config: executionProjection,
           sessionId: payload.sessionId,
           cwd: payload.cwd,
+          sessionLease: lease,
           loadModule,
           observers: context.observers,
           ...(options.adapterImports
@@ -401,18 +448,49 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
           ...(options.createHostRuntime
             ? { createHostRuntime: options.createHostRuntime }
             : {}),
+          ...(options.createEffectLedgerWriteAhead
+            ? {
+                createEffectLedgerWriteAhead:
+                  options.createEffectLedgerWriteAhead,
+              }
+            : {}),
           ...(restoreSnapshot !== undefined ? { restoreSnapshot } : {}),
         });
         ({ host, shell } = created);
-        if (payload.mode === 'fresh') {
-          await lease.initializeSettled({
-            cwd: payload.cwd,
-            structuralProjection:
-              projectCaptainSessionStructure(executionProjection),
-            executionProjection,
-            snapshot: created.snapshot,
-          });
-        }
+        await installRetainedGenerationsForLaunch({
+          lease,
+          shell,
+          ...(payload.mode === 'fresh'
+            ? {
+                freshBoundary: {
+                  cwd: payload.cwd,
+                  structuralProjection:
+                    projectCaptainSessionStructure(executionProjection),
+                  executionProjection,
+                  snapshot: created.snapshot,
+                },
+                onFreshRecord(record) {
+                  freshLaunchRecord = record;
+                },
+                onLegacyRecord: (record) =>
+                  reportSkippedCaptainSession(
+                    options.stderr ?? process.stderr,
+                    'playbook',
+                    'legacy',
+                    record,
+                  ),
+                onInvalidRecord: (record) =>
+                  reportSkippedCaptainSession(
+                    options.stderr ?? process.stderr,
+                    'playbook',
+                    'invalid',
+                    record,
+                  ),
+              }
+            : {}),
+          retainedGenerations,
+          reconcileRepositoryEffects: created.reconcileRepositoryEffects,
+        });
         initialized = true;
         return {
           abortActiveTurn: (...args) => host.abortActiveTurn(...args),
@@ -445,6 +523,13 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
             failures.push(disposeError);
           }
         }
+        if (!leaseQuarantined) {
+          try {
+            await abandonFreshLaunchRecord();
+          } catch (abandonmentError) {
+            failures.push(abandonmentError);
+          }
+        }
         shell = undefined;
         if (!leaseQuarantined) {
           try {
@@ -503,25 +588,93 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
           `managed interactive Captain turn produced ${replies.length} usable Boss-visible replies; expected exactly one`,
         );
       }
-      const snapshot = shell?.exportSnapshot();
-      if (snapshot === undefined) {
+      const settlement = shell?.exportSettlement();
+      if (settlement === undefined) {
         throw new Error(
-          'managed interactive Captain turn settled without an exportable session snapshot',
+          'managed interactive Captain turn settled without an exportable session settlement',
         );
       }
-      await lease.settle({ attemptId: activeTurn.attemptId, snapshot });
+      await lease.settle({
+        attemptId: activeTurn.attemptId,
+        snapshot: settlement.snapshot,
+        unresolvedEffects: settlement.unresolvedEffects,
+        retentionUpdates: settlement.retentionUpdates,
+      });
       activeTurn = undefined;
     },
 
-    async shutdown() {
+    async shutdown(context) {
       // Cligent invokes lifecycle shutdown only after runtime disposal and the
       // complete turn transaction, so ownership retirement cannot race either.
       if (leaseQuarantined) return;
-      await release();
+      const failures = [];
+      if (context !== undefined) {
+        try {
+          await abandonFreshLaunchRecord({ claim: true });
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      try {
+        await release();
+      } catch (error) {
+        failures.push(error);
+      }
+      if (failures.length === 1) throw failures[0];
+      if (failures.length > 1) {
+        throw new AggregateError(
+          failures,
+          'managed interactive shutdown could not retract its unused fresh session and retire its lease',
+        );
+      }
     },
   });
 }
 
+async function writeManagedInteractiveReadinessClaim({
+  workDir,
+  sessionId,
+  claim,
+  rejectExisting,
+}) {
+  assertCanonicalAbsolutePath(
+    workDir,
+    'managed interactive readiness work directory',
+  );
+  assertUuid(sessionId, 'managed interactive readiness session id');
+  const path = join(workDir, MANAGED_INTERACTIVE_READINESS_WITNESS_FILE);
+  let handle;
+  try {
+    handle = await open(path, 'wx', 0o600);
+  } catch (cause) {
+    if (cause?.code === 'EEXIST' && !rejectExisting) return false;
+    throw new Error(
+      `managed interactive readiness claim could not be created: ${message(cause)}`,
+      { cause },
+    );
+  }
+  try {
+    await handle.chmod(0o600);
+    const stat = await handle.stat();
+    if (!stat.isFile() || (stat.mode & 0o7777) !== 0o600) {
+      throw new Error(
+        'managed interactive readiness claim is not a private regular file',
+      );
+    }
+    if (
+      typeof process.getuid === 'function' &&
+      stat.uid !== process.getuid()
+    ) {
+      throw new Error('managed interactive readiness claim has a foreign owner');
+    }
+    await handle.writeFile(`${claim} ${sessionId}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return true;
+}
+
 export function parseManagedInteractiveChildArgs(argv) {
   if (argv.length !== 1) {
     throw new Error(

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -37,6 +37,7 @@ const DEFAULT_TEMPLATE_PATH = resolve(
 export const PLAYBOOK_CAPTAIN_MODULE =
   '@sublang/playbook/playbook-captain';
 const PLAYBOOK_LAUNCHER_KEYS = ['from', 'command', 'roles'];
+const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
 const PLAYBOOK_TOP_LEVEL_KEYS = new Set([
   'captain',
   'players',
@@ -291,6 +292,7 @@ export async function normalizeSelectedLaunchPlanDataOnly(
     if (hasOwn(block, 'players')) {
       throw legacyPlayersError(`playbooks.${id}.players`, configPath);
     }
+    rejectConfiguredHostCapabilities(block, `playbooks.${id}`);
     if (
       typeof block.from !== 'string' ||
       block.from.trim().length === 0 ||
@@ -519,6 +521,19 @@ export function resolveAgent(value, path, reservedKeys = []) {
   throw new Error(`${path} must be an adapter shorthand or an agent block`);
 }
 
+function rejectConfiguredHostCapabilities(value, path) {
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    hasOwn(value, HOST_CAPABILITIES_OPTION_KEY)
+  ) {
+    throw new Error(
+      `${path}.${HOST_CAPABILITIES_OPTION_KEY} is host-owned and cannot be configured`,
+    );
+  }
+}
+
 // PBCLI-46: normalize into a detached, deeply frozen JSON plan. The plan has
 // only execution data and presentation data; imported registry functions are
 // consulted for validation and then discarded.
@@ -597,6 +612,7 @@ export async function normalizeLaunchPlan(
     if (hasOwn(block, 'players')) {
       throw legacyPlayersError(`playbooks.${id}.players`, configPath);
     }
+    rejectConfiguredHostCapabilities(block, `playbooks.${id}`);
     const from = block.from;
     if (
       typeof from !== 'string' ||
@@ -806,7 +822,7 @@ export async function normalizeLaunchPlan(
         `playbooks.${id}.from "${from}" failed to import: ${errorMessage(cause)}`,
       );
     }
-    const entry = mod?.default;
+    const entry = snapshotRegistryEntry(mod?.default);
     const registryProblem = invalidRegistryEntryReason(entry);
     if (registryProblem !== undefined) {
       throw new Error(
@@ -1252,7 +1268,26 @@ function assertNoRetiredProfiles(top, configPath) {
   }
 }
 
-function invalidRegistryEntryReason(value) {
+// Imported manifests remain live JavaScript objects. Capture every member this
+// host consumes once, then validate and project only the detached record so a
+// getter or later mutation cannot make those two phases observe different
+// compatibility declarations or identities.
+export function snapshotRegistryEntry(value) {
+  if (!isObject(value)) return value;
+  return {
+    id: value.id,
+    command: value.command,
+    intent: value.intent,
+    artifactSchema: value.artifactSchema,
+    runtimeProfile: value.runtimeProfile,
+    requiredRoleIds: value.requiredRoleIds,
+    concurrentRoleSets: value.concurrentRoleSets,
+    validateOptions: value.validateOptions,
+    createRuntime: value.createRuntime,
+  };
+}
+
+export function invalidRegistryEntryReason(value) {
   if (!isObject(value)) return 'the default export must be an object';
   if (
     typeof value.id !== 'string' ||
@@ -1269,9 +1304,14 @@ function invalidRegistryEntryReason(value) {
     return 'command must be a canonical trimmed nonblank string';
   }
   if (typeof value.intent !== 'string') return 'intent must be a string';
-  if (value.artifactSchema !== 2) {
-    return 'artifactSchema must be exactly 2';
+  if (value.artifactSchema !== 3) {
+    return 'artifactSchema must be 3';
   }
+  const runtimeProfileProblem = invalidRuntimeProfileReason(
+    value.runtimeProfile,
+    value.artifactSchema,
+  );
+  if (runtimeProfileProblem !== undefined) return runtimeProfileProblem;
   const roleProblem = invalidManifestRoles(value.requiredRoleIds);
   if (roleProblem !== undefined) return `requiredRoleIds ${roleProblem}`;
   const concurrentProblem = invalidConcurrentRoleSets(
@@ -1290,6 +1330,89 @@ function invalidRegistryEntryReason(value) {
   return undefined;
 }
 
+function invalidRuntimeProfileReason(value, advertisedArtifactSchema) {
+  if (!isPlainObject(value)) {
+    return 'runtimeProfile must be a plain object';
+  }
+  const kindDescriptor = Object.getOwnPropertyDescriptor(value, 'kind');
+  if (
+    kindDescriptor === undefined ||
+    kindDescriptor.get !== undefined ||
+    kindDescriptor.set !== undefined ||
+    kindDescriptor.enumerable !== true
+  ) {
+    return 'runtimeProfile.kind must be an enumerable data property';
+  }
+  const kind = kindDescriptor.value;
+  if (kind === 'shared-factory') {
+    const profile = exactPlainDataRecord(value, ['kind', 'compat']);
+    if (profile === undefined) {
+      return 'shared-factory runtimeProfile must contain exactly kind and compat data properties';
+    }
+    const compat = exactPlainDataRecord(profile.compat, [
+      'artifactSchema',
+      'runtimeAbi',
+    ]);
+    if (compat === undefined) {
+      return 'shared-factory runtimeProfile.compat must contain exactly artifactSchema and runtimeAbi data properties';
+    }
+    if (!Number.isSafeInteger(compat.artifactSchema)) {
+      return 'shared-factory runtimeProfile.compat.artifactSchema must be an integer';
+    }
+    if (!Number.isSafeInteger(compat.runtimeAbi)) {
+      return 'shared-factory runtimeProfile.compat.runtimeAbi must be an integer';
+    }
+    if (compat.artifactSchema !== advertisedArtifactSchema) {
+      return 'artifactSchema must match runtimeProfile.compat.artifactSchema';
+    }
+    return undefined;
+  }
+  if (kind === 'bespoke') {
+    const profile = exactPlainDataRecord(value, ['kind', 'artifactSchema']);
+    if (profile === undefined) {
+      return 'bespoke runtimeProfile must contain exactly kind and artifactSchema data properties';
+    }
+    if (!Number.isSafeInteger(profile.artifactSchema)) {
+      return 'bespoke runtimeProfile.artifactSchema must be an integer';
+    }
+    if (profile.artifactSchema !== advertisedArtifactSchema) {
+      return 'artifactSchema must match runtimeProfile.artifactSchema';
+    }
+    return undefined;
+  }
+  return 'runtimeProfile.kind must be shared-factory or bespoke';
+}
+
+function exactPlainDataRecord(value, expectedKeys) {
+  if (!isPlainObject(value)) return undefined;
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== expectedKeys.length ||
+    keys.some(
+      (key) => typeof key !== 'string' || !expectedKeys.includes(key),
+    )
+  ) {
+    return undefined;
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (
+    expectedKeys.some((key) => {
+      const descriptor = descriptors[key];
+      return (
+        descriptor === undefined ||
+        descriptor.get !== undefined ||
+        descriptor.set !== undefined ||
+        descriptor.enumerable !== true
+      );
+    })
+  ) {
+    return undefined;
+  }
+  return Object.fromEntries(
+    expectedKeys.map((key) => [key, descriptors[key].value]),
+  );
+}
+
 function validateStoredStructuralProjection(value) {
   const stored = cloneJson(value, 'stored structural projection');
   if (!isPlainObject(stored) || stored.schemaVersion !== 1) {
@@ -1340,6 +1463,15 @@ function validateStoredStructuralProjection(value) {
     ) {
       throw new Error(`stored structural catalog.${id} is malformed`);
     }
+    if (item.artifactSchema !== 3) {
+      throw new Error(
+        `stored structural catalog.${id}.artifactSchema must be 3`,
+      );
+    }
+    rejectConfiguredHostCapabilities(
+      item.options,
+      `stored structural catalog.${id}.options`,
+    );
     if (
       JSON.stringify(Object.keys(item.roles)) !==
       JSON.stringify(item.requiredRoleIds)

package/reference/sdlc/code.playbook/bin/playbook.js

@@ -34,6 +34,7 @@ import {
   createManagedInteractiveSessionCommand,
   MANAGED_INTERACTIVE_PAYLOAD_KIND,
   MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION,
+  publishManagedInteractiveReadinessWitness,
 } from './interactive-session.js';
 import { prepareConfiguredRegistries } from './provision.js';
 import {
@@ -115,6 +116,12 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createHostRuntime
         ? { createHostRuntime: options.createHostRuntime }
         : {}),
+      ...(options.createEffectLedgerWriteAhead
+        ? {
+            createEffectLedgerWriteAhead:
+              options.createEffectLedgerWriteAhead,
+          }
+        : {}),
       ...(options.sessionStore
         ? { sessionStore: options.sessionStore }
         : {}),
@@ -126,6 +133,12 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createAttemptId
         ? { createAttemptId: options.createAttemptId }
         : {}),
+      ...(options.installRetainedGenerationsForLaunch
+        ? {
+            installRetainedGenerationsForLaunch:
+              options.installRetainedGenerationsForLaunch,
+          }
+        : {}),
       ...(options.signal ? { signal: options.signal } : {}),
       // PBCLI-39: the run path gates on SDK availability too.
       ...(options.probeAdapterSdk
@@ -213,11 +226,45 @@ export async function runPlaybookCli(options = {}) {
       selectedRecord = validateCaptainSessionRecord(
         await store.read(interactiveArgs.sessionId),
       );
-      if (selectedRecord.state !== 'settled') {
+      const needsAbandonmentRecovery =
+        (selectedRecord.state === 'uncertain' &&
+          Object.hasOwn(selectedRecord.uncertain, 'abandonment')) ||
+        (selectedRecord.state === 'settled' &&
+          Object.hasOwn(selectedRecord, 'settledAbandonment'));
+      if (selectedRecord.state !== 'settled' && !needsAbandonmentRecovery) {
         throw new Error(
           `Captain session ${JSON.stringify(interactiveArgs.sessionId)} has an uncertain turn; recover it with playbook run before reopening interactively`,
         );
       }
+      if (needsAbandonmentRecovery) {
+        const recoveryLease = await store.acquire(interactiveArgs.sessionId);
+        let recoveryError;
+        try {
+          selectedRecord = validateCaptainSessionRecord(
+            await recoveryLease.recoverUnresolvedEffectAbandonment(),
+          );
+        } catch (error) {
+          recoveryError = error;
+        }
+        try {
+          await recoveryLease.release();
+        } catch (error) {
+          if (recoveryError !== undefined) {
+            throw aggregateOperationalFailures(
+              recoveryError,
+              error,
+              'Captain session abandonment recovery failed and its lease could not be released',
+            );
+          }
+          throw error;
+        }
+        if (recoveryError !== undefined) throw recoveryError;
+        if (selectedRecord.state !== 'settled') {
+          throw new Error(
+            `Captain session ${JSON.stringify(interactiveArgs.sessionId)} abandonment recovery did not settle its turn`,
+          );
+        }
+      }
     } catch (error) {
       stderr.write(`playbook: ${errorMessage(error)}\n`);
       return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -358,6 +405,7 @@ export async function runPlaybookCli(options = {}) {
     projectTmuxConfig(plan),
   );
   let prepared;
+  let managedChildWorkDir;
   try {
     throwIfSignalAborted(options.signal);
     prepared = await awaitManagedPreparation(
@@ -372,8 +420,14 @@ export async function runPlaybookCli(options = {}) {
           ...(options.adapterImports
             ? { adapterImports: options.adapterImports }
             : {}),
-          createSessionCommand: (context) =>
-            createManagedInteractiveSessionCommand(
+          createSessionCommand: (context) => {
+            if (managedChildWorkDir !== undefined) {
+              throw new Error(
+                'managed tmux-play requested more than one session command',
+              );
+            }
+            managedChildWorkDir = context.workDir;
+            return createManagedInteractiveSessionCommand(
               context,
               {
                 schemaVersion: MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION,
@@ -393,7 +447,8 @@ export async function runPlaybookCli(options = {}) {
                   ),
                 ...(options.execPath ? { execPath: options.execPath } : {}),
               },
-            ),
+            );
+          },
         }),
       options.signal,
     );
@@ -403,6 +458,28 @@ export async function runPlaybookCli(options = {}) {
         new Error('managed tmux-play prepared a mismatched session id'),
       );
     }
+    if (managedChildWorkDir === undefined) {
+      await cancelPreparedAfterFailure(
+        prepared,
+        new Error('managed tmux-play did not request a session command'),
+      );
+    }
+    if (prepared?.workDir !== managedChildWorkDir) {
+      await cancelPreparedAfterFailure(
+        prepared,
+        new Error('managed tmux-play prepared a mismatched work directory'),
+      );
+    }
+    if (!selectedRecord) {
+      try {
+        await (
+          options.publishManagedReadinessWitness ??
+          publishManagedInteractiveReadinessWitness
+        )(managedChildWorkDir, sessionId);
+      } catch (error) {
+        await cancelPreparedAfterFailure(prepared, error);
+      }
+    }
     try {
       await writeStream(
         stderr,