@sublang/playbook 17.4.1 → 17.6.0

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

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

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

@@ -18,10 +18,12 @@ import {
 } from "./adapter-sdk.js";
 import {
   adaptersFromLaunchPlan,
+  extractModuleFlags,
   extractWithFlags,
   loadLaunchPlan,
   loadSelectedLaunchPlanDataOnly,
   projectTmuxConfig,
+  suppliedModulesFromFlags,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
   resolveFormerUserConfigPaths,
@@ -54,15 +56,18 @@ export {
   checkReadiness,
   composeGenericConfig,
   deriveLaunchReadiness,
+  extractModuleFlags,
   extractWithFlags,
   loadLaunchPlan,
   loadOverlayFragment,
   mergeConfigs,
   migrateRetiredProfiles,
   normalizeLaunchPlan,
+  parseModuleFlagValue,
   projectTmuxConfig,
   resolveAgent,
   resolveUserConfigPath,
+  suppliedModulesFromFlags,
 } from "./launch-config.js";
 
 const READINESS_FAILURE_EXIT_CODE = 2;
@@ -188,10 +193,15 @@ export async function runPlaybookCli(options = {}) {
   // PBCLI-25/26: `--with <path>` overlays are launcher-owned — consumed
   // here, never forwarded to tmux-play, and incompatible with a raw
   // `--config` launch, which bypasses the composition they target.
+  // PBCLI-94 (DR-083): `--module <id>=<specifier>` is launcher-owned in the
+  // same way: consumed, never forwarded, and refused beside raw `--config`.
   let withPaths;
+  let modulePairs;
+  let modules;
   let forwardArgv;
   try {
     ({ withPaths, rest: forwardArgv } = extractWithFlags(argv));
+    ({ modulePairs, rest: forwardArgv } = extractModuleFlags(forwardArgv));
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -203,6 +213,22 @@ export async function runPlaybookCli(options = {}) {
     );
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
+  if (modulePairs.length > 0 && hasExplicitConfig(argv)) {
+    stderr.write(
+      "playbook: --module supplies a playbook module for the top-level " +
+        "config and cannot combine with a raw --config launch\n",
+    );
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+  try {
+    modules = suppliedModulesFromFlags(
+      modulePairs,
+      options.cwd ?? process.cwd(),
+    );
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
   const noProvision = forwardArgv.includes("--no-provision");
   forwardArgv = forwardArgv.filter((arg) => arg !== "--no-provision");
   if (noProvision && hasExplicitConfig(argv)) {
@@ -349,6 +375,7 @@ export async function runPlaybookCli(options = {}) {
       ? await loadSelectedLaunchPlanDataOnly({
           userConfigPath,
           overlayPaths: withPaths,
+          modules,
           structuralProjection: selectedRecord.structuralProjection,
           onNotice: (line) => stderr.write(line),
           env,
@@ -357,6 +384,7 @@ export async function runPlaybookCli(options = {}) {
       : await loadLaunchPlan({
           userConfigPath,
           overlayPaths: withPaths,
+          modules,
           env,
           homeDir: home,
           loadModule,
@@ -923,13 +951,17 @@ function helpText({
     ...sdkFailureLines,
     ...failures,
     "Usage:",
-    "  playbook [--with <path>]... [--no-provision] [--cwd <path>]",
-    "  playbook --session <id> [--with <path>]... [--no-provision]",
-    "  playbook --list [--with <path>]... [--no-provision]",
-    "  playbook --theme-diagnostics [--with <path>]... [--cwd <path>]",
+    "  playbook [--with <path>]... [--module <id>=<specifier>]...",
+    "           [--no-provision] [--cwd <path>]",
+    "  playbook --session <id> [--with <path>]...",
+    "           [--module <id>=<specifier>]... [--no-provision]",
+    "  playbook --list [--with <path>]... [--module <id>=<specifier>]...",
+    "           [--no-provision]",
+    "  playbook --theme-diagnostics [--with <path>]...",
+    "           [--module <id>=<specifier>]... [--cwd <path>]",
     "  playbook --config <path> [tmux-play arguments...]",
-    "  playbook run [--with <path>]... [--no-provision] [--json]",
-    "               [--verbose] [--] [input]",
+    "  playbook run [--with <path>]... [--module <id>=<specifier>]...",
+    "               [--no-provision] [--json] [--verbose] [--] [input]",
     "  playbook run (--continue | --session <id>) [reply]",
     "  playbook run --session <id> --retry-uncertain",
     "  playbook run --session <id> --discard-uncertain",
@@ -947,6 +979,11 @@ function helpText({
     "  the default config) for a fresh launch or compatible ordinary reopen —",
     "  maps merge recursively, other values replace, later files win, and the",
     "  default config file is never modified.",
+    "  --module <id>=<specifier> supplies playbook <id>'s registry module",
+    "  ahead of its playbooks.<id>.from (repeatable, one per id); a relative",
+    "  path resolves against the current directory, and the module is never",
+    "  written back to your config files. Without --module or from, a",
+    "  reopened session uses the module it already records.",
     "  --no-provision keeps configured filesystem registries read-only;",
     "  any missing engine links remain a launch error.",
     "  `playbook run --verbose` prints Captain telemetry topics to stderr.",

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

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

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

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

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

@@ -39,12 +39,14 @@ import {
   invalidRegistryEntryReason,
   loadLaunchPlan,
   loadSelectedLaunchPlanDataOnly,
+  parseModuleFlagValue,
   projectHostAgent,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
   resolveFormerUserConfigPaths,
   resolveUserConfigPath,
   snapshotRegistryEntry,
+  suppliedModulesFromFlags,
 } from "./launch-config.js";
 import { prepareConfiguredRegistries } from "./provision.js";
 import {
@@ -122,6 +124,12 @@ export async function runPlaybookRun(options = {}) {
   const recovering = args.retryUncertain || args.discardUncertain;
   const continuing = args.continue || args.sessionId !== undefined;
   let input = args.input;
+  // PBCLI-94 (DR-083): a relative supplied module resolves against the
+  // invocation's working directory before the loader sees it.
+  const modules = suppliedModulesFromFlags(
+    args.modulePairs,
+    options.cwd ?? process.cwd(),
+  );
 
   // PBCLI-18/40: a fresh piped producer is drained before config,
   // preparation, import, or readiness. Continuations first inspect the
@@ -369,6 +377,7 @@ export async function runPlaybookRun(options = {}) {
         ? await loadSelectedLaunchPlanDataOnly({
             userConfigPath,
             overlayPaths: args.withPaths,
+            modules,
             structuralProjection: priorRecord.structuralProjection,
             onNotice: (line) => configNotices.push(line),
             env,
@@ -377,6 +386,7 @@ export async function runPlaybookRun(options = {}) {
         : await loadLaunchPlan({
             userConfigPath,
             overlayPaths: args.withPaths,
+            modules,
             env,
             homeDir: home,
             loadModule,
@@ -1561,6 +1571,7 @@ export function parseRunArgs(argv) {
   const parsed = {
     input: undefined,
     withPaths: [],
+    modulePairs: [],
     noProvision: false,
     json: false,
     verbose: false,
@@ -1625,6 +1636,18 @@ export function parseRunArgs(argv) {
       const value = arg.slice("--with=".length);
       if (value === "") throw new Error("--with needs a value");
       parsed.withPaths.push(value);
+    } else if (arg === "--module" || arg.startsWith("--module=")) {
+      // PBCLI-94 (DR-083): one `<id>=<specifier>` per playbook id.
+      const pair = parseModuleFlagValue(
+        arg === "--module" ? argv[index + 1] : arg.slice("--module=".length),
+      );
+      if (arg === "--module") index += 1;
+      if (parsed.modulePairs.some(([id]) => id === pair[0])) {
+        throw new Error(
+          `--module names playbook ${JSON.stringify(pair[0])} more than once`,
+        );
+      }
+      parsed.modulePairs.push(pair);
     } else if (
       RETIRED_FLAGS.has(arg) ||
       [...RETIRED_FLAGS].some((flag) => arg.startsWith(`${flag}=`))
@@ -1681,6 +1704,12 @@ export function parseRunArgs(argv) {
   ) {
     throw new Error("--with is unavailable during uncertain-turn recovery");
   }
+  if (
+    (parsed.retryUncertain || parsed.discardUncertain) &&
+    parsed.modulePairs.length > 0
+  ) {
+    throw new Error("--module is unavailable during uncertain-turn recovery");
+  }
   if (
     parsed.sessionId !== undefined &&
     !SESSION_ID_PATTERN.test(parsed.sessionId)
@@ -1928,10 +1957,11 @@ async function writeStream(stream, text) {
 function runHelpText(userConfigPath) {
   return [
     "Usage:",
-    "  playbook run [--with <path>]... [--no-provision] [--json]",
-    "               [--verbose] [--] [input]",
+    "  playbook run [--with <path>]... [--module <id>=<specifier>]...",
+    "               [--no-provision] [--json] [--verbose] [--] [input]",
     "  playbook run (--continue | --session <id>) [--with <path>]...",
-    "               [--no-provision] [--json] [--verbose] [--] [reply]",
+    "               [--module <id>=<specifier>]... [--no-provision] [--json]",
+    "               [--verbose] [--] [reply]",
     "  playbook run --session <id> --retry-uncertain [--no-provision]",
     "  playbook run --session <id> --discard-uncertain",
     "",
@@ -1959,6 +1989,10 @@ function runHelpText(userConfigPath) {
     "",
     "Options:",
     "  --with <path>    overlay a generic config fragment (repeatable)",
+    "  --module <id>=<specifier>",
+    "                   supply playbook <id>'s module ahead of its",
+    "                   playbooks.<id>.from (repeatable, one per id); a",
+    "                   continuation without either uses the stored module",
     "  --no-provision   do not provision thin filesystem registry engines",
     "  --continue       prefer this working directory, else global newest",
     "  --session <id>   reply to one durable Captain session UUID",