@sequenceholdings/studio-cli 0.1.13 → 0.1.21

package/dist/process/commands.js

@@ -11,18 +11,19 @@ import { fileURLToPath } from 'node:url';
 import { forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
 import { getJson, getJsonOr404, postJson, AtlasApiError } from '../atlas-client.js';
 import { generateProcessFiles } from './codegen.js';
-import { getAccessToken, NotLoggedInError } from '../auth.js';
+import { getAccessToken, getAccessTokenWithMode, NotLoggedInError, } from '../auth.js';
 import { readConfig, resolveEnvWithDiscovery } from '../config.js';
-import { buildBundleFromProcesses, summarizeBundle } from './build.js';
+import { finalizeCompiledBundle, summarizeBundle } from './build.js';
 import { buildResolveProcessPinFromEnv } from './resolve-process-pin.js';
 import { loadBundleForPublish } from './local-bundle.js';
-import { loadProcessDefinitions } from './discover.js';
-import { lintProcesses, formatLintResult } from './lint.js';
+import { findProcessRoot } from './discover.js';
+import { formatLintResult, lintSerializedAgentContracts, } from './lint.js';
 import { diffBundleAgainstActive, formatPlanDiff, } from './plan-diff.js';
-import { simulateProcess, formatSimulateResult } from './simulate.js';
+import { formatSimulateResult } from './simulate.js';
 import { buildAgentSchemaLoader } from './agent-loader.js';
-import { resolveArtifactSource, } from '@sequenceholdings/artifact-studio/source-resolver';
+import { localGitMetadata, resolveArtifactSource, } from '@sequenceholdings/artifact-studio/source-resolver';
 import { prepareProcessBuildRoot } from './repo-install.js';
+import { compileProcessSourceIsolated, simulateProcessIsolated, } from './compiler-subprocess.js';
 export function parseArgs(rest) {
     const positional = [];
     const flags = {};
@@ -98,7 +99,7 @@ async function getEnvAndToken(args) {
     const env = await resolveEnvWithDiscovery({ requested });
     let token;
     try {
-        token = await getAccessToken();
+        token = await getAccessToken({ env: env.name, targetUrl: env.url });
     }
     catch (err) {
         if (err instanceof NotLoggedInError) {
@@ -108,6 +109,12 @@ async function getEnvAndToken(args) {
     }
     return { env, token };
 }
+async function getEnvAndAuth(args) {
+    const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
+    const env = await resolveEnvWithDiscovery({ requested });
+    const auth = await getAccessTokenWithMode({ env: env.name, targetUrl: env.url });
+    return { authMode: auth.authMode, env, token: auth.token };
+}
 /**
  * Parse the process-apply source flags. `--repo processes/<name>` materializes
  * from the platform git service; absent means local (cwd / LATTICE_PROCESSES_ROOT).
@@ -206,9 +213,11 @@ function slugify(value) {
 // lint
 // ---------------------------------------------------------------------------
 export async function lintCommand(args) {
-    const defs = await loadProcessDefinitions();
-    const loadAgentSchemaEdgeIdEnum = await tryBuildAgentLoader(args);
-    const result = await lintProcesses({ defs, loadAgentSchemaEdgeIdEnum });
+    const compiled = await compileLocalProcessSource();
+    const result = await lintCompiledProcessSource({
+        compiled,
+        loadAgentSchemaEdgeIdEnum: await tryBuildAgentLoader(args),
+    });
     const formatted = formatLintResult(result);
     if (formatted.text)
         console.log(formatted.text);
@@ -216,9 +225,29 @@ export async function lintCommand(args) {
         console.error(`\nlint FAILED — ${result.errors.length} error(s), ${result.warnings.length} warning(s)`);
         return 1;
     }
-    console.log(`\nlint ok — ${defs.length} process(es) checked, ${result.warnings.length} warning(s)`);
+    console.log(`\nlint ok — ${compiled.bundle.processes.length} process(es) checked, ${result.warnings.length} warning(s)`);
     return 0;
 }
+async function compileLocalProcessSource() {
+    const rootDir = await findProcessRoot();
+    return compileProcessSourceIsolated({
+        rootDir,
+        provenance: localGitMetadata(rootDir),
+    });
+}
+async function lintCompiledProcessSource({ compiled, loadAgentSchemaEdgeIdEnum, }) {
+    const agentLint = await lintSerializedAgentContracts({
+        bundle: compiled.bundle,
+        loadAgentSchemaEdgeIdEnum,
+        // The worker already performs source-local checks. The credential-owning
+        // parent only adds registry-dependent validation (or the offline warning).
+        includeStaticValidation: false,
+    });
+    return {
+        errors: [...compiled.lint.errors, ...agentLint.errors],
+        warnings: [...compiled.lint.warnings, ...agentLint.warnings],
+    };
+}
 async function tryBuildAgentLoader(args) {
     // Agent loader is only meaningful when we have a target env + token.
     // If either fails to resolve, skip the check; lint will emit a warning
@@ -234,23 +263,31 @@ async function tryBuildAgentLoader(args) {
 // ---------------------------------------------------------------------------
 // plan
 // ---------------------------------------------------------------------------
-async function buildBundleForPublish(args, defs, provenance) {
-    const hasSubprocess = defs.some((d) => d.process.nodes.some((n) => n.kind === 'subprocess'));
+async function buildBundleForPublish(args, compiled) {
+    let hasSubprocess = false;
+    for (const process of compiled.bundle.processes) {
+        forEachSerializedNode(process.nodes, (node) => {
+            if (node.kind === 'subprocess')
+                hasSubprocess = true;
+        });
+    }
+    if (!hasSubprocess)
+        return compiled.bundle;
     try {
         const { env, token } = await getEnvAndToken(args);
         const resolveProcessPin = buildResolveProcessPinFromEnv(env, token);
-        return await buildBundleFromProcesses(defs, { resolveProcessPin, provenance });
+        return await finalizeCompiledBundle({
+            bundle: compiled.bundle,
+            resolveProcessPin,
+        });
     }
     catch (err) {
-        if (hasSubprocess) {
-            throw new Error('subprocess nodes require -e <env> and `seq-studio login` to resolve child process versions', { cause: err });
-        }
-        return await buildBundleFromProcesses(defs, { provenance });
+        throw new Error('subprocess nodes require -e <env> and `seq-studio login` to resolve child process versions', { cause: err });
     }
 }
 export async function planCommand(args) {
-    const defs = await loadProcessDefinitions();
-    const bundle = await buildBundleForPublish(args, defs);
+    const compiled = await compileLocalProcessSource();
+    const bundle = await buildBundleForPublish(args, compiled);
     const summary = summarizeBundle(bundle);
     console.log(JSON.stringify(summary, null, 2));
     const loadActiveProcess = await tryBuildActiveProcessLoader(args);
@@ -302,9 +339,11 @@ async function tryBuildActiveProcessLoader(args) {
 // test (CI wrapper)
 // ---------------------------------------------------------------------------
 export async function testCommand(args) {
-    const defs = await loadProcessDefinitions();
-    const loadAgentSchemaEdgeIdEnum = await tryBuildAgentLoader(args);
-    const lintResult = await lintProcesses({ defs, loadAgentSchemaEdgeIdEnum });
+    const compiled = await compileLocalProcessSource();
+    const lintResult = await lintCompiledProcessSource({
+        compiled,
+        loadAgentSchemaEdgeIdEnum: await tryBuildAgentLoader(args),
+    });
     const formattedLint = formatLintResult(lintResult);
     if (formattedLint.text)
         console.log(formattedLint.text);
@@ -312,8 +351,8 @@ export async function testCommand(args) {
         console.error(`\nlint FAILED — ${lintResult.errors.length} error(s), ${lintResult.warnings.length} warning(s)`);
         return 1;
     }
-    console.log(`\nlint ok — ${defs.length} process(es) checked, ${lintResult.warnings.length} warning(s)`);
-    const bundle = await buildBundleForPublish(args, defs);
+    console.log(`\nlint ok — ${compiled.bundle.processes.length} process(es) checked, ${lintResult.warnings.length} warning(s)`);
+    const bundle = await buildBundleForPublish(args, compiled);
     const offline = args.flags.offline === true;
     const loadActiveProcess = await tryBuildActiveProcessLoader(args);
     if (!loadActiveProcess) {
@@ -376,32 +415,34 @@ export async function applyCommand(args) {
     return applyLocal(args);
 }
 async function applyLocal(args) {
+    const compiled = await compileLocalProcessSource();
     const { env, token } = await getEnvAndToken(args);
-    const defs = await loadProcessDefinitions();
-    return registerAndPromote({ args, env, token, defs });
+    return registerAndPromote({ args, env, token, compiled });
 }
 async function applyFromRepo(args, spec) {
-    const { env, token } = await getEnvAndToken(args);
-    const source = await resolveArtifactSource({ kind: 'git-service', namespace: spec.namespace, name: spec.name, ref: spec.ref }, { baseUrl: env.url, token });
+    const { authMode, env, token } = await getEnvAndAuth(args);
+    const source = await resolveArtifactSource({ kind: 'git-service', namespace: spec.namespace, name: spec.name, ref: spec.ref }, { authMode, baseUrl: env.url, token });
     try {
         await prepareProcessBuildRoot(source.dir);
-        const defs = await loadProcessDefinitions(source.dir);
+        const compiled = await compileProcessSourceIsolated({
+            rootDir: source.dir,
+            provenance: source.provenance,
+        });
         return await registerAndPromote({
             args,
             env,
             token,
-            defs,
-            provenance: source.provenance,
+            compiled,
         });
     }
     finally {
         await source.cleanup();
     }
 }
-async function registerAndPromote({ args, env, token, defs, provenance, }) {
+async function registerAndPromote({ args, env, token, compiled, }) {
     const onlyResult = resolveOnlyIds({
         only: args.flags.only,
-        knownIds: new Set(defs.map((d) => d.process.id)),
+        knownIds: new Set(compiled.bundle.processes.map((process) => process.id)),
     });
     if (onlyResult.error) {
         console.error(onlyResult.error);
@@ -412,7 +453,10 @@ async function registerAndPromote({ args, env, token, defs, provenance, }) {
     // again on POST /bundles; this is a local fast-fail so we don't ship
     // a bundle that will be rejected.
     const loadAgentSchemaEdgeIdEnum = buildAgentSchemaLoader({ baseUrl: env.url, token });
-    const lintResult = await lintProcesses({ defs, loadAgentSchemaEdgeIdEnum });
+    const lintResult = await lintCompiledProcessSource({
+        compiled,
+        loadAgentSchemaEdgeIdEnum,
+    });
     const formatted = formatLintResult(lintResult);
     if (formatted.text)
         console.log(formatted.text);
@@ -420,7 +464,7 @@ async function registerAndPromote({ args, env, token, defs, provenance, }) {
         console.error('\napply FAILED — lint rejected the bundle');
         return 1;
     }
-    const bundle = await buildBundleForPublish(args, defs, provenance);
+    const bundle = await buildBundleForPublish(args, compiled);
     console.log(`[seq-studio] built bundle ${bundle.bundle_hash.slice(0, 12)} ` +
         `(${bundle.processes.length} process(es))`);
     // We send only the bundle. `created_by` (and `promoted_by` for the
@@ -569,8 +613,8 @@ export async function bundleCommand(args) {
     const sub = args.positional[0];
     switch (sub) {
         case 'build': {
-            const defs = await loadProcessDefinitions();
-            const bundle = await buildBundleForPublish(args, defs);
+            const compiled = await compileLocalProcessSource();
+            const bundle = await buildBundleForPublish(args, compiled);
             const out = typeof args.flags.out === 'string' ? resolve(args.flags.out) : null;
             if (out) {
                 await mkdir(dirname(out), { recursive: true });
@@ -705,14 +749,15 @@ export async function simulateCommand(args) {
         console.error('usage: seq-studio process simulate <process-id>');
         return 1;
     }
-    const defs = await loadProcessDefinitions();
-    const def = defs.find((d) => d.process.id === processId);
-    if (!def) {
-        console.error(`process "${processId}" not found in lattice process roots`);
+    const simulation = await simulateProcessIsolated({
+        rootDir: await findProcessRoot(),
+        processId,
+    });
+    if (simulation.kind === 'not-found') {
+        console.error(`process "${simulation.processId}" not found in lattice process roots`);
         return 1;
     }
-    const processesById = new Map(defs.map((d) => [d.process.id, d.process]));
-    const result = await simulateProcess({ process: def.process, processesById });
+    const result = simulation.result;
     console.log(formatSimulateResult(result));
     return result.status === 'failed' ? 1 : 0;
 }
@@ -748,7 +793,7 @@ export async function doctorCommand(args) {
     }
     let token = null;
     try {
-        token = await getAccessToken();
+        token = await getAccessToken({ env: env?.name, targetUrl: env?.url });
         lines.push('auth: ok — seqapi token present and not expired');
     }
     catch (err) {
@@ -812,9 +857,14 @@ export async function doctorCommand(args) {
             const currentTotal = current.total ?? current.items.length;
             if (currentTotal === 0 && env.name !== 'staging' && config?.envs.staging?.url) {
                 try {
+                    const stagingUrl = config.envs.staging.url;
+                    const stagingToken = await getAccessToken({
+                        env: 'staging',
+                        targetUrl: stagingUrl,
+                    });
                     const staging = await getJson({
-                        baseUrl: config.envs.staging.url,
-                        token,
+                        baseUrl: stagingUrl,
+                        token: stagingToken,
                         path: '/api/git-service/repos?limit=1&offset=0',
                     });
                     const stagingTotal = staging.total ?? staging.items.length;

package/dist/process/compiler-subprocess.d.ts

@@ -0,0 +1,29 @@
+import type { LatticeBundle } from '@sequenceholdings/lattice/bundle';
+import type { BuildBundleOptions } from './build.js';
+import type { LintResult } from './lint.js';
+import type { SimulateResult } from './simulate.js';
+export interface CompiledProcessSource {
+    bundle: LatticeBundle;
+    lint: LintResult;
+}
+export type IsolatedSimulation = {
+    kind: 'not-found';
+    processId: string;
+} | {
+    kind: 'result';
+    result: SimulateResult;
+};
+export declare function compileProcessSourceIsolated({ rootDir, provenance, workerPath, timeoutMs, sourceEnv, }: {
+    rootDir: string;
+    provenance?: NonNullable<BuildBundleOptions['provenance']>;
+    workerPath?: string;
+    timeoutMs?: number;
+    sourceEnv?: NodeJS.ProcessEnv;
+}): Promise<CompiledProcessSource>;
+export declare function simulateProcessIsolated({ rootDir, processId, workerPath, timeoutMs, sourceEnv, }: {
+    rootDir: string;
+    processId: string;
+    workerPath?: string;
+    timeoutMs?: number;
+    sourceEnv?: NodeJS.ProcessEnv;
+}): Promise<IsolatedSimulation>;

package/dist/process/compiler-subprocess.js

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createScrubbedChildEnv } from '@sequenceholdings/artifact-studio/child-environment';
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const BUILT_WORKER_PATH = join(MODULE_DIR, 'compiler-worker.js');
+const DEFAULT_WORKER_PATH = existsSync(BUILT_WORKER_PATH)
+    ? BUILT_WORKER_PATH
+    : join(MODULE_DIR, 'compiler-worker.ts');
+const DEFAULT_TIMEOUT_MS = 2 * 60_000;
+const MAX_STDERR_BYTES = 1024 * 1024;
+export async function compileProcessSourceIsolated({ rootDir, provenance, workerPath = DEFAULT_WORKER_PATH, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv, }) {
+    return runProcessWorker({
+        request: {
+            action: 'compile',
+            rootDir,
+            ...(provenance ? { provenance } : {}),
+        },
+        workerPath,
+        timeoutMs,
+        ...(sourceEnv ? { sourceEnv } : {}),
+    });
+}
+export async function simulateProcessIsolated({ rootDir, processId, workerPath = DEFAULT_WORKER_PATH, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv, }) {
+    return runProcessWorker({
+        request: { action: 'simulate', rootDir, processId },
+        workerPath,
+        timeoutMs,
+        ...(sourceEnv ? { sourceEnv } : {}),
+    });
+}
+async function runProcessWorker({ request, workerPath, timeoutMs, sourceEnv, }) {
+    const scratch = await mkdtemp(join(tmpdir(), 'process-compiler-'));
+    const requestFile = join(scratch, 'request.json');
+    const outFile = join(scratch, 'result.json');
+    const homeDir = join(scratch, 'home');
+    try {
+        await mkdir(homeDir, { recursive: true });
+        await writeFile(requestFile, JSON.stringify(request), 'utf8');
+        await runWorker({
+            workerPath,
+            requestFile,
+            outFile,
+            homeDir,
+            timeoutMs,
+            ...(sourceEnv ? { sourceEnv } : {}),
+        });
+        return JSON.parse(await readFile(outFile, 'utf8'));
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+function runWorker({ workerPath, requestFile, outFile, homeDir, timeoutMs, sourceEnv, }) {
+    return new Promise((resolve, reject) => {
+        const workerArgs = workerPath.endsWith('.ts')
+            ? ['--import', 'tsx', workerPath, requestFile, outFile]
+            : [workerPath, requestFile, outFile];
+        const child = spawn(process.execPath, workerArgs, {
+            stdio: ['ignore', 'inherit', 'pipe'],
+            env: createScrubbedChildEnv({
+                homeDir,
+                ...(sourceEnv ? { source: sourceEnv } : {}),
+            }),
+        });
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.stderr.on('data', (chunk) => {
+            if (stderr.length < MAX_STDERR_BYTES) {
+                stderr += chunk.toString().slice(0, MAX_STDERR_BYTES - stderr.length);
+            }
+        });
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                reject(new Error(`process compiler exceeded ${Math.round(timeoutMs / 1000)}s and was terminated`));
+                return;
+            }
+            if (code === 0) {
+                if (stderr.trim())
+                    process.stderr.write(stderr);
+                resolve();
+                return;
+            }
+            reject(new Error(stderr.trim() || `process compiler exited with code ${code ?? 'null'}`));
+        });
+    });
+}

package/dist/process/compiler-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/process/compiler-worker.js

@@ -0,0 +1,38 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { buildBundleFromProcesses } from './build.js';
+import { loadProcessDefinitions } from './discover.js';
+import { lintProcesses } from './lint.js';
+import { simulateProcess } from './simulate.js';
+async function main() {
+    const [requestFile, outFile] = process.argv.slice(2);
+    if (!requestFile || !outFile) {
+        process.stderr.write('usage: compiler-worker <request.json> <result.json>\n');
+        process.exitCode = 2;
+        return;
+    }
+    const request = JSON.parse(await readFile(requestFile, 'utf8'));
+    const defs = await loadProcessDefinitions(request.rootDir);
+    if (request.action === 'simulate') {
+        const process = defs.find((definition) => definition.process.id === request.processId)?.process;
+        if (!process) {
+            await writeFile(outFile, JSON.stringify({ kind: 'not-found', processId: request.processId }), 'utf8');
+            return;
+        }
+        const processesById = new Map(defs.map((definition) => [definition.process.id, definition.process]));
+        const result = await simulateProcess({ process, processesById });
+        await writeFile(outFile, JSON.stringify({ kind: 'result', result }), 'utf8');
+        return;
+    }
+    const lint = await lintProcesses({
+        defs,
+        suppressUnavailableAgentWarnings: true,
+    });
+    const bundle = await buildBundleFromProcesses(defs, {
+        ...(request.provenance ? { provenance: request.provenance } : {}),
+    });
+    await writeFile(outFile, JSON.stringify({ bundle, lint }), 'utf8');
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/process/lint.d.ts

@@ -9,6 +9,7 @@
  *   - Human timeout edge — if timeout is set and outgoing_edges.length > 0
  *     but on_timeout_edge_id is unset, warn
  */
+import { type LatticeBundle } from '@sequenceholdings/lattice/bundle';
 import type { ProcessDefinition } from '@sequenceholdings/lattice/define';
 export interface LintIssue {
     process_id: string;
@@ -31,8 +32,15 @@ export interface LintInput {
      * undefined and a warning is emitted instead of failing the build.
      */
     loadAgentSchemaEdgeIdEnum?: (agentId: string) => Promise<string[] | null | 'not-found'>;
+    /** A scrubbed worker can defer registry-backed agent checks to its parent. */
+    suppressUnavailableAgentWarnings?: boolean;
 }
 export declare function lintProcesses(input: LintInput): Promise<LintResult>;
+export declare function lintSerializedAgentContracts({ bundle, loadAgentSchemaEdgeIdEnum, includeStaticValidation, }: {
+    bundle: LatticeBundle;
+    loadAgentSchemaEdgeIdEnum?: LintInput['loadAgentSchemaEdgeIdEnum'];
+    includeStaticValidation?: boolean;
+}): Promise<LintResult>;
 export declare function formatLintResult(result: LintResult): {
     text: string;
     hasErrors: boolean;

package/dist/process/lint.js

@@ -10,6 +10,7 @@
  *     but on_timeout_edge_id is unset, warn
  */
 import { readFileSync } from 'node:fs';
+import { forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
 import { parallelSubNodes, validateEmailReminders } from '@sequenceholdings/lattice/define';
 export async function lintProcesses(input) {
     const errors = [];
@@ -67,7 +68,7 @@ export async function lintProcesses(input) {
             }
         }
         for (const node of p.nodes) {
-            await lintNodeContract(p.id, node, errors, warnings, input.loadAgentSchemaEdgeIdEnum);
+            await lintNodeContract(p.id, node, errors, warnings, input.loadAgentSchemaEdgeIdEnum, input.suppressUnavailableAgentWarnings ?? false);
         }
         // Closure-scope check: mappers / fn / join / fan_out / output are
         // serialized via `.toString()` and run in a vm with NOTHING from the
@@ -213,10 +214,10 @@ function lintSandboxClosures(processId, node, importedNames, warnings) {
  * edge_id-contract checks as a top-level node) and lints the `join` reducer's
  * own edge_id returns against the parallel node's outgoing_edges.
  */
-async function lintNodeContract(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum) {
+async function lintNodeContract(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings) {
     switch (node.kind) {
         case 'agent':
-            await lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum);
+            await lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings);
             break;
         case 'human':
             lintHuman(processId, node, errors, warnings);
@@ -225,7 +226,7 @@ async function lintNodeContract(processId, node, errors, warnings, loadAgentSche
             const parallel = node;
             lintParallelJoin(processId, parallel, errors, warnings);
             for (const { node: sub } of parallelSubNodes(parallel)) {
-                await lintNodeContract(processId, sub, errors, warnings, loadAgentSchemaEdgeIdEnum);
+                await lintNodeContract(processId, sub, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings);
             }
             break;
         }
@@ -335,28 +336,74 @@ function lintSubprocessOutput(processId, node, errors, warnings) {
     }
 }
 const EDGE_ID_LITERAL_RE = /\bedge_id\s*:\s*['"`]([^'"`]+)['"`]/g;
-async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum) {
-    const allEdgeIds = node.outgoing_edges.map((e) => e.id);
-    // The reset edge (taken out-of-band by the reset intervention, never chosen
-    // by the agent) must exist on the node but is excluded from the agent's
-    // edge_id contract — same way a human node's on_timeout_edge_id is an
-    // orchestration-only edge. Validate membership, then verify the agent's
-    // edge_id enum against the REAL (non-reset) edges only.
-    if (node.on_reset_edge_id) {
-        if (!allEdgeIds.includes(node.on_reset_edge_id)) {
-            errors.push({
-                process_id: processId,
-                node_id: node.id,
-                message: `on_reset_edge_id "${node.on_reset_edge_id}" is not in outgoing_edges`,
-            });
-        }
+export async function lintSerializedAgentContracts({ bundle, loadAgentSchemaEdgeIdEnum, includeStaticValidation = true, }) {
+    const errors = [];
+    const warnings = [];
+    const pending = [];
+    for (const process of bundle.processes) {
+        forEachSerializedNode(process.nodes, (node) => {
+            const contract = serializedAgentContract(node);
+            if (!contract)
+                return;
+            pending.push(lintAgentContract({
+                processId: process.id,
+                nodeId: node.id,
+                ...contract,
+                errors,
+                warnings,
+                loadAgentSchemaEdgeIdEnum,
+                suppressUnavailableAgentWarnings: false,
+                includeStaticValidation,
+            }));
+        });
     }
-    const outgoingIds = allEdgeIds.filter((id) => id !== node.on_reset_edge_id);
+    await Promise.all(pending);
+    return { errors, warnings };
+}
+function serializedAgentContract(node) {
+    if (node.kind !== 'agent' || !isUnknownRecord(node.metadata))
+        return null;
+    const agentId = node.metadata.agent_id;
+    if (typeof agentId !== 'string')
+        return null;
+    const onResetEdgeId = node.metadata.on_reset_edge_id;
+    return {
+        agentId,
+        allEdgeIds: node.outgoing_edges.map((edge) => edge.id),
+        ...(typeof onResetEdgeId === 'string' ? { onResetEdgeId } : {}),
+    };
+}
+function isUnknownRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings) {
+    await lintAgentContract({
+        processId,
+        nodeId: node.id,
+        agentId: node.agent.id,
+        allEdgeIds: node.outgoing_edges.map((edge) => edge.id),
+        onResetEdgeId: node.on_reset_edge_id,
+        errors,
+        warnings,
+        loadAgentSchemaEdgeIdEnum,
+        suppressUnavailableAgentWarnings,
+        includeStaticValidation: true,
+    });
+}
+async function lintAgentContract({ processId, nodeId, agentId, allEdgeIds, onResetEdgeId, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings, includeStaticValidation, }) {
+    if (includeStaticValidation && onResetEdgeId && !allEdgeIds.includes(onResetEdgeId)) {
+        errors.push({
+            process_id: processId,
+            node_id: nodeId,
+            message: `on_reset_edge_id "${onResetEdgeId}" is not in outgoing_edges`,
+        });
+    }
+    const outgoingIds = allEdgeIds.filter((id) => id !== onResetEdgeId);
     if (!loadAgentSchemaEdgeIdEnum) {
-        if (outgoingIds.length > 1) {
+        if (outgoingIds.length > 1 && !suppressUnavailableAgentWarnings) {
             warnings.push({
                 process_id: processId,
-                node_id: node.id,
+                node_id: nodeId,
                 message: `agent node has ${outgoingIds.length} outgoing edges; agent output schema vs outgoing_edges contract not verified (no agent registry loader available)`,
             });
         }
@@ -364,21 +411,21 @@ async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeI
     }
     let enumValues;
     try {
-        enumValues = await loadAgentSchemaEdgeIdEnum(node.agent.id);
+        enumValues = await loadAgentSchemaEdgeIdEnum(agentId);
     }
     catch (err) {
         warnings.push({
             process_id: processId,
-            node_id: node.id,
-            message: `could not load agent definition "${node.agent.id}" to verify output contract: ${err instanceof Error ? err.message : String(err)} (run with DB access to enable full check)`,
+            node_id: nodeId,
+            message: `could not load agent definition "${agentId}" to verify output contract: ${err instanceof Error ? err.message : String(err)} (run with DB access to enable full check)`,
         });
         return;
     }
     if (enumValues === 'not-found') {
         errors.push({
             process_id: processId,
-            node_id: node.id,
-            message: `agent "${node.agent.id}" not found in the target env — sync/seed the agent registry before applying`,
+            node_id: nodeId,
+            message: `agent "${agentId}" not found in the target env — sync/seed the agent registry before applying`,
         });
         return;
     }
@@ -397,8 +444,8 @@ async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeI
     if (missing.length > 0 || extra.length > 0) {
         errors.push({
             process_id: processId,
-            node_id: node.id,
-            message: `agent "${node.agent.id}" edge_id enum mismatch — missing: [${missing.join(', ')}], extra: [${extra.join(', ')}]; expected exactly: [${outgoingIds.join(', ')}]`,
+            node_id: nodeId,
+            message: `agent "${agentId}" edge_id enum mismatch — missing: [${missing.join(', ')}], extra: [${extra.join(', ')}]; expected exactly: [${outgoingIds.join(', ')}]`,
         });
     }
 }
@@ -502,6 +549,14 @@ function lintHuman(processId, node, errors, warnings) {
         }
     }
     if (node.on_timeout_edge_id) {
+        if (node.timeout === undefined) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `on_timeout_edge_id "${node.on_timeout_edge_id}" requires timeout — ` +
+                    `omit on_timeout_edge_id for an indefinite wait, or set timeout to enable the timeout edge`,
+            });
+        }
         const ok = node.outgoing_edges.some((e) => e.id === node.on_timeout_edge_id);
         if (!ok) {
             errors.push({