@sublang/playbook 8.0.0 → 10.0.0

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

@@ -11,7 +11,14 @@ import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { createTmuxPlayRuntime } from '@sublang/cligent/tmux-play';
-import { createPlaybookCaptainShell } from '../playbook-captain.js';
+import {
+  assertPlaybookEffectLedger,
+  emptyPlaybookEffectLedger,
+} from '../../../../src/xstate-runtime.js';
+import {
+  assertPlaybookCaptainShellSnapshot,
+  createPlaybookCaptainShell,
+} from '../playbook-captain.js';
 import {
   adapterSdkFailureLines,
   checkAdapterSdks,
@@ -20,11 +27,18 @@ import {
 } from './adapter-sdk.js';
 import {
   checkReadiness,
+  invalidRegistryEntryReason,
   loadLaunchPlan,
   projectHostAgent,
   resolveUserConfigPath,
+  snapshotRegistryEntry,
 } from './launch-config.js';
 import { prepareConfiguredRegistries } from './provision.js';
+import {
+  createRepositoryEffectCapabilities,
+  refreshRepositoryEffectCapabilities,
+  recoverIncompleteRepositoryEffects,
+} from './repository-effects.js';
 import {
   assertCaptainSessionExecutionCompatible,
   captainSessionSelectedMembers,
@@ -122,18 +136,28 @@ export async function runPlaybookRun(options = {}) {
   if (continuing) {
     try {
       if (args.sessionId === undefined) {
+        const invokingCwd = resolve(options.cwd ?? process.cwd());
         const selected = validateCaptainSessionRecord(
           await awaitWithAbort(
             store.latest({
-              onLegacyRecord: ({ sessionId: legacyId, path }) =>
-                writeStream(
+              preferredCwd: invokingCwd,
+              onLegacyRecord: (record) =>
+                reportSkippedCaptainSession(
                   stderr,
-                  `playbook run: skipping legacy Captain session ${JSON.stringify(legacyId)} at ${JSON.stringify(path)} because schema 2 has incompatible player identity; move it outside the sessions directory or remove it to silence this warning\n`,
+                  'playbook run',
+                  'legacy',
+                  record,
                 ),
             }),
             options.signal,
           ),
         );
+        if (selected.cwd !== invokingCwd) {
+          await writeStream(
+            stderr,
+            `playbook run: no same-directory Captain session exists for invoking working directory ${JSON.stringify(invokingCwd)}; selecting globally newest Captain session ${JSON.stringify(selected.sessionId)} with stored working directory ${JSON.stringify(selected.cwd)}\n`,
+          );
+        }
         sessionId = selected.sessionId;
       } else {
         sessionId = args.sessionId;
@@ -141,7 +165,10 @@ export async function runPlaybookRun(options = {}) {
       throwIfAborted(options.signal);
       lease = await store.acquire(sessionId);
       throwIfAborted(options.signal);
-      const authoritative = await lease.read();
+      const authoritative =
+        typeof lease.recoverUnresolvedEffectAbandonment === 'function'
+          ? await lease.recoverUnresolvedEffectAbandonment()
+          : await lease.read();
       throwIfAborted(options.signal);
       if (authoritative === undefined) {
         throw new Error(
@@ -424,12 +451,14 @@ export async function runPlaybookRun(options = {}) {
   }
 
   let settled;
+  let freshLaunchRecord;
   try {
     settled = await driveHeadlessCaptainTurn({
       config,
       input,
       sessionId,
       cwd,
+      sessionLease: lease,
       loadModule,
       stderr,
       verbose: args.verbose,
@@ -445,11 +474,62 @@ export async function runPlaybookRun(options = {}) {
       ...(options.createHostRuntime
         ? { createHostRuntime: options.createHostRuntime }
         : {}),
+      ...(options.createEffectLedgerWriteAhead
+        ? {
+            createEffectLedgerWriteAhead:
+              options.createEffectLedgerWriteAhead,
+          }
+        : {}),
       ...(restoreSnapshot !== undefined
         ? { restoreSnapshot }
         : {}),
+      ...(args.retryUncertain
+        ? { reconcileUncertainTurnReplay: true }
+        : {}),
       ...(options.signal ? { signal: options.signal } : {}),
-      beforeBossTurn: async (baselineSnapshot) => {
+      beforeBossTurn: async (
+        baselineSnapshot,
+        shell,
+        reconcileRepositoryEffects,
+      ) => {
+        throwIfAborted(options.signal);
+        const installForLaunch =
+          options.installRetainedGenerationsForLaunch ??
+          installRetainedGenerationsForLaunch;
+        await installForLaunch({
+          lease,
+          shell,
+          ...(priorRecord === undefined
+            ? {
+                freshBoundary: {
+                  cwd,
+                  structuralProjection:
+                    projectCaptainSessionStructure(config),
+                  executionProjection: config,
+                  snapshot: baselineSnapshot,
+                },
+                onFreshRecord(record) {
+                  freshLaunchRecord = record;
+                },
+                onLegacyRecord: (record) =>
+                  reportSkippedCaptainSession(
+                    stderr,
+                    'playbook run',
+                    'legacy',
+                    record,
+                  ),
+                onInvalidRecord: (record) =>
+                  reportSkippedCaptainSession(
+                    stderr,
+                    'playbook run',
+                    'invalid',
+                    record,
+                  ),
+              }
+            : {}),
+          retainedGenerations: priorRecord?.retainedGenerations ?? {},
+          reconcileRepositoryEffects,
+        });
         throwIfAborted(options.signal);
         return args.retryUncertain
           ? lease.beginRetry({
@@ -460,22 +540,24 @@ export async function runPlaybookRun(options = {}) {
               input,
               attemptId,
               attemptedExecutionProjection: config,
-              ...(priorRecord === undefined
-                ? {
-                    fresh: {
-                      cwd,
-                      structuralProjection:
-                        projectCaptainSessionStructure(config),
-                      snapshot: baselineSnapshot,
-                    },
-                  }
-                : {}),
             });
       },
       assertBeforeBossTurn: () => lease.assertOwner(),
     });
   } catch (error) {
     const cleanupIncomplete = isCaptainSessionHostCleanupIncomplete(error);
+    let abandonmentError;
+    if (
+      !cleanupIncomplete &&
+      freshLaunchRecord !== undefined &&
+      Object.keys(freshLaunchRecord.retainedGenerations ?? {}).length === 0
+    ) {
+      try {
+        await lease.abandonFreshSettled({ expected: freshLaunchRecord });
+      } catch (cause) {
+        abandonmentError = cause;
+      }
+    }
     const releaseError = cleanupIncomplete
       ? undefined
       : await releaseLease(lease);
@@ -492,9 +574,17 @@ export async function runPlaybookRun(options = {}) {
         `playbook run: cannot release Captain session lease: ${message(releaseError)}\n`,
       );
     }
+    if (abandonmentError !== undefined) {
+      await writeStream(
+        stderr,
+        `playbook run: cannot retract unused fresh Captain session: ${message(abandonmentError)}\n`,
+      );
+    }
     return {
       code:
-        error instanceof HeadlessHostSetupError && releaseError === undefined
+        error instanceof HeadlessHostSetupError &&
+        abandonmentError === undefined &&
+        releaseError === undefined
           ? EXIT.argument
           : EXIT.turn,
     };
@@ -506,6 +596,8 @@ export async function runPlaybookRun(options = {}) {
     durableRecord = await lease.settle({
       attemptId: settled.uncertainRecord.uncertain.attemptId,
       snapshot: settled.snapshot,
+      unresolvedEffects: settled.unresolvedEffects,
+      retentionUpdates: settled.retentionUpdates,
     });
   } catch (error) {
     let cleanupError;
@@ -593,6 +685,7 @@ export async function driveHeadlessCaptainTurn({
   input,
   sessionId,
   cwd,
+  sessionLease,
   loadModule,
   stderr,
   verbose = false,
@@ -600,7 +693,9 @@ export async function driveHeadlessCaptainTurn({
   createCaptainRuntime,
   createCaptainSessionId,
   createHostRuntime = createTmuxPlayRuntime,
+  createEffectLedgerWriteAhead,
   restoreSnapshot,
+  reconcileUncertainTurnReplay = false,
   beforeBossTurn,
   assertBeforeBossTurn,
   signal,
@@ -616,6 +711,7 @@ export async function driveHeadlessCaptainTurn({
         config,
         sessionId,
         cwd,
+        sessionLease,
         loadModule,
         observers: [
           {
@@ -635,10 +731,20 @@ export async function driveHeadlessCaptainTurn({
         ...(createCaptainRuntime ? { createCaptainRuntime } : {}),
         ...(createCaptainSessionId ? { createCaptainSessionId } : {}),
         createHostRuntime,
+        ...(createEffectLedgerWriteAhead
+          ? { createEffectLedgerWriteAhead }
+          : {}),
         ...(restoreSnapshot !== undefined ? { restoreSnapshot } : {}),
+        ...(reconcileUncertainTurnReplay
+          ? { reconcileUncertainTurnReplay: true }
+          : {}),
       });
       ({ shell, host, snapshot: baselineSnapshot } = created);
-      uncertainRecord = await beforeBossTurn?.(baselineSnapshot);
+      uncertainRecord = await beforeBossTurn?.(
+        baselineSnapshot,
+        shell,
+        created.reconcileRepositoryEffects,
+      );
     } catch (error) {
       throw new HeadlessHostSetupError(error);
     }
@@ -660,10 +766,11 @@ export async function driveHeadlessCaptainTurn({
     if (shell === undefined) {
       throw new Error('Captain shell host initialized without a shell');
     }
-    const snapshot = shell.exportSnapshot();
-    if (snapshot === undefined) {
-      throw new Error('Captain turn settled without an exportable session snapshot');
+    const settlement = shell.exportSettlement();
+    if (settlement === undefined) {
+      throw new Error('Captain turn settled without an exportable session settlement');
     }
+    const { snapshot, unresolvedEffects, retentionUpdates } = settlement;
     if (
       snapshot.captain?.sessionId === sessionId ||
       snapshot.issuedSessionIds?.includes(sessionId)
@@ -676,6 +783,8 @@ export async function driveHeadlessCaptainTurn({
       sessionId,
       reply: replies[0],
       snapshot,
+      unresolvedEffects,
+      retentionUpdates,
       config: cloneJson(config),
       cwd,
       uncertainRecord,
@@ -711,6 +820,48 @@ export class CaptainSessionHostCleanupError extends AggregateError {
   }
 }
 
+async function createStoreEffectLedgerService(lease) {
+  let mirror =
+    (await lease.read())?.effectLedger ?? emptyPlaybookEffectLedger();
+  mirror = assertPlaybookEffectLedger(mirror);
+  return Object.freeze({
+    snapshot: () => mirror,
+    async refresh() {
+      mirror = assertPlaybookEffectLedger(
+        (await lease.read())?.effectLedger ?? emptyPlaybookEffectLedger(),
+      );
+      return mirror;
+    },
+    async writeAhead(authority, commands) {
+      mirror = assertPlaybookEffectLedger(
+        await lease.writeEffectLedger(authority, commands),
+      );
+      return mirror;
+    },
+  });
+}
+
+function effectLedgerSnapshotFromCapabilities(hostCapabilities) {
+  const capabilities = Object.values(hostCapabilities);
+  if (capabilities.length === 0) return emptyPlaybookEffectLedger();
+  const mirror = assertPlaybookEffectLedger(
+    capabilities[0].effectLedger.snapshot(),
+  );
+  for (const capability of capabilities.slice(1)) {
+    if (
+      !isDeepStrictEqual(
+        assertPlaybookEffectLedger(capability.effectLedger.snapshot()),
+        mirror,
+      )
+    ) {
+      throw new Error(
+        'schema-3 current-host capabilities disagree on their effect ledger',
+      );
+    }
+  }
+  return mirror;
+}
+
 function isCaptainSessionHostCleanupIncomplete(error) {
   if (error instanceof CaptainSessionHostCleanupError) return true;
   return (
@@ -719,21 +870,145 @@ function isCaptainSessionHostCleanupIncomplete(error) {
   );
 }
 
+function reconcileWholeTurnReplaySnapshot(snapshot, ledger, catalog) {
+  const checkpoint = assertPlaybookEffectLedger(snapshot.effectLedger);
+  const current = assertPlaybookEffectLedger(ledger);
+  const checkpointBoundaryCount = checkpoint.boundaries.length;
+  const currentPrefix = current.boundaries.slice(0, checkpointBoundaryCount);
+  if (!isDeepStrictEqual(currentPrefix, checkpoint.boundaries)) {
+    throw new Error(
+      'Captain uncertain turn repository-effect reconciliation cannot restore a changed pre-turn boundary',
+    );
+  }
+  if (
+    !isDeepStrictEqual(
+      current.logicalOperations,
+      checkpoint.logicalOperations,
+    )
+  ) {
+    throw new Error(
+      'Captain uncertain turn repository-effect reconciliation found deferred logical-operation progress and cannot replay the Boss turn',
+    );
+  }
+  const suffix = current.boundaries.slice(checkpointBoundaryCount);
+  const blocking = suffix.find(
+    (boundary) =>
+      boundary.physicalReceipt?.classification !== 'unchanged',
+  );
+  if (blocking !== undefined) {
+    const classification =
+      blocking.physicalReceipt?.classification ?? 'incomplete';
+    throw new Error(
+      `Captain uncertain turn repository-effect boundary ${JSON.stringify(blocking.boundaryId)} is ${classification}; whole-turn replay remains parked for reconciliation`,
+    );
+  }
+  const frames =
+    snapshot.mode !== 'engaged.parked'
+      ? undefined
+      : snapshot.frames.map((frame) => {
+          if (catalog[frame.playbookId]?.artifactSchema !== 3) {
+            throw new Error(
+              `Captain uncertain turn cannot rebase frame ${JSON.stringify(frame.playbookId)} without exact artifact-schema authority`,
+            );
+          }
+          return {
+            ...frame,
+            runtime: { ...frame.runtime, effectLedger: current },
+          };
+        });
+
+  return assertPlaybookCaptainShellSnapshot({
+    ...snapshot,
+    effectLedger: current,
+    ...(frames === undefined ? {} : { frames }),
+  });
+}
+
 export async function createCaptainSessionHost({
   config,
   sessionId,
   cwd,
+  sessionLease,
   loadModule,
   observers,
   adapterImports,
   createCaptainRuntime,
   createCaptainSessionId,
   createHostRuntime = createTmuxPlayRuntime,
+  createEffectLedgerWriteAhead,
   restoreSnapshot,
+  reconcileUncertainTurnReplay = false,
   signal,
 }) {
+  const hostCapabilities = await createRepositoryEffectCapabilities({
+    cwd,
+    catalog: config.catalog,
+    sessionId,
+    sessionLease,
+    createWriteAhead:
+      createEffectLedgerWriteAhead ?? createStoreEffectLedgerService,
+  });
+  const reconcileRepositoryEffects = async () => {
+    await refreshRepositoryEffectCapabilities(hostCapabilities);
+    await recoverIncompleteRepositoryEffects({
+      catalog: config.catalog,
+      capabilities: hostCapabilities,
+    });
+    return effectLedgerSnapshotFromCapabilities(hostCapabilities);
+  };
+  try {
+    await reconcileRepositoryEffects();
+  } catch (error) {
+    if (!reconcileUncertainTurnReplay) throw error;
+    throw new Error(
+      `Captain uncertain turn repository-effect reconciliation failed: ${message(error)}`,
+      { cause: error },
+    );
+  }
+  const currentEffectLedger = () =>
+    effectLedgerSnapshotFromCapabilities(hostCapabilities);
+  let sourceSnapshot = restoreSnapshot;
+  if (
+    sourceSnapshot !== undefined &&
+    !isDeepStrictEqual(sourceSnapshot.effectLedger, currentEffectLedger())
+  ) {
+    const recovered =
+      typeof sessionLease.read === 'function'
+        ? await sessionLease.read()
+        : undefined;
+    if (
+      recovered?.state === 'settled' &&
+      isDeepStrictEqual(recovered.snapshot.effectLedger, currentEffectLedger())
+    ) {
+      sourceSnapshot = recovered.snapshot;
+    }
+  }
+  if (
+    sourceSnapshot !== undefined &&
+    reconcileUncertainTurnReplay
+  ) {
+    sourceSnapshot = reconcileWholeTurnReplaySnapshot(
+      sourceSnapshot,
+      currentEffectLedger(),
+      config.catalog,
+    );
+  } else if (
+    sourceSnapshot !== undefined &&
+    !isDeepStrictEqual(sourceSnapshot.effectLedger, currentEffectLedger())
+  ) {
+    throw new Error(
+      'Captain session effect ledger requires reconciliation before source-state restoration',
+    );
+  }
   const shell = createPlaybookCaptainShell(captainOptionsFromConfig(config), {
     loadModule,
+    hostCapabilities,
+    unresolvedEffectSettlement: {
+      begin: (input) =>
+        sessionLease.beginUnresolvedEffectAbandonment(input),
+      complete: (input) =>
+        sessionLease.completeUnresolvedEffectAbandonment(input),
+    },
     ...(createCaptainRuntime ? { createCaptainRuntime } : {}),
     ...(createCaptainSessionId
       ? { createSessionId: createCaptainSessionId }
@@ -741,7 +1016,7 @@ export async function createCaptainSessionHost({
   });
   let host;
   try {
-    const captain = captainHostBoundary(shell, restoreSnapshot);
+    const captain = captainHostBoundary(shell, sourceSnapshot);
     host = await createHostRuntime({
       captain,
       captainConfig: projectHostAgent(
@@ -763,16 +1038,13 @@ export async function createCaptainSessionHost({
         'Captain shell initialized without an exportable session snapshot',
       );
     }
-    if (
-      restoreSnapshot !== undefined &&
-      !isDeepStrictEqual(snapshot, restoreSnapshot)
-    ) {
+    if (sourceSnapshot !== undefined && !isDeepStrictEqual(snapshot, sourceSnapshot)) {
       throw new Error('restored Captain snapshot changed before the Boss turn');
     }
     if (sessionId !== undefined) {
       assertLogicalSessionIdDistinct({ sessionId, snapshot });
     }
-    return { shell, host, snapshot };
+    return { shell, host, snapshot, reconcileRepositoryEffects };
   } catch (error) {
     let cleanupError;
     try {
@@ -791,6 +1063,37 @@ export async function createCaptainSessionHost({
   }
 }
 
+// PBCLI-55: both presentations install one authoritative retention map at the
+// same post-shell, pre-turn boundary. Fresh-session guarded initialization
+// publishes either the intentional empty boundary or the transferred map.
+export async function installRetainedGenerationsForLaunch({
+  lease,
+  shell,
+  freshBoundary,
+  onFreshRecord,
+  onLegacyRecord,
+  onInvalidRecord,
+  retainedGenerations,
+  reconcileRepositoryEffects,
+}) {
+  let authoritative = retainedGenerations;
+  if (freshBoundary !== undefined) {
+    const record = await lease.initializeSettledWithPredecessor({
+      ...freshBoundary,
+      onLegacyRecord,
+      onInvalidRecord,
+    });
+    authoritative = record.retainedGenerations ?? {};
+  }
+  await reconcileRepositoryEffects?.();
+  if (freshBoundary !== undefined) {
+    onFreshRecord?.(await lease.read());
+  }
+  await shell.installRetainedGenerations(authoritative);
+  await lease.assertOwner();
+  return authoritative;
+}
+
 // PBCLI-20: restoration enters through the host's one init boundary. The
 // restored shell is fresh and receives restore instead of init, never both.
 function captainHostBoundary(shell, restoreSnapshot) {
@@ -871,11 +1174,11 @@ export async function validateFrozenExecutionConfig(
   for (const [id, item] of catalogItems) {
     let entry;
     try {
-      entry = (await loadModule(item.from))?.default;
+      entry = snapshotRegistryEntry((await loadModule(item.from))?.default);
     } catch (cause) {
       throw new Error(`stored playbook ${JSON.stringify(id)} failed to import: ${message(cause)}`);
     }
-    if (!isValidRegistryEntry(entry)) {
+    if (invalidRegistryEntryReason(entry) !== undefined) {
       throw new Error(`stored playbook ${JSON.stringify(id)} exposes no valid registry entry`);
     }
     if (
@@ -928,38 +1231,6 @@ function memoizedModuleLoader(loadModule) {
   };
 }
 
-function isValidRegistryEntry(value) {
-  if (
-    value === null ||
-    typeof value !== 'object' ||
-    Array.isArray(value) ||
-    typeof value.id !== 'string' ||
-    value.id.trim().length === 0 ||
-    typeof value.command !== 'string' ||
-    value.command.trim().length === 0 ||
-    typeof value.intent !== 'string' ||
-    value.artifactSchema !== 2 ||
-    !Array.isArray(value.requiredRoleIds) ||
-    value.requiredRoleIds.some(
-      (role) => typeof role !== 'string' || role.trim().length === 0,
-    ) ||
-    new Set(value.requiredRoleIds).size !== value.requiredRoleIds.length ||
-    !Array.isArray(value.concurrentRoleSets) ||
-    typeof value.validateOptions !== 'function' ||
-    typeof value.createRuntime !== 'function'
-  ) {
-    return false;
-  }
-  const roles = new Set(value.requiredRoleIds);
-  return value.concurrentRoleSets.every(
-    (set) =>
-      Array.isArray(set) &&
-      set.length >= 2 &&
-      set.every((role) => typeof role === 'string' && roles.has(role)) &&
-      new Set(set).size === set.length,
-  );
-}
-
 export function captainOptionsFromConfig(config) {
   return {
     playbooks: Object.fromEntries(
@@ -1255,6 +1526,35 @@ async function reportUncertainSession(stderr, sessionId) {
   );
 }
 
+function legacyCaptainSessionReason(schemaVersion) {
+  if (schemaVersion === 2) {
+    return 'schema 2 has incompatible player identity';
+  }
+  if (schemaVersion === 3 || schemaVersion === 4) {
+    return `schema ${JSON.stringify(schemaVersion)} predates the artifact-schema-3 effect-authority cutover and is not resumable`;
+  }
+  if (schemaVersion === 5) {
+    return 'schema 5 predates the canonical schema-6 unresolved-effect settlement boundary for the artifact-schema-3 effect-authority cutover and is not resumable';
+  }
+  return `schema ${JSON.stringify(schemaVersion)} is unsupported`;
+}
+
+export async function reportSkippedCaptainSession(
+  stderr,
+  commandName,
+  kind,
+  { sessionId, path, schemaVersion, reason },
+) {
+  const explanation =
+    kind === 'legacy'
+      ? legacyCaptainSessionReason(schemaVersion)
+      : reason;
+  await writeStream(
+    stderr,
+    `${commandName}: skipping ${kind} Captain session ${JSON.stringify(sessionId)} at ${JSON.stringify(path)} because ${explanation}; move it outside the sessions directory or remove it to silence this warning\n`,
+  );
+}
+
 function replayInvocation(argv, args, input) {
   if (args.retryUncertain || args.discardUncertain) {
     return ['run', ...argv];
@@ -1319,14 +1619,16 @@ function runHelpText(userConfigPath) {
     'provider conversation; distinct ids remain isolated.',
     'Legacy playbooks.<id>.players is rejected and is not auto-migrated,',
     'because choosing new ids decides sharing versus isolation.',
-    'An ordinary continued run restores the stored structure and working',
+    'Bare continuation prefers the newest session stored for the invoking',
+    'working directory and reports when it uses the global newest fallback.',
+    'An ordinary continued run restores that stored structure and working',
     'directory, then reads current config and overlays for model and effort.',
     'Uncertain retry instead uses its exact recorded input and settings.',
     '',
     'Options:',
     '  --with <path>    overlay a generic config fragment (repeatable)',
     '  --no-provision   do not provision thin filesystem registry engines',
-    '  --continue       reply to the latest durable Captain session',
+    '  --continue       prefer this working directory, else global newest',
     '  --session <id>   reply to one durable Captain session UUID',
     '  --retry-uncertain retry that session\'s exact recorded uncertain input',
     '  --discard-uncertain discard that session\'s uncertain attempt',