@agilno-tech/rivet 0.1.0-alpha.0

package/src/commands/integration-setup.js

@@ -0,0 +1,65 @@
+import { CliError, EXIT_CODES } from '../cli/output.js';
+import { resolveConfiguredProject } from '../cli/project-discovery.js';
+import { prepareProviderAppend } from './init.js';
+import { createIntegrationRegistry } from '../integrations/registry.js';
+
+const KINDS=['jira','linear','figma','confluence'];
+const CAPS={jira:'issues-read',linear:'issues-read',figma:'files-read',confluence:'pages-read'};
+class Cancelled extends Error {}
+function fail(message,code='INVALID_INPUT'){throw new CliError(message,code);}
+function text(value){if(typeof value!=='string'||!value.length||value.length>2048||/[\u0000-\u001f\u007f]/.test(value))fail('Enter a bounded configuration value. Secret values must never be entered.');return value.trim();}
+function envName(value){const name=text(value);if(!/^[A-Z][A-Z0-9_]{1,127}$/.test(name))fail('Enter an environment variable NAME such as JIRA_API_TOKEN, never a credential value.');return name;}
+function csv(value,pattern){const values=text(value).split(',').map(item=>item.trim());if(values.length>64||values.some(item=>!pattern.test(item))||new Set(values).size!==values.length)fail('Enter unique comma-separated values in the requested format.');return values;}
+function endpoint(kind,value){
+  const result=text(value);let url;try{url=new URL(result);}catch{fail('Enter the HTTPS source origin only.');}
+  const host=kind==='linear'?url.hostname==='linear.app':kind==='figma'?['figma.com','www.figma.com'].includes(url.hostname):/^[a-z0-9][a-z0-9-]*\.atlassian\.net$/.test(url.hostname);
+  if(!host||url.protocol!=='https:'||url.username||url.password||url.port||url.pathname!=='/'||url.search||url.hash)fail('Use the supported HTTPS source origin with no credentials, path or query.');return url.origin;
+}
+export async function integrationSetup(parsed,dependencies){
+  if(parsed.operands.length||Object.keys(parsed.flags).some(key=>key!=='project'))fail('Use rivet integrations setup [--project=<path>] in an interactive terminal.');
+  if(dependencies.terminalIsInteractive?.()!==true||typeof dependencies.integrationSetupPrompt!=='function')fail('Run rivet integrations setup in an interactive terminal to preview and approve local settings.');
+  const project=await resolveConfiguredProject(dependencies.cwd(),parsed.flags.project,{env:dependencies.env,runner:dependencies.runGit});
+  let captured;try{captured=await prepareProviderAppend(project.root,{fs:dependencies.fs});}catch{fail('Existing project configuration is missing, invalid or unsafe. Run rivet setup first; existing files were preserved.','REPOSITORY_CONFLICT');}
+  const ask=async question=>{let answer;try{answer=await dependencies.integrationSetupPrompt(question);}catch{throw new Cancelled();}if(answer===null||answer===undefined)throw new Cancelled();return answer;};
+  const select=async(id,message,choices)=>{const answer=await ask({id,type:'select',message,choices});if(!choices.some(choice=>choice.value===answer))fail('Choose one of the displayed options.');return answer;};
+  const input=(id,message,defaultValue)=>ask({id,type:'input',message,...(defaultValue?{defaultValue}:{})});
+  const existing=captured.config.providers.providers,projectId=captured.config.project.id;
+  dependencies.output.log(`Project: ${projectId}\nExisting integrations preserved: ${existing.map(p=>p.id).join(', ')}`);
+  dependencies.output.log('This guide appends read-only local settings. It never requests credential values, authenticates tools or calls providers. Figma and Confluence are harness-MCP context sources in this workflow.');
+  try{
+    const kinds=await ask({id:'providers',type:'multi',message:'Which integrations would you like to add?',choices:KINDS.map(value=>({value,label:value==='confluence'?'Confluence context':value==='figma'?'Figma context':value==='jira'?'Jira tracker':'Linear tracker'}))});
+    if(!Array.isArray(kinds)||kinds.length>4||new Set(kinds).size!==kinds.length||kinds.some(kind=>!KINDS.includes(kind)))fail('Select the displayed integrations.');
+    if(!kinds.length)throw new Cancelled();
+    const added=[],ids=new Set(existing.map(p=>p.id));
+    for(const kind of kinds){
+      const transport=await select(kind+'.transport',`How will ${kind} be read?`,[
+        {value:'harness-mcp',label:'Connected harness tools (MCP)'},...(['jira','linear'].includes(kind)?[{value:'direct-api',label:'Direct API using environment references'}]:[])]);
+      if(transport==='direct-api'&&existing.some(p=>p.kind===kind&&(p.transport??'direct-api')==='direct-api'&&p.mode!=='disabled'&&p.capabilities.includes('issues-read')&&(!p.projectIds?.length||p.projectIds.includes(projectId))))fail(`An enabled direct ${kind} issue reader already matches this project. Adding another would make ticket intake ambiguous. Review the existing descriptor; the guide will not replace it.`,'REPOSITORY_CONFLICT');
+      const prefix=kind+(transport==='direct-api'?'-direct':'-mcp');let id=prefix,index=2;while(ids.has(id))id=prefix+'-'+index++;ids.add(id);
+      const descriptor={id,kind,mode:'read-only',transport,capabilities:[CAPS[kind]],projectIds:[projectId]};
+      if(kind==='linear'&&transport==='direct-api')descriptor.endpoint='https://api.linear.app';
+      else descriptor.endpoint=endpoint(kind,await input(kind+'.endpoint',`${kind} HTTPS source origin (no path, query or credentials)`,kind==='linear'?'https://linear.app':kind==='figma'?'https://www.figma.com':undefined));
+      const scope=await select(kind+'.scope',`Resource access for ${id} within project ${projectId}`,[{value:'selected',label:'Specific resource IDs'},{value:'all',label:'All provider-accessible resources for this project'}]);
+      descriptor.resourceIds=scope==='all'?[]:csv(await input(kind+'.resources',kind==='jira'||kind==='linear'?'Issue keys, comma-separated (for example DEMO-1, DEMO-2)':kind==='confluence'?'Confluence page IDs, comma-separated':'Figma file keys, comma-separated'),['jira','linear'].includes(kind)?/^[A-Z][A-Z0-9]{0,31}-[1-9][0-9]{0,15}$/:kind==='confluence'?/^[1-9][0-9]{0,19}$/:/^[A-Za-z0-9_-]{1,200}$/);
+      if(transport==='harness-mcp')descriptor.tools=csv(await input(kind+'.tools','Exact read tool names exposed by your harness, comma-separated; tool availability is not inferred'),/^[A-Za-z0-9_.:-]{1,128}$/);
+      else descriptor.credentials=kind==='jira'?{
+        usernameEnv:envName(await input(kind+'.usernameEnv','Environment variable NAME for your Jira email (never the email value)','JIRA_USERNAME')),
+        apiTokenEnv:envName(await input(kind+'.apiTokenEnv','Environment variable NAME for the Jira API token (never the token value)','JIRA_API_TOKEN')),
+      }:{apiTokenEnv:envName(await input(kind+'.apiTokenEnv','Environment variable NAME for the Linear API key (never the key value)','LINEAR_API_KEY'))};
+      added.push(descriptor);
+    }
+    let proposal;try{
+      const config={...captured.config,providers:{...captured.config.providers,providers:[...existing,...added]}};
+      createIntegrationRegistry({config,projectId});proposal=captured.propose(added);
+    }catch{fail('The proposed provider settings failed configuration validation. No files were written.');}
+    dependencies.output.log('Exact providers.yaml preview (existing descriptor values are preserved):\n'+proposal.providersYaml);
+    for(const provider of added)dependencies.output.log(`${provider.id}: project ${projectId}; ${provider.resourceIds.length?'only resource IDs: '+provider.resourceIds.join(', '):'all provider-accessible resources in this project; no resource ID filter'}. ${provider.transport==='harness-mcp'?'Tool names configured; current authenticated host inventory is still required.':'Credential references configured; environment values were not inspected.'}`);
+    dependencies.output.log('No network access or authentication was checked. Only .rivet/providers.yaml content changes; the other configuration files retain their exact bytes.');
+    const confirmed=await ask({id:'confirm',type:'confirm',message:'Write these local provider settings?'});
+    if(confirmed!==true)throw new Cancelled();
+    let cleanup;try{cleanup=await proposal.commit();}catch(error){throw new CliError('Provider settings were not committed safely. Inspect concurrent edits, initialization locks or transaction recovery; do not force an overwrite.','REPOSITORY_CONFLICT',{cause:error});}
+    dependencies.output.log('Local provider settings written. Review and commit the configuration, then run rivet integrations check. Connected tool inventory and credentials remain separate.');
+    if(cleanup.residueCount)dependencies.output.log(cleanup.warning??cleanup.remediation);
+    return EXIT_CODES.SUCCESS;
+  }catch(error){if(error instanceof Cancelled){dependencies.output.log('Integration setup cancelled. No configuration changes were written.');return EXIT_CODES.SUCCESS;}throw error;}
+}

package/src/commands/integrations.js

@@ -0,0 +1,54 @@
+import { resolve } from 'node:path';
+import { loadProjectConfig } from '../config/load.js';
+import { createIntegrationRegistry } from '../integrations/registry.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+
+function readHostInventory(flags, dependencies) {
+  const inline = flags['host-inventory-json'];
+  if (inline === undefined) return dependencies.integrationHost;
+  if (dependencies.integrationHost !== undefined) {
+    throw new CliError('Supply host inventory once, through the CLI or host adapter.', 'INVALID_INPUT');
+  }
+  if (typeof inline !== 'string' || Buffer.byteLength(inline, 'utf8') > 65536) {
+    throw new CliError('Host inventory must be JSON of at most 64 KiB.', 'INVALID_INPUT');
+  }
+  try {
+    return JSON.parse(inline);
+  } catch {
+    throw new CliError('Host inventory must be valid JSON.', 'INVALID_INPUT');
+  }
+}
+
+export async function integrationsCommand(parsed, dependencies) {
+  const { subcommand, operands, flags } = parsed;
+  if (subcommand === 'setup') return (await import('./integration-setup.js')).integrationSetup(parsed, dependencies);
+  if (!['list', 'check'].includes(subcommand) || operands.length
+    || Object.keys(flags).some(key => !['project', 'json', 'host-inventory-json'].includes(key))) {
+    throw new CliError('Use rivet integrations list or check [--project=<path>] [--host-inventory-json=<json>] [--json].', 'INVALID_INPUT');
+  }
+  const host = readHostInventory(flags, dependencies);
+  const projectRoot = resolve(flags.project ?? dependencies.cwd?.() ?? process.cwd());
+  let config;
+  try {
+    config = await (dependencies.configLoader ?? loadProjectConfig)(projectRoot);
+  } catch {
+    throw new CliError('Project configuration is missing or invalid.', 'MISSING_CONFIGURATION');
+  }
+  let result;
+  try {
+    const registry = createIntegrationRegistry({
+      config,
+      projectId: config.project.id,
+      environment: dependencies.env ?? process.env,
+      host,
+    });
+    result = { integrations: registry[subcommand](), networkChecked: false };
+  } catch {
+    throw new CliError('Integration configuration or supplied host inventory is invalid.', 'INVALID_INPUT');
+  }
+  if (flags.json) dependencies.output.json({ ok: true, result });
+  else dependencies.output.log(result.integrations.map(item =>
+    `${item.id} (${item.transport}): ${item.readiness}. ${item.remedy}`).join('\n'));
+  // Diagnostic completion is success even when an optional integration is unavailable.
+  return EXIT_CODES.SUCCESS;
+}

package/src/commands/models.js

@@ -0,0 +1,158 @@
+import { resolveRoleProfile } from '../models/profiles.js';
+import { humanRunCommand } from './human-run.js';
+import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { delegateText, ModelDelegationError } from '../models/delegate.js';
+import { buildModelRequest } from '../models/protocols.js';
+import { containsSecretMaterial } from '../clients/contract.js';
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createModelRegistry } from '../models/registry.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+
+async function readProfile(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const metadata = await handle.stat();
+    if (!metadata.isFile() || metadata.size > 64 * 1024) throw new Error();
+    const buffer = Buffer.alloc(64 * 1024 + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    if (offset > 64 * 1024) throw new Error();
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, offset)));
+  } catch { throw new CliError('Model profile must be a valid JSON file of at most 64 KiB.', 'INVALID_INPUT'); }
+  finally { await handle?.close(); }
+}
+
+export async function modelsCommand(parsed, dependencies) {
+  const { subcommand, operands, flags } = parsed;
+  if (subcommand === 'role') {
+    if (operands.length || typeof flags.roles !== 'string' || typeof flags.role !== 'string'
+      || Object.keys(flags).some(key => !['roles', 'role', 'json'].includes(key))) throw new CliError('Use rivet models role --roles=<file> --role=<name> [--json].', 'INVALID_INPUT');
+    const result = await readRole(flags, dependencies);
+    if (flags.json) dependencies.output.json({ ok: true, result });
+    else dependencies.output.log(`Role ${result.role}: ${result.target.kind}. This inspection does not execute work.`);
+    return EXIT_CODES.SUCCESS;
+  }
+  if (subcommand === 'delegate') return delegateCommand(parsed, dependencies);
+  if (operands.length || !['list', 'check'].includes(subcommand)
+    || Object.keys(flags).some(key => !['json', 'profile'].includes(key))
+    || (subcommand === 'list' && flags.profile !== undefined)
+    || (subcommand === 'check' && typeof flags.profile !== 'string')) {
+    throw new CliError('Use rivet models list or rivet models check --profile=<file>.', 'INVALID_INPUT');
+  }
+  const registry = createModelRegistry();
+  let result;
+  if (subcommand === 'list') result = { providers: registry.list() };
+  else {
+    const input = await readProfile(resolve(dependencies.cwd(), flags.profile));
+    try { result = registry.resolve(input); }
+    catch { throw new CliError('Invalid model profile. Check the provider, model, limits, endpoint and credential reference.', 'INVALID_INPUT'); }
+  }
+  if (flags.json) dependencies.output.json({ ok: true, result });
+  else if (subcommand === 'list') {
+    dependencies.output.log(result.providers.map(provider => `${provider.id}: ${provider.label} (${provider.kind}; ${provider.execution}; not live verified)`).join('\n'));
+  } else {
+    dependencies.output.log(`Profile valid: ${result.profile.provider} / ${result.profile.model}. Execution is not ready: ${result.reasons.join(', ')}. No model was called.`);
+  }
+  return EXIT_CODES.SUCCESS;
+}
+
+const UNSAFE_DISPLAY = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u;
+async function delegateCommand({ operands, flags }, dependencies) {
+  const invalid = message => { throw new CliError(message, 'INVALID_INPUT'); };
+  const roleMode = typeof flags.roles === 'string' && typeof flags.role === 'string' && flags.profile === undefined;
+  const profileMode = typeof flags.profile === 'string' && flags.roles === undefined && flags.role === undefined;
+  if (operands.length !== 1 || (!roleMode && !profileMode)
+    || Object.keys(flags).some(key => !(roleMode ? ['roles', 'role', 'project'] : ['profile']).includes(key))
+    || !dependencies.terminalIsInteractive()) {
+    invalid('Use rivet models delegate "prompt" with --profile=<file> or --roles=<file> --role=<name> in an interactive terminal.');
+  }
+  const prompt = operands[0];
+  if (typeof prompt !== 'string' || !prompt.trim() || Buffer.byteLength(prompt) > 64 * 1024
+    || UNSAFE_DISPLAY.test(prompt) || containsSecretMaterial(prompt)) invalid('Use a prompt of at most 64 KiB without secrets or terminal control characters.');
+  const selection = roleMode ? await readRole(flags, dependencies) : undefined;
+  if (roleMode) dependencies.output.log(`Role ${selection.role}: ${selection.target.kind}`);
+  if (selection?.target.kind === 'active-harness') {
+    if (flags.project !== undefined) invalid('--project applies only to a delegated harness task.');
+    dependencies.output.log('Continue this request in your active harness through the Rivet workflow. No model or process was started; the task has not been performed.');
+    return EXIT_CODES.SUCCESS;
+  }
+  if (selection?.target.kind === 'harness') {
+    const unchanged = async () => {
+      if (!isDeepStrictEqual(selection, await readRole(flags, dependencies))) invalid('Role selection changed. Run the command again.');
+    };
+    await unchanged();
+    return humanRunCommand({ command: 'run', subcommand: null, operands, flags: {
+      harness: selection.target.harness, ...(flags.project === undefined ? {} : { project: flags.project }),
+    } }, { ...dependencies, confirmFeatureActivation: async (proposal, options) => {
+      await unchanged();
+      const approved = await dependencies.confirmFeatureActivation(proposal, options);
+      await unchanged();
+      return approved;
+    } });
+  }
+  if (flags.project !== undefined) invalid('--project applies only to a delegated harness task.');
+  const path = profileMode ? resolve(dependencies.cwd(), flags.profile) : undefined;
+  const resolveProfile = async () => {
+    if (roleMode) {
+      const current = await readRole(flags, dependencies);
+      if (!isDeepStrictEqual(selection, current)) invalid('Role selection changed. Run the command again.');
+      return current.target.profile;
+    }
+    const input = await readProfile(path);
+    try { return createModelRegistry().resolve(input, { requiredCapabilities: ['text'] }).profile; }
+    catch { invalid('Invalid model profile.'); }
+  };
+  const profile = await resolveProfile();
+  if (profile.maxCostUsd !== undefined) invalid('Monetary caps cannot be enforced for direct text delegation.');
+  if (profile.timeoutMs > 120000) invalid('Direct text delegation requires timeoutMs at most 120000.');
+  let url;
+  try { url = buildModelRequest(profile, prompt, 'preview-only').url; }
+  catch { invalid('This profile does not support direct text delegation. Check its provider and endpoint.'); }
+  if (UNSAFE_DISPLAY.test(profile.model)) invalid('Model names must not contain terminal control characters.');
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  const external = dependencies.models?.signal;
+  if (external?.aborted) controller.abort();
+  external?.addEventListener('abort', abort, { once: true });
+  process.on('SIGINT', abort); process.on('SIGTERM', abort);
+  let timer;
+  try {
+    if (controller.signal.aborted) invalid('Text delegation cancelled.');
+    const preview = Object.freeze({ profile, prompt, url });
+    dependencies.output.log(`Text delegation: ${profile.provider} / ${profile.model}\nDestination: ${url}\nLimits: ${profile.timeoutMs} ms, ${profile.maxOutputTokens} output tokens\nExact prompt:\n${prompt}`);
+    const cancelled = new Promise(resolvePromise => {
+      controller.signal.addEventListener('abort', () => resolvePromise(false), { once: true });
+      timer = setTimeout(() => { controller.abort(); resolvePromise(false); }, 30000);
+    });
+    const approved = await Promise.race([dependencies.confirmModelDelegation(preview, { signal: controller.signal }), cancelled]);
+    clearTimeout(timer);
+    if (approved !== true || controller.signal.aborted) invalid('Text delegation cancelled.');
+    if (!isDeepStrictEqual(profile, await resolveProfile())) invalid('Model profile changed after approval. Run the command again.');
+    if (controller.signal.aborted) invalid('Text delegation cancelled.');
+    const result = await (dependencies.models?.delegateText ?? delegateText)({ profile, prompt,
+      environment: dependencies.env, signal: controller.signal });
+    const text = result.text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, '');
+    const model = result.model.replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, '');
+    dependencies.output.log(`Unverified advisory output (${model}; input ${result.usage.inputTokens}, output ${result.usage.outputTokens} tokens):\n${text}`);
+    return EXIT_CODES.SUCCESS;
+  } catch (error) {
+    if (error instanceof ModelDelegationError) throw new CliError(error.safeMessage, 'INVALID_INPUT');
+    throw error;
+  } finally {
+    clearTimeout(timer); external?.removeEventListener('abort', abort);
+    process.removeListener('SIGINT', abort); process.removeListener('SIGTERM', abort);
+  }
+}
+
+async function readRole(flags, dependencies) {
+  const input = await readProfile(resolve(dependencies.cwd(), flags.roles));
+  try { return resolveRoleProfile(input, flags.role); }
+  catch { throw new CliError('Invalid model role configuration or role name.', 'INVALID_INPUT'); }
+}

package/src/commands/orchestrate.js

@@ -0,0 +1,61 @@
+import { watchOrchestration } from '../runtime/supervisor.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+
+export async function orchestrateRun(runtime, instance, options) { return runtime.tick(instance, options); }
+export async function orchestrateWatch(runtime, instance, options) { return watchOrchestration(runtime, instance, options); }
+
+function cliFailure(message, code = 'INVALID_INPUT') { throw new CliError(message, code); }
+function cliInteger(value, name, { minimum = 0, maximum = Number.MAX_SAFE_INTEGER } = {}) {
+  const parsed = typeof value === 'string' && /^(?:0|[1-9][0-9]*)$/.test(value) ? Number(value) : value;
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) cliFailure(`Orchestrate option '${name}' is invalid.`);
+  return parsed;
+}
+function cliInput(parsed, dependencies) {
+  if (!parsed || parsed.command !== 'orchestrate' || !['run', 'watch'].includes(parsed.subcommand)
+    || !Array.isArray(parsed.operands) || parsed.operands.length !== 1
+    || typeof parsed.operands[0] !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(parsed.operands[0])
+    || parsed.operands[0].length > 64) cliFailure('Orchestrate commands require one explicit private instance ID.');
+  const allowed = parsed.subcommand === 'run'
+    ? ['json', 'expected-version', 'max-active-nodes']
+    : ['json', 'expected-version', 'interval-ms', 'max-ticks', 'deadline-ms'];
+  if (!parsed.flags || Object.keys(parsed.flags).some(key => !allowed.includes(key))) cliFailure('Orchestrate command options are invalid.');
+  const context = dependencies?.orchestration;
+  if (!context || typeof context.resolveInstance !== 'function' || !context.runtime || typeof context.runtime.tick !== 'function') cliFailure('Private orchestration is not configured.', 'MISSING_CONFIGURATION');
+  return { context, instanceId: parsed.operands[0] };
+}
+function emitCliResult(parsed, dependencies, result) {
+  const payload = { ok: true, command: 'orchestrate', subcommand: parsed.subcommand, result };
+  if (parsed.flags.json) dependencies.output.json(payload);
+  else dependencies.output.log(`Orchestration ${parsed.subcommand}: ${result.terminal ?? 'running'}.`);
+  return EXIT_CODES.SUCCESS;
+}
+
+export async function orchestrateCommand(parsed, dependencies) {
+  const { context, instanceId } = cliInput(parsed, dependencies);
+  const expectedVersion = cliInteger(parsed.flags['expected-version'], 'expected-version');
+  let options;
+  if (parsed.subcommand === 'run') {
+    options = { expectedVersion };
+    if (parsed.flags['max-active-nodes'] !== undefined) options.maxActiveNodes = cliInteger(parsed.flags['max-active-nodes'], 'max-active-nodes', { minimum: 1, maximum: 64 });
+  } else {
+    if (typeof context.now !== 'function' || typeof context.wait !== 'function') cliFailure('Orchestration watch dependencies are not configured.', 'MISSING_CONFIGURATION');
+    options = {
+      expectedVersion,
+      intervalMs: cliInteger(parsed.flags['interval-ms'], 'interval-ms', { minimum: 1, maximum: 60_000 }),
+      maxTicks: cliInteger(parsed.flags['max-ticks'], 'max-ticks', { minimum: 1, maximum: 10_000 }),
+      deadlineMs: cliInteger(parsed.flags['deadline-ms'], 'deadline-ms'),
+      now: context.now,
+      wait: context.wait,
+      ...(context.signal === undefined ? {} : { signal: context.signal }),
+    };
+  }
+  const instance = await context.resolveInstance(instanceId);
+  if (!instance || instance.id !== instanceId) cliFailure('Private orchestration instance is unavailable.', 'MISSING_CONFIGURATION');
+  let result;
+  if (parsed.subcommand === 'run') {
+    result = await orchestrateRun(context.runtime, instance, options);
+  } else {
+    result = await orchestrateWatch(context.runtime, instance, options);
+  }
+  return emitCliResult(parsed, dependencies, result);
+}

package/src/commands/preflight.js

@@ -0,0 +1,125 @@
+import { join, resolve } from 'node:path';
+
+import { EXIT_CODES } from '../cli/output.js';
+import { loadProjectConfig } from '../config/load.js';
+import { discoverGit } from '../discovery/git.js';
+import { discoverTools } from '../discovery/tools.js';
+import { diagnoseDoctor } from './doctor.js';
+
+function check(id, passed, remediation, details = {}) {
+  return { id, status: passed ? 'pass' : 'fail', ...details, ...(passed ? {} : { remediation }) };
+}
+
+function emit(output, json, payload, exitCode) {
+  if (json) {
+    output.json(payload, exitCode === EXIT_CODES.SUCCESS ? 'stdout' : 'stderr');
+  } else if (exitCode === EXIT_CODES.SUCCESS) {
+    output.log(`Preflight: ${payload.status}.${payload.dependencyPreparation==='required'?' Dependencies require separate approval and installation in the isolated task checkout before checks can run.':''}`);
+  } else {
+    output.error(`Preflight: ${payload.status}. ${payload.remediations.join(' ')}`);
+  }
+  return exitCode;
+}
+
+function defaultGoalState() {
+  return { status: 'not_initialized' };
+}
+
+export async function preflight(parsed, dependencies = {}) {
+  const json = parsed.flags.json === true;
+  const mode = parsed.flags.mode ?? 'orchestration';
+  if (!['host', 'orchestration'].includes(mode)) {
+    return emit(dependencies.output, json, {
+      ok: false, status: 'fail', checks: [],
+      remediations: ['Use --mode=host or --mode=orchestration.'],
+      error: { code: 'INVALID_INPUT', exitCode: EXIT_CODES.INVALID_INPUT, message: 'Preflight mode is invalid.' },
+    }, EXIT_CODES.INVALID_INPUT);
+  }
+  const projectRoot = resolve(parsed.flags.project ?? dependencies.cwd?.() ?? process.cwd());
+  let config;
+  try {
+    config = await (dependencies.configLoader ?? loadProjectConfig)(projectRoot, { fs: dependencies.fs });
+  } catch {
+    return emit(dependencies.output, json, {
+      ok: false,
+      status: 'fail',
+      checks: [],
+      remediations: ['Create or repair the project configuration before preflight.'],
+      error: {
+        code: 'MISSING_CONFIGURATION',
+        exitCode: EXIT_CODES.MISSING_CONFIGURATION,
+        message: 'Project configuration is missing or invalid.',
+      },
+    }, EXIT_CODES.MISSING_CONFIGURATION);
+  }
+  try {
+    const packageManager = config.project.stack.packageManager;
+    const direct = config.project.schemaVersion === 3;
+    const doctor = await diagnoseDoctor(projectRoot, {
+      ...dependencies,
+      ...(mode === 'host' ? { hostReadiness: true } : {}),
+    });
+    const [git, tools, goalState] = await Promise.all([
+      (dependencies.gitDiscovery ?? discoverGit)(projectRoot, {
+        runner: dependencies.runner,
+        ...(mode === 'host' ? { defaultBranch: config.project.repository.defaultBranch } : {}),
+        candidatePaths: dependencies.candidatePaths ?? [join(projectRoot, '.worktrees', 'next')],
+      }),
+      (dependencies.toolDiscovery ?? discoverTools)(direct ? { runtimeOnly: true } : { packageManager }, {
+        cwd: projectRoot,
+        runner: dependencies.runner,
+      }),
+      mode === 'host' ? Promise.resolve(null) : (dependencies.goalStateReader ?? defaultGoalState)(projectRoot),
+    ]);
+    const capacity = dependencies.runtimeCapacity ?? { available: 1, required: 1 };
+    const qualityCommands = doctor.checks?.commands ?? { ready: false, steps: [] };
+    const checks = [
+      check('doctor', doctor.exitCode === EXIT_CODES.SUCCESS, 'Run doctor and resolve failed readiness checks.'),
+      check('repository', git.repository === true, 'Run preflight inside a Git repository.'),
+      check('worktree-clean', git.dirty === false, 'Commit or stash worktree changes.'),
+      check('head-attached', git.detached === false, 'Switch to a local branch.'),
+      ...(mode === 'host' ? [check('configured-branch', git.currentBranch === config.project.repository.defaultBranch
+        && git.defaultBranch === config.project.repository.defaultBranch,
+      'Review repository.defaultBranch in .rivet/project.yaml and switch to that local branch before starting a task.')] : []),
+      check('base-freshness', git.baseFreshness === 'fresh' || git.baseFreshness === 'ahead', 'Update the local default branch from its existing remote-tracking ref.'),
+      check('worktree-discovery', git.worktreeCheck?.checked === true, 'Resolve local Git worktree discovery before retrying.'),
+      ...(mode === 'host' ? [] : [check('worktree-paths', (git.occupiedCandidatePaths ?? []).length === 0, 'Select an unoccupied worktree path.', {
+        occupiedCount: (git.occupiedCandidatePaths ?? []).length,
+      })]),
+      ...(mode === 'host' ? [] : [check('runtime-capacity', Number(capacity.available) >= Number(capacity.required), 'Increase available runtime capacity.', {
+        available: Number(capacity.available), required: Number(capacity.required),
+      })]),
+      ...(mode === 'host' ? [] : [check('goal-state', goalState?.status === 'ready', 'Initialize and approve the private goal instance.')]),
+      check('toolchain', tools.node?.supported === true && (direct || tools[packageManager]?.supported === true) && tools.git?.supported === true,
+        direct ? 'Install a supported local Node runtime and Git.' : 'Install a supported local Node, package manager, and Git toolchain.'),
+      check('quality-commands', qualityCommands.ready || (direct && qualityCommands.preparationReady === true), direct
+        ? 'Resolve the configured command executables on PATH and verify their project working directories. Run rivet doctor for the failing command.'
+        : 'Define every required quality command as an effective bounded package script.', {
+        commands: qualityCommands.steps,
+      }),
+    ];
+    const failed = checks.filter(item => item.status === 'fail');
+    const payload = {
+      ok: failed.length === 0,
+      status: failed.length === 0 ? 'pass' : 'fail',
+      ...(mode === 'host' ? { mode } : {}),
+      ...(doctor.status === 'preparation-required' ? { dependencyPreparation: 'required' } : {}),
+      checks,
+      remediations: [...new Set(failed.map(item => item.remediation))],
+    };
+    return emit(dependencies.output, json, payload,
+      failed.length === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.FAILED_GATE);
+  } catch {
+    return emit(dependencies.output, json, {
+      ok: false,
+      status: 'fail',
+      checks: [],
+      remediations: ['Retry after resolving the local discovery failure.'],
+      error: {
+        code: 'INTERNAL_ERROR',
+        exitCode: EXIT_CODES.INTERNAL_ERROR,
+        message: 'Preflight could not complete safely.',
+      },
+    }, EXIT_CODES.INTERNAL_ERROR);
+  }
+}