@relayflows/sdk 2.0.29 → 2.0.31

package/src/plugin-store.ts

@@ -1,6 +1,25 @@
-import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { payloadManifest, safePath, sha256 } from './bundle.js';
+import {
+  closeDescriptor,
+  closeDirectory,
+  descriptorIsDirectory,
+  descriptorIsFile,
+  directoryEntryIsDirectory,
+  directoryEntryIsFile,
+  lstatPath,
+  openDirectory,
+  openDescriptor,
+  readDescriptor,
+  readDirectoryEntry,
+  statDescriptor,
+} from './fs-descriptor.js';
+import { frozenHostedPromiseValue, hostedPromiseValue } from './hosted-promise-safety.js';
+import { appendIntrinsicArray } from './intrinsic-array.js';
+import { snapshotJsonValue, type JsonValue } from './json-value.js';
+import { MAX_PLUGIN_FILE_BYTES, MAX_PLUGIN_FILES, MAX_PLUGIN_TOTAL_BYTES } from './plugin-github.js';
 import { PluginError } from './plugin-manifest.js';
 
 /**
@@ -13,93 +32,341 @@ import { PluginError } from './plugin-manifest.js';
  * refusal, not a surprise.
  */
 export const PLUGIN_STORE = '.flows/plugins';
+const MKDIR = mkdir;
+const MKDTEMP = mkdtemp;
+const RENAME = rename;
+const RM = rm;
+const WRITE_FILE = writeFile;
+const PATH_DIRNAME = dirname;
+const PATH_JOIN = join;
+const PATH_RESOLVE = resolve;
+const PROCESS_PLATFORM = process.platform;
+const ERROR = Error;
+const MAX_PLUGIN_MANIFEST_BYTES = 4_000_000;
+const MAX_PLUGIN_STORE_ENTRIES = 10_000;
+const ARRAY_IS_ARRAY = Array.isArray;
+const BIG_INT = BigInt;
+const BUFFER_ALLOC_UNSAFE = Buffer.allocUnsafe;
+const BUFFER_TO_STRING = Function.prototype.call.bind(Buffer.prototype.toString) as (
+  value: Buffer,
+  encoding: BufferEncoding,
+) => string;
+const JSON_PARSE = JSON.parse;
+const NUMBER = Number;
+const NUMBER_IS_SAFE_INTEGER = Number.isSafeInteger;
+const OBJECT_CREATE = Object.create;
+const OBJECT_FREEZE = Object.freeze;
+const OBJECT_GET_OWN_PROPERTY_DESCRIPTOR = Object.getOwnPropertyDescriptor;
+const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (pattern: RegExp, value: string) => boolean;
+const SET = Set;
+const SET_ADD = Function.prototype.call.bind(Set.prototype.add) as <T>(set: Set<T>, value: T) => Set<T>;
+const SET_FOR_EACH = Function.prototype.call.bind(Set.prototype.forEach) as <T>(
+  set: Set<T>,
+  callback: (value: T) => void,
+) => void;
+const SET_HAS = Function.prototype.call.bind(Set.prototype.has) as <T>(set: Set<T>, value: T) => boolean;
+const STRING_SPLIT = Function.prototype.call.bind(String.prototype.split) as (
+  value: string,
+  separator: string,
+) => string[];
+const STRING_STARTS_WITH = Function.prototype.call.bind(String.prototype.startsWith) as (
+  value: string,
+  search: string,
+) => boolean;
+const READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
 
 export function pluginStoreDirectory(root: string, name: string, digest: string): string {
-  return join(resolve(root), PLUGIN_STORE, `${name}@sha256:${digest}`);
+  return PATH_JOIN(PATH_RESOLVE(root), PLUGIN_STORE, `${name}@sha256:${digest}`);
 }
 
-export interface StoredPluginFile { readonly path: string; readonly data: Uint8Array }
+export interface StoredPluginFile {
+  readonly path: string;
+  readonly data: Uint8Array;
+}
+
+/** @internal Deterministic race seams for the bounded store reader. */
+export interface StoredPluginReadTestHooks {
+  readonly beforeOpen?: (path: string) => Promise<void>;
+  readonly afterStat?: (path: string) => Promise<void>;
+  readonly beforeDirectoryStat?: () => Promise<void>;
+}
+
+const EMPTY_STORED_PLUGIN_HOOKS = OBJECT_FREEZE(
+  OBJECT_CREATE(null),
+) as StoredPluginReadTestHooks;
 
 /** Write the files atomically; an existing directory is verified instead of overwritten. */
-export async function materializePlugin(root: string, name: string, files: readonly StoredPluginFile[]): Promise<{ directory: string; digest: string }> {
+export async function materializePlugin(
+  root: string,
+  name: string,
+  files: readonly StoredPluginFile[],
+): Promise<{ directory: string; digest: string }> {
   const manifest = payloadManifest(files);
   const digest = sha256(manifest);
   const directory = pluginStoreDirectory(root, name, digest);
   let exists = false;
-  try { await lstat(directory); exists = true; }
-  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
-  if (exists) { await verifyStoredPlugin(directory, digest); return { directory, digest }; }
-  const parent = dirname(directory);
-  await mkdir(parent, { recursive: true });
-  const staging = await mkdtemp(join(parent, '.install-'));
   try {
-    for (const file of files) {
-      if (!safePath(file.path) || file.path === 'manifest.json') throw new PluginError('plugin_path_invalid', `${file.path}: invalid plugin path.`);
-      await mkdir(dirname(join(staging, file.path)), { recursive: true });
-      await writeFile(join(staging, file.path), file.data, { mode: 0o644 });
+    await lstatPath(directory);
+    exists = true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  if (exists) {
+    await verifyStoredPlugin(directory, digest);
+    return frozenHostedPromiseValue({ directory, digest });
+  }
+  const parent = PATH_DIRNAME(directory);
+  await MKDIR(parent, { recursive: true });
+  const staging = await MKDTEMP(PATH_JOIN(parent, '.install-'));
+  try {
+    for (let index = 0; index < files.length; index += 1) {
+      const file = files[index]!;
+      if (!safePath(file.path) || file.path === 'manifest.json')
+        throw new PluginError('plugin_path_invalid', `${file.path}: invalid plugin path.`);
+      await MKDIR(PATH_DIRNAME(PATH_JOIN(staging, file.path)), {
+        recursive: true,
+      });
+      await WRITE_FILE(PATH_JOIN(staging, file.path), file.data, {
+        mode: 0o644,
+      });
     }
-    await writeFile(join(staging, 'manifest.json'), manifest);
-    try { await rename(staging, directory); }
-    catch (error) {
-      if (!['EEXIST', 'ENOTEMPTY'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+    await WRITE_FILE(PATH_JOIN(staging, 'manifest.json'), manifest);
+    try {
+      await RENAME(staging, directory);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'EEXIST' && code !== 'ENOTEMPTY') throw error;
       await verifyStoredPlugin(directory, digest);
     }
-  } finally { await rm(staging, { recursive: true, force: true }); }
-  return { directory, digest };
+  } finally {
+    await RM(staging, { recursive: true, force: true });
+  }
+  return frozenHostedPromiseValue({ directory, digest });
 }
 
-async function regularFile(root: string, path: string): Promise<Buffer> {
-  const parts = path.split('/');
-  for (let i = 1; i <= parts.length; i++) {
-    const stat = await lstat(join(root, ...parts.slice(0, i)));
-    if (i === parts.length ? !stat.isFile() : !stat.isDirectory()) throw new PluginError('plugin_source_drift', `${path}: expected a regular file, without symlinks.`);
+async function regularFile(
+  root: string,
+  path: string,
+  maxBytes: number,
+  expectedBytes?: number,
+  hooks: StoredPluginReadTestHooks = EMPTY_STORED_PLUGIN_HOOKS,
+): Promise<Buffer> {
+  const absolute = PATH_JOIN(root, path);
+  const handle = await openStoredFile(root, path, hooks);
+  try {
+    const before = await statDescriptor(handle, { bigint: true });
+    if (
+      !descriptorIsFile(before) ||
+      before.size < 0n ||
+      before.size > BIG_INT(maxBytes) ||
+      (expectedBytes !== undefined && before.size !== BIG_INT(expectedBytes))
+    ) {
+      throw new PluginError('plugin_source_drift', `${path}: expected a bounded regular file.`);
+    }
+    await ownHook(hooks, 'afterStat')?.(absolute);
+    const size = NUMBER(before.size);
+    const bytes = BUFFER_ALLOC_UNSAFE(size);
+    let offset = 0;
+    while (offset < size) {
+      const bytesRead = await readDescriptor(handle, bytes, offset, size - offset, offset);
+      if (bytesRead === 0) {
+        throw new PluginError('plugin_source_drift', `${path}: changed while reading.`);
+      }
+      offset += bytesRead;
+    }
+    const extra = BUFFER_ALLOC_UNSAFE(1);
+    if ((await readDescriptor(handle, extra, 0, 1, size)) !== 0) {
+      throw new PluginError('plugin_source_drift', `${path}: changed while reading.`);
+    }
+    const after = await statDescriptor(handle, { bigint: true });
+    if (after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs) {
+      throw new PluginError('plugin_source_drift', `${path}: changed while reading.`);
+    }
+    return hostedPromiseValue(bytes);
+  } finally {
+    await closeDescriptor(handle);
+  }
+}
+
+async function openStoredFile(root: string, path: string, hooks: StoredPluginReadTestHooks): Promise<number> {
+  const parts = STRING_SPLIT(path, '/');
+  if (PROCESS_PLATFORM !== 'linux') {
+    for (let i = 1; i < parts.length; i++) {
+      let parent = root;
+      for (let index = 0; index < i; index += 1) parent = PATH_JOIN(parent, parts[index]!);
+      if (!descriptorIsDirectory(await lstatPath(parent))) {
+        throw new PluginError('plugin_source_drift', `${path}: expected a regular file, without symlinks.`);
+      }
+    }
+    await ownHook(hooks, 'beforeOpen')?.(PATH_JOIN(root, path));
+    return await openDescriptor(PATH_JOIN(root, path), READ_FLAGS);
+  }
+  let directory = await openDescriptor(PATH_RESOLVE(root), READ_FLAGS);
+  try {
+    if (!descriptorIsDirectory(await statDescriptor(directory, { bigint: true }))) {
+      throw new PluginError('plugin_source_drift', `${path}: plugin store root is not a directory.`);
+    }
+    for (let index = 0; index < parts.length - 1; index += 1) {
+      const part = parts[index]!;
+      const child = await openDescriptor(`/proc/self/fd/${directory}/${part}`, READ_FLAGS);
+      let adopted = false;
+      try {
+        await ownHook(hooks, 'beforeDirectoryStat')?.();
+        if (!descriptorIsDirectory(await statDescriptor(child, { bigint: true }))) {
+          throw new PluginError('plugin_source_drift', `${path}: expected a regular file, without symlinks.`);
+        }
+        await closeDescriptor(directory);
+        directory = child;
+        adopted = true;
+      } finally {
+        if (!adopted) await closeDescriptor(child);
+      }
+    }
+    await ownHook(hooks, 'beforeOpen')?.(PATH_JOIN(root, path));
+    return await openDescriptor(`/proc/self/fd/${directory}/${parts[parts.length - 1]!}`, READ_FLAGS);
+  } finally {
+    await closeDescriptor(directory);
   }
-  return readFile(join(root, path));
 }
 
 /** Re-hash a materialized plugin and compare with the digest the lockfile recorded. */
-export async function verifyStoredPlugin(directory: string, expectedDigest: string): Promise<void> {
-  const drift = (message: string): never => { throw new PluginError('plugin_source_drift', `${directory}: ${message}`); };
-  let raw: string;
+export async function verifyStoredPlugin(
+  directory: string,
+  expectedDigest: string,
+  hooks: StoredPluginReadTestHooks = EMPTY_STORED_PLUGIN_HOOKS,
+): Promise<void> {
+  await readVerifiedStoredPluginFiles(directory, expectedDigest, hooks);
+}
+
+async function readVerifiedStoredPluginFiles(
+  directory: string,
+  expectedDigest: string,
+  hooks: StoredPluginReadTestHooks,
+): Promise<readonly { path: string; data: Buffer }[]> {
+  const drift = (message: string): never => {
+    throw new PluginError('plugin_source_drift', `${directory}: ${message}`);
+  };
+  let manifest: Buffer;
   try {
-    if (!(await lstat(directory)).isDirectory()) return drift('not a directory');
-    raw = (await regularFile(directory, 'manifest.json')).toString('utf8');
-  } catch (error) { return drift(error instanceof PluginError ? error.message : 'manifest.json is missing'); }
+    if (!descriptorIsDirectory(await lstatPath(directory))) return drift('not a directory');
+    manifest = await regularFile(directory, 'manifest.json', MAX_PLUGIN_MANIFEST_BYTES, undefined, hooks);
+  } catch (error) {
+    return drift(error instanceof PluginError ? error.message : 'manifest.json is missing');
+  }
+  const raw = BUFFER_TO_STRING(manifest, 'utf8');
   if (sha256(raw) !== expectedDigest) return drift('manifest.json digest differs from the lockfile');
-  let entries: { path: string; sha256: string; bytes: number }[];
-  try { entries = JSON.parse(raw); if (!Array.isArray(entries)) throw new Error(); }
-  catch { return drift('manifest.json is not a manifest'); }
-  const paths = new Set<string>();
-  for (const entry of entries) {
-    if (typeof entry?.path !== 'string' || !safePath(entry.path)) return drift('manifest.json lists an invalid path');
+  let entries: JsonValue[];
+  try {
+    const value = snapshotJsonValue(JSON_PARSE(raw), 'stored plugin manifest', {
+      maxBytes: MAX_PLUGIN_MANIFEST_BYTES,
+      maxDepth: 3,
+      maxNodes: 1 + MAX_PLUGIN_FILES * 4,
+    });
+    if (!ARRAY_IS_ARRAY(value)) throw new ERROR();
+    entries = value;
+  } catch {
+    return drift('manifest.json is not a manifest');
+  }
+  if (entries.length > MAX_PLUGIN_FILES) return drift(`manifest.json lists more than ${MAX_PLUGIN_FILES} files`);
+  const paths = new SET<string>();
+  const files = [{ path: 'manifest.json', data: manifest }];
+  let totalBytes = 0;
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index]!;
+    if (
+      typeof entry !== 'object' ||
+      entry === null ||
+      ARRAY_IS_ARRAY(entry)
+    )
+      return drift('manifest.json lists an invalid file');
+    const path = entry.path;
+    const digest = entry.sha256;
+    const bytes = entry.bytes;
+    if (
+      typeof path !== 'string' ||
+      !safePath(path) ||
+      typeof digest !== 'string' ||
+      !REGEXP_TEST(/^[a-f0-9]{64}$/, digest) ||
+      typeof bytes !== 'number' ||
+      !NUMBER_IS_SAFE_INTEGER(bytes) ||
+      bytes < 0 ||
+      bytes > MAX_PLUGIN_FILE_BYTES ||
+      SET_HAS(paths, path)
+    )
+      return drift('manifest.json lists an invalid file');
+    totalBytes += bytes;
+    if (totalBytes > MAX_PLUGIN_TOTAL_BYTES) return drift(`plugin exceeds ${MAX_PLUGIN_TOTAL_BYTES} bytes`);
     let data: Buffer;
-    try { data = await regularFile(directory, entry.path); }
-    catch (error) { return drift(error instanceof PluginError ? error.message : `${entry.path} is missing`); }
-    if (data.length !== entry.bytes || sha256(data) !== entry.sha256) return drift(`${entry.path} changed since installation`);
-    paths.add(entry.path);
+    try {
+      data = await regularFile(directory, path, MAX_PLUGIN_FILE_BYTES, bytes, hooks);
+    } catch (error) {
+      return drift(error instanceof PluginError ? error.message : `${path} is missing`);
+    }
+    if (sha256(data) !== digest) return drift(`${path} changed since installation`);
+    SET_ADD(paths, path);
+    appendIntrinsicArray(files, { path, data });
+  }
+  SET_ADD(paths, 'manifest.json');
+  await rejectExtras(directory, '', paths, drift);
+  const frozen: Readonly<{ path: string; data: Buffer }>[] = [];
+  for (let index = 0; index < files.length; index += 1) {
+    appendIntrinsicArray(frozen, OBJECT_FREEZE(files[index]!));
   }
-  await rejectExtras(directory, '', new Set([...paths, 'manifest.json']), drift);
+  return frozenHostedPromiseValue(frozen);
 }
 
 /** Re-verify, then return every stored file including the payload `manifest.json`. */
-export async function readStoredPluginFiles(directory: string, expectedDigest: string): Promise<readonly { path: string; data: Buffer }[]> {
-  await verifyStoredPlugin(directory, expectedDigest);
-  const manifest = await regularFile(directory, 'manifest.json');
-  const entries = JSON.parse(manifest.toString('utf8')) as { path: string }[];
-  const files = [{ path: 'manifest.json', data: manifest }];
-  for (const entry of entries) files.push({ path: entry.path, data: await regularFile(directory, entry.path) });
-  return files;
+export async function readStoredPluginFiles(
+  directory: string,
+  expectedDigest: string,
+  hooks: StoredPluginReadTestHooks = EMPTY_STORED_PLUGIN_HOOKS,
+): Promise<readonly { path: string; data: Buffer }[]> {
+  return await readVerifiedStoredPluginFiles(directory, expectedDigest, hooks);
+}
+
+function ownHook(
+  hooks: StoredPluginReadTestHooks,
+  name: keyof StoredPluginReadTestHooks,
+): ((...args: unknown[]) => Promise<void>) | undefined {
+  const descriptor = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(hooks, name);
+  return descriptor !== undefined && 'value' in descriptor && typeof descriptor.value === 'function'
+    ? descriptor.value as (...args: unknown[]) => Promise<void>
+    : undefined;
 }
 
 /** Drop a materialized plugin directory. Missing is a no-op. */
 export async function removeStoredPlugin(directory: string): Promise<void> {
-  await rm(directory, { recursive: true, force: true });
+  await RM(directory, { recursive: true, force: true });
 }
 
-async function rejectExtras(root: string, prefix: string, paths: Set<string>, drift: (m: string) => never): Promise<void> {
-  for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
-    const path = prefix + entry.name;
-    if (entry.isDirectory() && [...paths].some(file => file.startsWith(`${path}/`))) await rejectExtras(root, `${path}/`, paths, drift);
-    else if (!entry.isFile() || !paths.has(path)) drift(`${path}: unlisted file or unsupported file type`);
+async function rejectExtras(
+  root: string,
+  prefix: string,
+  paths: Set<string>,
+  drift: (m: string) => never,
+): Promise<void> {
+  let entries = 0;
+  async function visit(currentPrefix: string): Promise<void> {
+    const directory = await openDirectory(PATH_JOIN(root, currentPrefix));
+    try {
+      for (;;) {
+        const entry = await readDirectoryEntry(directory);
+        if (entry === null) break;
+        entries += 1;
+        if (entries > MAX_PLUGIN_STORE_ENTRIES) drift('plugin store contains too many entries');
+        const path = currentPrefix + entry.name;
+        let declaredDescendant = false;
+        SET_FOR_EACH(paths, file => {
+          if (STRING_STARTS_WITH(file, `${path}/`)) declaredDescendant = true;
+        });
+        if (directoryEntryIsDirectory(entry) && declaredDescendant) await visit(`${path}/`);
+        else if (!directoryEntryIsFile(entry) || !SET_HAS(paths, path)) {
+          drift(`${path}: unlisted file or unsupported file type`);
+        }
+      }
+    } finally {
+      await closeDirectory(directory);
+    }
   }
+  await visit(prefix);
 }

package/src/preflight.ts

@@ -12,6 +12,7 @@ import { compileSpec, CompileError } from './compile.js';
 import { helperCall } from './yaml-helpers.js';
 import { resolveCliModelSelection, type CliModelSource } from './cli-adapter.js';
 import { isNamedGate, NAMED_GATE_FAILURE_KINDS, type NamedGateFailureKind } from './named-gates.js';
+import { namedGateScanCoverageDiagnostics } from './named-gate-preflight.js';
 import { compileScopes, type ScopeInput, type MountRegistry } from './scope-compiler.js';
 import { readMountRegistry } from './mount-registry.js';
 import type {
@@ -242,6 +243,12 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   // permissions they declared on the same file are not enforced.
   diagnostics.push(...permissionsDiagnostics(compiled));
   diagnostics.push(...scopeDiagnostics(compiled, options));
+  // Same rule, same reason: whether the bundled worker's artifact scan can
+  // reach an `artifact_exists` path is decidable from the snapshot, so it is
+  // collected here rather than beside `probeNamedGate` below — which CLI
+  // resolution, an unknown model, a bad scope or a budget refusal all return
+  // before.
+  diagnostics.push(...compiled.steps.flatMap(namedGateScanCoverageDiagnostics));
   for (const server of new Set(options.mcpServers ?? [])) {
     if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;
     diagnostics.push({ severity: 'refusal', kind: 'mcp_undeclared_server', server,

package/src/protocol.ts

@@ -96,6 +96,8 @@ export type StepUsage =
 export interface RunStartParams {
   /** Caller-owned retry identity. Reuse with a different spec is refused. */
   admission_key?: string;
+  /** Push the new run's entries to this connection from `run.spawned` on, as `run.watch` does. */
+  watch?: boolean;
   reuse_from_run_id?: string;
   /**
    * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`

package/src/redact.ts

@@ -104,3 +104,114 @@ export function redactRelayError(message: string, env: NodeJS.ProcessEnv = proce
   }
   return redact(message, env);
 }
+
+/**
+ * Credential heads whose value may continue past a line boundary.
+ *
+ * Every NAMED_VALUE pattern puts `\s` between the name and the value, and
+ * `\s` matches newlines: `authorization:` alone at the end of a poll is a
+ * complete, unredacted line, while the opaque value that lands on the next
+ * poll arrives with no recognizable credential context and would print
+ * verbatim. A trailing header — the colon plus only whitespace, or for
+ * `authorization` one scheme word — is therefore an open context. A header
+ * already followed by a non-space word has its value on that line and is not
+ * open. `Bearer` is the one bare scheme word the patterns treat as a name.
+ */
+const OPEN_HEADER_PATTERNS: readonly RegExp[] = [
+  /\bauthorization:(?:\s+\w+)?\s*$/i,
+  /\bx-callback-token:\s*$/i,
+  /\bx-nightcto-evidence-token:\s*$/i,
+  /\bBearer\s*$/,
+];
+
+/** A quoted JSON field name; the value side is inspected by the scanner. */
+const JSON_FIELD_HEAD = /"([A-Za-z0-9_.\-]{1,64})"/g;
+
+/**
+ * Where a named-credential context may still be half-arrived at the end of
+ * `text`.
+ *
+ * `openSecretStart` covers secret env *values*; this covers the credential
+ * *names* whose patterns can span a line break: a header released on one poll
+ * leaves its late-arriving value unrecognizable on the next, and a credential
+ * JSON field whose value string is not yet closed leaks its first fragment.
+ * Returns the earliest index at which such a context is open — the point past
+ * which nothing may be released until more of the stream arrives — or
+ * `text.length` when none is open. Holding back is line-granular upstream, so
+ * a false positive delays one line one poll rather than dropping it.
+ */
+export function openCredentialStart(text: string): number {
+  let hold = text.length;
+  for (const pattern of OPEN_HEADER_PATTERNS) {
+    const match = pattern.exec(text);
+    if (match && match.index < hold) hold = match.index;
+  }
+  JSON_FIELD_HEAD.lastIndex = 0;
+  let head: RegExpExecArray | null;
+  while ((head = JSON_FIELD_HEAD.exec(text)) !== null) {
+    if (!isCredentialName(head[1]!)) continue;
+    let i = head.index + head[0].length;
+    while (i < text.length && /\s/.test(text[i]!)) i++;
+    if (i >= text.length) { hold = Math.min(hold, head.index); continue; }
+    if (text[i] !== ':') continue;
+    i++;
+    while (i < text.length && /\s/.test(text[i]!)) i++;
+    if (i >= text.length) { hold = Math.min(hold, head.index); continue; }
+    if (text.startsWith('[redacted]', i) || text[i] !== '"') continue;
+    i++;
+    let closed = false;
+    while (i < text.length) {
+      if (text[i] === '\\') { i += 2; continue; }
+      if (text[i] === '"') { closed = true; break; }
+      i++;
+    }
+    if (!closed) hold = Math.min(hold, head.index);
+  }
+  return hold;
+}
+
+/**
+ * Does `text` end on a bare credential header — a named credential line whose
+ * value, if it has one, begins on the NEXT line?
+ *
+ * The stream releaser needs this apart from `openCredentialStart`: that check
+ * sees only a header at the very end of the consumed text, but the danger is
+ * wider — a released block that *ends* on `x-callback-token:` prints the
+ * header now and its value, arriving on the next line in some later poll,
+ * without the context `redact` needs. `redact` folds the header's newline into
+ * its own named-pattern match, so the releaser's block-prefix check cannot
+ * detect the dependency on its own. Trailing whitespace-only lines after the
+ * header count as part of it — the value is still to come.
+ */
+export function endsWithOpenCredentialHeader(text: string): boolean {
+  const stripped = text.replace(/\s+$/, '');
+  const lastLine = stripped.slice(stripped.lastIndexOf('\n') + 1);
+  return OPEN_HEADER_PATTERNS.some((pattern) => pattern.test(lastLine));
+}
+
+/**
+ * Where a secret value may still be half-arrived at the end of `text`.
+ *
+ * A stream is redacted in pieces, and `redact` only replaces a secret it can
+ * see whole: releasing text up to a point where a secret has begun but not
+ * ended would print the first half of it and never match the second. This
+ * returns the smallest index `i` for which `text.slice(i)` is a proper prefix
+ * of some secret env value — the point past which nothing may be released
+ * until more of the stream arrives — or `text.length` when no value is open.
+ *
+ * Values only, not the token and header *shapes*: those are bounded by
+ * whitespace, so a reader that releases whole lines cannot cut one in half.
+ */
+export function openSecretStart(text: string, env: NodeJS.ProcessEnv = process.env): number {
+  let start = text.length;
+  for (const [, value] of secretEnvValues(env)) {
+    // A proper prefix is shorter than the value, so it can only begin inside
+    // the last `value.length - 1` characters; the first character narrows the
+    // scan to the few positions worth comparing.
+    const first = Math.max(0, text.length - value.length + 1);
+    for (let at = text.indexOf(value[0]!, first); at >= 0 && at < start; at = text.indexOf(value[0]!, at + 1)) {
+      if (value.startsWith(text.slice(at))) { start = at; break; }
+    }
+  }
+  return start;
+}