@agilno-tech/rivet 0.1.0-alpha.0

package/src/clients/result-contract.js

@@ -0,0 +1,78 @@
+import { immutableJson } from './contract.js';
+
+const AGENT_RESULT_CONTRACT = immutableJson({
+  version: 1,
+  kind: 'agilno.agent-result',
+  framing: 'Emit exactly one JSON object matching this result schema on stdout. Emit no Markdown or commentary. For a successful result, output.evidence must contain exactly the evidence identifiers declared by the launch contract, with no invented or omitted identifiers.',
+  schema: {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'agilno.agent-result',
+    type: 'object',
+    additionalProperties: false,
+    required: ['version', 'status', 'output', 'usage'],
+    properties: {
+      version: { const: 1 },
+      status: { enum: ['success', 'retry', 'failed', 'blocked', 'budget-exhausted'] },
+      output: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['summary', 'evidence'],
+        properties: {
+          summary: { type: 'string', minLength: 1, maxLength: 16_384 },
+          evidence: {
+            type: 'array',
+            maxItems: 64,
+            uniqueItems: true,
+            items: {
+              type: 'string',
+              minLength: 1,
+              maxLength: 64,
+              pattern: '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$',
+            },
+          },
+        },
+      },
+      usage: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['tokens', 'costUsd'],
+        properties: {
+          tokens: { type: 'integer', minimum: 0, maximum: 10_000_000 },
+          costUsd: { type: 'number', minimum: 0, maximum: 100_000 },
+        },
+      },
+    },
+  },
+});
+
+export function agentResultContract(evidence = undefined) {
+  if (evidence === undefined) return AGENT_RESULT_CONTRACT;
+  if (!Array.isArray(evidence) || evidence.length > 64
+    || evidence.some(item => typeof item !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(item))) {
+    throw new TypeError('Agent result evidence is invalid.');
+  }
+  return immutableJson({
+    ...AGENT_RESULT_CONTRACT,
+    schema: {
+      ...AGENT_RESULT_CONTRACT.schema,
+      properties: {
+        ...AGENT_RESULT_CONTRACT.schema.properties,
+        output: {
+          ...AGENT_RESULT_CONTRACT.schema.properties.output,
+          properties: {
+            ...AGENT_RESULT_CONTRACT.schema.properties.output.properties,
+            evidence: {
+              ...AGENT_RESULT_CONTRACT.schema.properties.output.properties.evidence,
+              minItems: evidence.length,
+              maxItems: evidence.length,
+              items: {
+                ...AGENT_RESULT_CONTRACT.schema.properties.output.properties.evidence.items,
+                enum: [...evidence],
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+}

package/src/commands/delivery-publish.js

@@ -0,0 +1,80 @@
+import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createApprovalReceipt, createApprovalRegistry } from '../policy/approvals.js';
+import { createAuthorityEnvelope } from '../policy/authority.js';
+import { createDeliveryService } from '../delivery/service.js';
+import { createBranchPublicationExecutor, publicationPayload } from '../delivery/branch-publication.js';
+import { createGitPublicationTransport, validatePublicationExecutable } from '../delivery/publication-transport.js';
+import { runPublicationProcess } from '../delivery/publication-process.js';
+import { parseRepositoryRemote } from '../repositories/identity.js';
+import { ensure, hash } from '../delivery/contract.js';
+const ENDPOINTS={github:'https://api.github.com',gitlab:'https://gitlab.com/api/v4',bitbucket:'https://api.bitbucket.org/2.0'};
+export function publicationProvider(config,repository,flags,writing) {
+  const candidates=config.providers.providers.filter(p=>p.kind==='git-ci'&&p.mode!=='disabled'&&(!writing||p.mode==='read-write-with-approval')&&(p.transport??'direct-api')==='direct-api'&&p.endpoint?.replace(/\/$/,'')===ENDPOINTS[repository.provider]&&['repository-read','branch-publish'].every(c=>p.capabilities.includes(c))&&(!p.projectIds?.length||p.projectIds.includes(config.project.id))&&(!p.resourceIds?.length||p.resourceIds.includes(repository.fullName))&&(flags.provider===undefined||flags.provider===p.id));
+  ensure(candidates.length===1,'publication-provider-required');return candidates[0];
+}
+export function publicationToken(provider,kind,environment) {
+  const keys=Object.keys(provider.credentials??{});ensure(keys.length===1&&['tokenEnv','accessTokenEnv','apiTokenEnv'].includes(keys[0]),'invalid-credentials');
+  if(kind==='bitbucket')ensure(keys[0]==='accessTokenEnv','bitbucket-access-token-required');
+  const name=provider.credentials[keys[0]];ensure(typeof name==='string'&&/^[A-Z][A-Z0-9_]{1,127}$/.test(name),'invalid-credentials');
+  return environment[name];
+}
+export async function inspectPublicationSource({project,gitExecutable,repository,runner=runPublicationProcess}) {
+  await validatePublicationExecutable(gitExecutable,project);
+  const run=async args=>{
+    const result=await runner(gitExecutable,args,{cwd:project,env:{PATH:'/usr/bin:/bin',HOME:'/nonexistent',GIT_CONFIG_GLOBAL:'/dev/null',GIT_CONFIG_SYSTEM:'/dev/null',GIT_CONFIG_NOSYSTEM:'1',GIT_TERMINAL_PROMPT:'0'},timeoutMs:3000,maxOutputBytes:32768});
+    ensure(result.code===0&&!result.reason,'publication-source-unavailable');return result.stdout.trim();
+  };
+  const remoteOutput=await run(['remote','-v']);const matching=new Set();const pushes=[];
+  for(const line of remoteOutput.split('\n').filter(Boolean)) {
+    const match=/^(\S+)\s+(\S+) \((fetch|push)\)$/.exec(line);ensure(match,'invalid-remote');
+    if(match[3]==='fetch') {try {if(hash(parseRepositoryRemote(match[2]))===hash(repository))matching.add(match[1]);}catch{}}
+    else pushes.push({name:match[1],url:match[2]});
+  }
+  ensure(matching.size>0,'publication-remote-missing');
+  for(const name of matching) {
+    const selected=pushes.filter(p=>p.name===name);ensure(selected.length===1,'conflicting-push-url');
+    ensure(hash(parseRepositoryRemote(selected[0].url))===hash(repository),'conflicting-push-url');
+  }
+  const objects=await run(['rev-parse','--git-path','objects']);ensure(objects&&!/[\u0000\r\n]/.test(objects),'unsafe-object-store');
+  const sourceObjects=resolve(project,objects);ensure(await realpath(sourceObjects)===sourceObjects,'unsafe-object-store');
+  return {sourceObjects,remoteDigest:hash(pushes.filter(p=>matching.has(p.name)).sort((a,b)=>a.name.localeCompare(b.name)))};
+}
+async function publicationDelivery({action,store,config,flags,dependencies,validateLocal,reloadConfig,publicationContext,confirm}) {
+  let state=await store.read();const writing=action==='publish';
+  const provider=structuredClone(publicationProvider(config,state.candidate.repository,flags,writing));
+  const projectDigest=hash(config.project);
+  const source=await inspectPublicationSource({...publicationContext,repository:state.candidate.repository,runner:dependencies.delivery?.publicationSourceRunner});
+  const factory=dependencies.delivery?.publicationTransportFactory??createGitPublicationTransport;
+  const token=publicationToken(provider,state.candidate.repository.provider,dependencies.env);
+  const transport=await factory({...publicationContext,repository:state.candidate.repository,sourceObjects:source.sourceObjects,token, signal: dependencies.publicationSignal});
+  const executor=createBranchPublicationExecutor({repository:state.candidate.repository,transport});
+  const service=createDeliveryService({store,executor,timeoutMs:120000,providerId:provider.id,subjectId:'delivery-cli',expectedApproverId:'terminal-human',approvalRegistry:createApprovalRegistry({approvers:[{id:'terminal-human',principal:'human'}]}),authority:createAuthorityEnvelope({actorId:'delivery-cli',principal:'agent',actions:writing?['provider.write']:[],ownedPaths:[],commands:[],providers:writing?[{id:provider.id,mode:provider.mode,capabilities:['branch-publish']}]:[]})});
+  if(action==='reconcile')return service.reconcile({expectedVersion:state.version});
+  await validateLocal(state.candidate);
+  state=await service.refresh({expectedVersion:state.version});
+  const publication=state.observation.publication;
+  if(publication.remoteSha===state.candidate.headSha) {dependencies.output.log('The exact verified commit is already available at the destination branch. No publication was dispatched.');return state;}
+  ensure(publication.remoteSha===null,'branch-exists');
+  const expiresAt=new Date(Date.now()+300000).toISOString();
+  state=await service.propose({expectedVersion:state.version,action:'branch-publish',payload:publicationPayload(state.candidate),expiresAt});
+  dependencies.output.log(`Publish ${state.candidate.headSha} to ${publication.destinationUrl}`);
+  dependencies.output.log(`Create only: ${publication.ref}. An existing branch will never be overwritten. This uploads the commit and its reachable history; it does not create or merge a review.`);
+  ensure(await confirm(state),'approval-required');
+  const currentConfig=await reloadConfig();const currentProvider=publicationProvider(currentConfig,state.candidate.repository,flags,true);
+  ensure(hash(currentProvider)===hash(provider)&&hash(currentConfig.project)===projectDigest,'changed-configuration');
+  ensure(publicationToken(currentProvider,state.candidate.repository.provider,dependencies.env)===token,'changed-credentials');
+  await validateLocal(state.candidate);
+  const currentSource=await inspectPublicationSource({...publicationContext,repository:state.candidate.repository,runner:dependencies.delivery?.publicationSourceRunner});
+  ensure(hash(currentSource)===hash(source),'changed-publication-source');
+  const approval=createApprovalReceipt({id:`publish-${randomUUID()}`,approverId:'terminal-human',approverPrincipal:'human',subjectId:'delivery-cli',action:'provider.write',resource:state.proposal.approvalResource,policyId:'authority.external-write',decision:'approved',expiresAt,singleUse:true});
+  return service.execute({expectedVersion:state.version,proposalDigest:state.proposal.digest,approval});
+}
+
+export async function runPublicationDelivery(input) {
+  const controller=new AbortController();const abort=()=>controller.abort();
+  process.once('SIGINT',abort);process.once('SIGTERM',abort);
+  try {return await publicationDelivery({...input,dependencies:{...input.dependencies,publicationSignal:controller.signal}});}
+  finally {process.removeListener('SIGINT',abort);process.removeListener('SIGTERM',abort);}
+}

package/src/commands/delivery-remote.js

@@ -0,0 +1,230 @@
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../cli/output.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import { createApprovalReceipt, createApprovalRegistry } from '../policy/approvals.js';
+import { createAuthorityEnvelope } from '../policy/authority.js';
+import { hash, plain } from '../delivery/contract.js';
+import { createDeliveryService } from '../delivery/service.js';
+
+function fail(message, code = 'REPOSITORY_CONFLICT') {
+  throw new CliError(message, code);
+}
+const ENDPOINTS = Object.freeze({ github: 'https://api.github.com', gitlab: 'https://gitlab.com/api/v4', bitbucket: 'https://api.bitbucket.org/2.0' });
+export function providerFor(config, repository, flags, writing, operation = 'merge') {
+  const providers = config.providers.providers.filter(
+    (provider) =>
+      provider.kind === 'git-ci' &&
+      provider.mode !== 'disabled' &&
+      (!writing || provider.mode === 'read-write-with-approval') &&
+      (provider.transport ?? 'direct-api') === 'direct-api' &&
+      ['repository-read', ...(operation === 'deploy' ? ['deployments-read', 'actions-read'] : ['review-request', 'review-update'].includes(operation) ? [] : ['checks-read']), ...(writing ? [operation] : [])].every((cap) =>
+        provider.capabilities.includes(cap)
+      ) &&
+      (!provider.projectIds?.length || provider.projectIds.includes(config.project.id)) &&
+      (!provider.resourceIds?.length || provider.resourceIds.includes(repository.fullName)) &&
+      provider.endpoint?.replace(/\/$/, '') === ENDPOINTS[repository.provider] &&
+      (flags.provider === undefined || provider.id === flags.provider)
+  );
+  if (providers.length !== 1)
+    fail(
+      'Configure one scoped repository API provider. Review operations need repository-read and review-request or review-update; merge needs repository-read/checks-read; deployment needs repository-read/deployments-read/actions-read. Writes require the action capability and read-write-with-approval mode.',
+      'MISSING_CONFIGURATION'
+    );
+  return providers[0];
+}
+export function headers(provider, environment, kind) {
+  const credentials = provider.credentials ?? {};
+  const keys = Object.keys(credentials);
+  if (
+    keys.length !== 1 ||
+    !['tokenEnv', 'accessTokenEnv', 'apiTokenEnv'].includes(keys[0]) ||
+    !/^[A-Z][A-Z0-9_]{1,127}$/.test(credentials[keys[0]])
+  )
+    fail('Configure one token environment reference for repository delivery.', 'MISSING_CONFIGURATION');
+  if (kind === 'bitbucket' && keys[0] !== 'accessTokenEnv')
+    fail('Bitbucket review operations require accessTokenEnv for a Bearer access token. API tokens use a different authentication scheme and are not supported here.', 'MISSING_CONFIGURATION');
+  const token = environment[credentials[keys[0]]];
+  if (typeof token !== 'string' || !token || token.length > 8192 || /[\s\u0000-\u001f\u007f]/.test(token))
+    fail('The configured repository token is missing or invalid.', 'PROVIDER_UNAVAILABLE');
+  return {
+    authorization: `Bearer ${token}`,
+    accept: kind === 'github' ? 'application/vnd.github+json' : 'application/json',
+  };
+}
+async function confirm(dependencies, preview) {
+  let timer;
+  try {
+    return (
+      (await Promise.race([
+        Promise.resolve().then(() => dependencies.confirmDelivery(preview)),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(false), 30000);
+        }),
+      ])) === true
+    );
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function runRemoteDelivery({ action, store, config, flags, dependencies, validateLocal, loadTrackerTarget, reloadConfig = async () => config, publicationContext }) {
+  if (action === 'review') action = 'review-request';
+  const writing = ['publish', 'review-request', 'review-update', 'merge', 'deploy', 'tracker-update', 'tracker-transition'].includes(action);
+  if (!['publish', 'review-request', 'review-update', 'merge', 'deploy', 'tracker-update', 'tracker-status', 'tracker-transition', 'refresh', 'reconcile'].includes(action))
+    fail('Unsupported delivery action.', 'INVALID_INPUT');
+  if (
+    writing &&
+    (flags.json ||
+      dependencies.terminalIsInteractive?.() !== true ||
+      typeof dependencies.confirmDelivery !== 'function')
+  )
+    fail(
+      'Run delivery writes in an interactive terminal to review and approve the exact operation. JSON and unattended writes are unavailable.',
+      'INVALID_INPUT'
+    );
+  let state = await store.read();
+  if (!state) fail('Run rivet delivery prepare after verification first.');
+  const pendingAction = state.operations.find(op => ['dispatching','indeterminate'].includes(op.state))?.action;
+  if (action === 'review-update' || (action === 'reconcile' && pendingAction === 'review-update')) {
+    const {runReviewUpdate} = await import('./delivery-review-update.js');
+    return runReviewUpdate({action,state,store,config,flags,dependencies,reloadConfig,validateLocal,confirm:preview=>confirm(dependencies,preview)});
+  }
+  if (action === 'publish' || (action === 'reconcile' && pendingAction === 'branch-publish')) {
+    const {runPublicationDelivery} = await import('./delivery-publish.js');
+    return runPublicationDelivery({action,store,config,flags,dependencies,validateLocal,reloadConfig,publicationContext,confirm: preview => confirm(dependencies,preview)});
+  }
+  if (['tracker-status', 'tracker-transition'].includes(action) || (action === 'reconcile' && pendingAction === 'tracker-transition')) {
+    const {runTrackerTransition} = await import('./delivery-transition.js');
+    return runTrackerTransition({action,state,store,config,flags,dependencies,reloadConfig,loadTrackerTarget,
+      confirm: preview => confirm(dependencies,preview)});
+  }
+  if (action === 'tracker-update' || (action === 'reconcile' && pendingAction === 'tracker-update')) {
+    const {runTrackerDelivery} = await import('./delivery-tracker.js');
+    return runTrackerDelivery({action,state,store,config,flags,dependencies,reloadConfig,loadTrackerTarget,
+      confirm: preview => confirm(dependencies,preview)});
+  }
+  const kind = state.candidate.repository.provider;
+  if (!Object.hasOwn(ENDPOINTS, kind))
+    fail('Native repository delivery supports GitHub.com, GitLab.com and Bitbucket Cloud review creation.', 'PROVIDER_UNAVAILABLE');
+  if (action === 'merge' && kind === 'gitlab' && flags.method !== undefined && flags.method !== 'merge')
+    fail(
+      'GitLab currently supports --method=merge only; squash and rebase are unavailable.',
+      'INVALID_INPUT'
+    );
+  if (writing && state.operations.some((op) => op.action === action && op.state === 'succeeded'))
+    return state;
+  const operation = action === 'reconcile'
+    ? state.operations.find(op => ['dispatching', 'indeterminate'].includes(op.state))?.action
+    : action;
+  if (kind === 'bitbucket' && operation !== 'review-request')
+    fail('Native Bitbucket delivery currently supports review creation and its reconciliation only. Native merge and deployment are unavailable.', 'PROVIDER_UNAVAILABLE');
+  const deploying = operation === 'deploy';
+  const reviewing = operation === 'review-request';
+  let deployment;
+  let mergeReceipt;
+  if (deploying) {
+    if (kind !== 'github' || !config.project.deployment)
+      fail('Configure project.deployment for GitHub Actions deployment first.', 'MISSING_CONFIGURATION');
+    deployment = plain(config.project.deployment);
+    if (flags.provider !== undefined && flags.provider !== deployment.providerId)
+      fail('Deployment uses the provider declared in project.deployment.', 'INVALID_INPUT');
+    mergeReceipt = state.operations.find(op => op.action === 'merge' && op.state === 'succeeded')?.receipt;
+    if (!mergeReceipt) fail('Deployment requires a confirmed merge receipt.');
+  }
+  const selectedFlags = deploying ? { ...flags, provider: deployment.providerId } : flags;
+  const provider = providerFor(config, state.candidate.repository, selectedFlags, writing, deploying ? 'deploy' : reviewing ? 'review-request' : 'merge');
+  const auth = headers(provider, dependencies.env, kind);
+  const executorFactory =
+    (deploying ? dependencies.delivery?.deploymentExecutorFactory : reviewing ? dependencies.delivery?.reviewExecutorFactory : dependencies.delivery?.executorFactory) ??
+    (deploying ? (await import('../delivery/github-deployment.js')).createGithubDeploymentExecutor : reviewing
+      ? (kind === 'github' ? (await import('../delivery/github-review.js')).createGithubReviewExecutor : kind === 'bitbucket' ? (await import('../delivery/bitbucket-review.js')).createBitbucketReviewExecutor : (await import('../delivery/gitlab-review.js')).createGitlabReviewExecutor) :
+    (kind === 'github'
+      ? (await import('../delivery/github.js')).createGithubDeliveryExecutor
+      : (await import('../delivery/gitlab.js')).createGitlabDeliveryExecutor));
+  const executor = executorFactory({
+    repository: state.candidate.repository,
+    ...(deploying ? {deployment, mergeReceipt} : {}),
+    headers: auth,
+    transport: dependencies.delivery?.transport ?? createNodeProviderTransport(),
+  });
+  const service = createDeliveryService({
+    store,
+    executor,
+    timeoutMs: 120000,
+    providerId: provider.id,
+    subjectId: 'delivery-cli',
+    expectedApproverId: 'terminal-human',
+    authority: createAuthorityEnvelope({
+      actorId: 'delivery-cli',
+      principal: 'agent',
+      actions: writing ? ['provider.write'] : [],
+      ownedPaths: [],
+      commands: [],
+      providers: writing ? [{ id: provider.id, mode: provider.mode, capabilities: [action] }] : [],
+    }),
+    approvalRegistry: createApprovalRegistry({ approvers: [{ id: 'terminal-human', principal: 'human' }] }),
+  });
+  if (action === 'reconcile') return service.reconcile({ expectedVersion: state.version });
+  if (action === 'merge' || reviewing) await validateLocal(state.candidate);
+  state = await service.refresh({ expectedVersion: state.version });
+  if (!writing) return state;
+  const expiresAt = new Date(Date.now() + 5 * 60 * 1000).toISOString();
+  state = await service.propose({
+    expectedVersion: state.version,
+    action,
+    expiresAt,
+    payload: reviewing ? (await import('../delivery/review-request.js')).reviewRequestPayload(state.candidate) : deploying ? {workflow: deployment.workflow, environment: deployment.environment, productionEnvironment: deployment.productionEnvironment} : {
+      reviewNumber: state.observation.review?.number,
+      mergeMethod: flags.method ?? (kind === 'github' ? 'squash' : 'merge'),
+    },
+  });
+  if (reviewing) {
+    const content = (await import('../delivery/review-request.js')).reviewRequestContent({ ...state.proposal, digest: state.proposal.digest });
+    dependencies.output.log(`Create review: ${state.candidate.repository.url}`);
+    dependencies.output.log(`${state.candidate.sourceBranch} (${state.candidate.headSha}) -> ${state.candidate.targetBranch} (${state.observation.baseSha})`);
+    dependencies.output.log('Branch selection is not atomic. Rivet verifies the created review afterward; a changed or uncertain result requires reconciliation.');
+    dependencies.output.log(`Title: ${content.title}`);
+    dependencies.output.log(`Body:\n${content.body}`);
+  } else if (deploying) {
+    dependencies.output.log(`Deploy ${mergeReceipt.commitSha} to ${deployment.environment}`);
+    dependencies.output.log(`Workflow: ${deployment.workflow}. Production environment: ${deployment.productionEnvironment}.`);
+  } else {
+  dependencies.output.log(`Merge ${state.observation.review.url}`);
+  dependencies.output.log(
+    `${state.candidate.sourceBranch} (${state.candidate.headSha}) -> ${state.candidate.targetBranch} (${state.observation.baseSha})`
+  );
+  dependencies.output.log(
+    `Method: ${state.proposal.payload.mergeMethod}. Required checks and supported review policy passed.`
+  );
+  }
+  if (!(await confirm(dependencies, state)))
+    fail('Delivery operation was not approved. Nothing was dispatched.', 'INVALID_INPUT');
+  if (reviewing) {
+    const currentConfig = await reloadConfig();
+    const currentProvider = providerFor(currentConfig, state.candidate.repository, selectedFlags, true, 'review-request');
+    if (hash(currentProvider) !== hash(provider) || hash(currentConfig.project) !== hash(config.project))
+      fail('Review configuration changed. Review a new proposal.');
+  }
+  if (deploying) {
+    const currentConfig = await reloadConfig();
+    const currentProvider = providerFor(currentConfig, state.candidate.repository, selectedFlags, true, 'deploy');
+    if (hash(currentConfig.project.deployment) !== hash(deployment) || hash(currentProvider) !== hash(provider))
+      fail('Deployment configuration changed. Review a new proposal.');
+  }
+  if (action === 'merge' || reviewing) await validateLocal(state.candidate);
+  const approval = createApprovalReceipt({
+    id: `${action}-${randomUUID()}`,
+    approverId: 'terminal-human',
+    approverPrincipal: 'human',
+    subjectId: 'delivery-cli',
+    action: 'provider.write',
+    resource: state.proposal.approvalResource,
+    policyId: 'authority.external-write',
+    decision: 'approved',
+    expiresAt,
+    singleUse: true,
+  });
+  return service.execute({ expectedVersion: state.version, proposalDigest: state.proposal.digest, approval });
+}

package/src/commands/delivery-review-update.js

@@ -0,0 +1,39 @@
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../cli/output.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import { createDeliveryService } from '../delivery/service.js';
+import { createReviewUpdateExecutor, reviewUpdateContent } from '../delivery/review-update.js';
+import { hash } from '../delivery/contract.js';
+import { createAuthorityEnvelope } from '../policy/authority.js';
+import { createApprovalReceipt, createApprovalRegistry } from '../policy/approvals.js';
+import { providerFor, headers } from './delivery-remote.js';
+function fail(message,code='REPOSITORY_CONFLICT'){throw new CliError(message,code);}
+export async function runReviewUpdate({action,state,store,config,flags,dependencies,reloadConfig,validateLocal,confirm}){
+ const writing=action==='review-update',pending=state.operations.find(op=>['dispatching','indeterminate'].includes(op.state));
+ if(writing&&pending)fail('Reconcile the pending delivery operation before updating review metadata.');
+ if(state.operations.some(op=>op.action==='merge'&&op.state==='succeeded'))fail('Review metadata updates require an open unmerged candidate.');
+ let desired;if(writing){try{desired=reviewUpdateContent({title:flags.title,body:flags.body},state.candidate.repository.provider);}catch{fail('Review update requires an exact --title and --body. Only bounded title/body text can be changed.','INVALID_INPUT');}}
+ let number=state.candidate.reviewNumber??state.observation?.review?.number;
+ if(!number){const receipt=state.operations.find(op=>op.action==='review-request'&&op.state==='succeeded')?.receipt;const prefix=`${state.candidate.repository.url}/${{github:'pull',gitlab:'-/merge_requests',bitbucket:'pull-requests'}[state.candidate.repository.provider]}/`;if(receipt?.resourceUrl?.startsWith(prefix))number=Number(receipt.resourceUrl.slice(prefix.length));}
+ let selectedId=flags.provider;
+ if(!writing){if(pending?.action!=='review-update'||state.proposal?.digest!==pending.digest)fail('No pending review metadata update was found.');number=pending.payload.before.review.number;if(selectedId!==undefined&&selectedId!==state.proposal.providerId)fail('Reconciliation requires the originally approved provider.');selectedId=state.proposal.providerId;}
+ if(!Number.isSafeInteger(number)||number<=0)fail('Prepare or create the exact review request before updating it.');
+ const provider=providerFor(config,state.candidate.repository,{...flags,provider:selectedId},writing,'review-update');
+ const prepared=(dependencies.delivery?.reviewUpdateFactory??createReviewUpdateExecutor)({repository:state.candidate.repository,reviewNumber:number,headers:headers(provider,dependencies.env,state.candidate.repository.provider),transport:dependencies.delivery?.transport??createNodeProviderTransport()});
+ const service=createDeliveryService({store,executor:prepared.executor,providerId:provider.id,timeoutMs:120000,subjectId:'delivery-cli',expectedApproverId:'terminal-human',authority:createAuthorityEnvelope({actorId:'delivery-cli',principal:'agent',actions:writing?['provider.write']:[],ownedPaths:[],commands:[],providers:writing?[{id:provider.id,mode:provider.mode,capabilities:['review-update']}]:[]}),approvalRegistry:createApprovalRegistry({approvers:[{id:'terminal-human',principal:'human'}]})});
+ if(!writing)return service.reconcile({expectedVersion:state.version});
+ await validateLocal(state.candidate);
+ const payload=await prepared.prepare(state.candidate,desired);
+ if(hash(payload.desired)===hash({title:payload.before.review.title,body:payload.before.review.body}))return {...state,reviewUpdateNoop:true};
+ state=await service.refresh({expectedVersion:state.version});
+ const expiresAt=new Date(Date.now()+5*60*1000).toISOString();state=await service.propose({expectedVersion:state.version,action:'review-update',payload,expiresAt});
+ dependencies.output.log(`Update review: ${payload.before.review.url}\n${state.candidate.sourceBranch} (${state.candidate.headSha}) -> ${state.candidate.targetBranch} (${payload.before.baseSha})`);
+ dependencies.output.log(`Previous title: ${payload.before.review.title}\nPrevious body:\n${payload.before.review.body}\nNew title: ${payload.desired.title}\nNew body:\n${payload.desired.body}`);
+ dependencies.output.log('Assurance: precheck and readback, without atomic metadata or commit conditions. Concurrent edits may be overwritten. Confirmation observes the desired state and does not prove exclusive causation.');
+ if(!(await confirm(state)))fail('Review metadata update was not approved. No write was sent.','INVALID_INPUT');
+ const currentConfig=await reloadConfig(),currentProvider=providerFor(currentConfig,state.candidate.repository,{provider:provider.id},true,'review-update');
+ if(hash(currentProvider)!==hash(provider)||hash(currentConfig.project)!==hash(config.project))fail('Review configuration changed. Review a new proposal.');
+ await validateLocal(state.candidate);
+ const approval=createApprovalReceipt({id:`review-update-${randomUUID()}`,approverId:'terminal-human',approverPrincipal:'human',subjectId:'delivery-cli',action:'provider.write',resource:state.proposal.approvalResource,policyId:'authority.external-write',decision:'approved',expiresAt,singleUse:true});
+ return service.execute({expectedVersion:state.version,proposalDigest:state.proposal.digest,approval});
+}

package/src/commands/delivery-tracker.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../cli/output.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import { createDeliveryService } from '../delivery/service.js';
+import { hash, plain } from '../delivery/contract.js';
+import { createAuthorityEnvelope } from '../policy/authority.js';
+import { createApprovalReceipt, createApprovalRegistry } from '../policy/approvals.js';
+
+function fail(message, code = 'MISSING_CONFIGURATION') { throw new CliError(message, code); }
+export function selectProvider(config, target, selectedId, writing, operation = 'tracker-update') {
+  const reading = operation === 'tracker-transition' ? 'transitions-read' : 'comments-read';
+  const matches = config.providers.providers.filter(provider =>
+    provider.kind === target.kind && provider.mode !== 'disabled' &&
+    (!writing || provider.mode === 'read-write-with-approval') &&
+    (provider.transport ?? 'direct-api') === 'direct-api' &&
+    ['issues-read', reading, ...(writing ? [operation] : [])].every(cap => provider.capabilities.includes(cap)) &&
+    (!provider.projectIds?.length || provider.projectIds.includes(config.project.id)) &&
+    (!provider.resourceIds?.length || provider.resourceIds.includes(target.issueKey)) &&
+    (selectedId === undefined || selectedId === provider.id));
+  if (matches.length !== 1) fail(`Configure one scoped direct Jira/Linear provider with issues-read and ${reading}. Writing also requires ${operation} and read-write-with-approval. Use --provider when ambiguous.`);
+  const provider = matches[0];
+  const validEndpoint = target.kind === 'jira'
+    ? /^https:\/\/[a-z0-9][a-z0-9-]*\.atlassian\.net$/.test(provider.endpoint ?? '') && target.issueUrl === `${provider.endpoint}/browse/${target.issueKey}`
+    : provider.endpoint === 'https://api.linear.app';
+  if (!validEndpoint) fail('Tracker endpoint must match the recorded Jira Cloud site or the Linear API.');
+  return provider;
+}
+export function authHeaders(provider, env) {
+  const credentials = provider.credentials ?? {}, keys = Object.keys(credentials);
+  const value = name => {
+    if (typeof name !== 'string' || !/^[A-Z][A-Z0-9_]{1,127}$/.test(name)) fail('Configure tracker credential environment references.');
+    const text = env[name];
+    if (typeof text !== 'string' || !text || text.length > 8192 || /[\s\u0000-\u001f\u007f]/.test(text))
+      fail('Configured tracker credentials are missing or invalid.', 'PROVIDER_UNAVAILABLE');
+    return text;
+  };
+  if (provider.kind === 'jira') {
+    if (keys.length !== 2 || !keys.includes('usernameEnv') || !keys.includes('apiTokenEnv')) fail('Jira delivery requires usernameEnv and apiTokenEnv.');
+    const username = value(credentials.usernameEnv);
+    if (username.includes(':')) fail('Jira username is invalid.');
+    return {authorization: `Basic ${Buffer.from(`${username}:${value(credentials.apiTokenEnv)}`).toString('base64')}`, accept:'application/json'};
+  }
+  if (keys.length !== 1 || !['apiTokenEnv','accessTokenEnv','tokenEnv'].includes(keys[0])) fail('Configure one Linear API key or OAuth token reference.');
+  const token = value(credentials[keys[0]]);
+  return {authorization: keys[0] === 'accessTokenEnv' ? `Bearer ${token}` : token, accept:'application/json'};
+}
+
+export async function runTrackerDelivery({action, state, store, config, flags, dependencies, reloadConfig, loadTrackerTarget, confirm}) {
+  const writing = action === 'tracker-update';
+  if (writing && state.operations.some(op => op.action === 'tracker-update' && op.state === 'succeeded')) return state;
+  const pending = state.operations.find(op => ['dispatching','indeterminate'].includes(op.state));
+  if (writing && pending) fail('Reconcile the pending delivery operation before posting a tracker update.', 'REPOSITORY_CONFLICT');
+  const mergeReceipt = state.operations.find(op => op.action === 'merge' && op.state === 'succeeded')?.receipt;
+  if (!mergeReceipt) fail('A tracker delivery summary requires a confirmed merge.', 'REPOSITORY_CONFLICT');
+  const deploymentReceipt = state.operations.find(op => op.action === 'deploy' && op.state === 'succeeded')?.receipt ?? null;
+  let target, selectedId = flags.provider;
+  if (writing) {
+    if (typeof loadTrackerTarget !== 'function') fail('The run must contain a recorded Jira or Linear source ticket.');
+    try { target = plain(await loadTrackerTarget(state.candidate)); }
+    catch { fail('This run has no validated Jira/Linear source ticket. Tracker updates require the recorded source; a replacement ticket cannot be supplied.'); }
+  } else {
+    if (pending?.action !== 'tracker-update' || state.proposal?.digest !== pending.digest) fail('No pending tracker update was found.', 'REPOSITORY_CONFLICT');
+    const p = pending.payload;
+    target = plain({kind:p.kind,issueKey:p.issueKey,issueUrl:p.issueUrl,requestDigest:p.requestDigest});
+    if (selectedId !== undefined && selectedId !== state.proposal.providerId) fail('Reconciliation requires the originally approved tracker provider.');
+    selectedId = state.proposal.providerId;
+  }
+  const provider = selectProvider(config, target, selectedId, writing);
+  if (!writing && pending.payload.endpoint !== provider.endpoint) fail('Restore the originally approved tracker endpoint before reconciliation.');
+  const factory = dependencies.delivery?.trackerFactory ?? (await import('../delivery/tracker.js')).createTrackerDelivery;
+  const prepared = await factory({repository:state.candidate.repository,target,mergeReceipt,deploymentReceipt,
+    providerId:provider.id,baseUrl:provider.endpoint,headers:authHeaders(provider,dependencies.env),
+    transport:dependencies.delivery?.transport ?? createNodeProviderTransport(),
+    ...(!writing ? {persistedPayload:pending.payload} : {})});
+  const service = createDeliveryService({store,executor:prepared.executor,providerId:provider.id,timeoutMs:120000,
+    subjectId:'delivery-cli',expectedApproverId:'terminal-human',
+    authority:createAuthorityEnvelope({actorId:'delivery-cli',principal:'agent',actions:writing?['provider.write']:[],ownedPaths:[],commands:[],
+      providers:writing?[{id:provider.id,mode:provider.mode,capabilities:['tracker-update']}]:[]}),
+    approvalRegistry:createApprovalRegistry({approvers:[{id:'terminal-human',principal:'human'}]})});
+  if (!writing) return service.reconcile({expectedVersion:state.version});
+  state = await service.refresh({expectedVersion:state.version});
+  const expiresAt = new Date(Date.now()+5*60*1000).toISOString();
+  state = await service.propose({expectedVersion:state.version,action:'tracker-update',payload:prepared.payload,expiresAt});
+  dependencies.output.log(`Post delivery summary to ${target.issueUrl}`);
+  dependencies.output.log(`${prepared.preview}\n\nRivet delivery operation: ${state.proposal.digest}`);
+  if (!(await confirm(state))) fail('Tracker update was not approved. No comment was posted.', 'INVALID_INPUT');
+  const freshConfig = await reloadConfig();
+  const freshProvider = selectProvider(freshConfig,target,provider.id,true);
+  if (hash(freshProvider) !== hash(provider) || hash(await loadTrackerTarget(state.candidate)) !== hash(target))
+    fail('Tracker source or provider configuration changed. Review a new proposal.', 'REPOSITORY_CONFLICT');
+  const approval = createApprovalReceipt({id:`tracker-${randomUUID()}`,approverId:'terminal-human',approverPrincipal:'human',subjectId:'delivery-cli',
+    action:'provider.write',resource:state.proposal.approvalResource,policyId:'authority.external-write',decision:'approved',expiresAt,singleUse:true});
+  return service.execute({expectedVersion:state.version,proposalDigest:state.proposal.digest,approval});
+}

package/src/commands/delivery-transition.js

@@ -0,0 +1,79 @@
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../cli/output.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import { createDeliveryService } from '../delivery/service.js';
+import { hash, plain } from '../delivery/contract.js';
+import { createAuthorityEnvelope } from '../policy/authority.js';
+import { createApprovalReceipt, createApprovalRegistry } from '../policy/approvals.js';
+import { selectProvider, authHeaders } from './delivery-tracker.js';
+
+function fail(message, code = 'REPOSITORY_CONFLICT') { throw new CliError(message, code); }
+async function select(dependencies, choices) {
+  let timer;
+  try {
+    const index = await Promise.race([
+      Promise.resolve().then(() => dependencies.selectTrackerDestination(choices)),
+      new Promise(resolve => { timer = setTimeout(() => resolve(null), 30000); }),
+    ]);
+    return Number.isInteger(index) && index >= 0 && index < choices.length ? choices[index] : null;
+  } catch { return null; } finally { clearTimeout(timer); }
+}
+
+export async function runTrackerTransition({action,state,store,config,flags,dependencies,reloadConfig,loadTrackerTarget,confirm}) {
+  const writing = action === 'tracker-transition', reconciling = action === 'reconcile';
+  if (writing && state.operations.some(op => op.action === action && op.state === 'succeeded')) return state;
+  const pending = state.operations.find(op => ['dispatching','indeterminate'].includes(op.state));
+  if (writing && pending) fail('Reconcile the pending delivery operation before changing tracker status.');
+  const mergeReceipt = state.operations.find(op => op.action === 'merge' && op.state === 'succeeded')?.receipt;
+  if (!mergeReceipt) fail('Tracker status delivery requires a confirmed merge.');
+  let target, selectedId = flags.provider;
+  if (reconciling) {
+    if (pending?.action !== 'tracker-transition' || state.proposal?.digest !== pending.digest) fail('No pending tracker transition was found.');
+    const p = pending.payload;
+    target = plain({kind:p.kind,issueKey:p.issueKey,issueUrl:p.issueUrl,requestDigest:p.requestDigest});
+    if (selectedId !== undefined && selectedId !== state.proposal.providerId) fail('Reconciliation requires the originally approved tracker provider.');
+    selectedId = state.proposal.providerId;
+  } else {
+    try { target = plain(await loadTrackerTarget(state.candidate)); }
+    catch { fail('This run has no validated Jira/Linear source ticket. A replacement ticket cannot be supplied.','MISSING_CONFIGURATION'); }
+  }
+  const provider = selectProvider(config,target,selectedId,writing,'tracker-transition');
+  if (reconciling && provider.endpoint !== pending.payload.endpoint) fail('Restore the originally approved tracker endpoint before reconciliation.');
+  const intake = await (dependencies.delivery?.transitionFactory ?? (await import('../delivery/tracker-transition.js')).createTrackerTransition)({
+    repository:state.candidate.repository,target,mergeReceipt,providerId:provider.id,baseUrl:provider.endpoint,
+    headers:authHeaders(provider,dependencies.env),transport:dependencies.delivery?.transport ?? createNodeProviderTransport(),
+    ...(reconciling ? {persistedPayload:pending.payload} : {}),
+  });
+  if (action === 'tracker-status') return {...state,trackerStatus:intake.status};
+  let prepared = intake;
+  if (writing) {
+    dependencies.output.log(`Tracker: ${target.issueUrl}\nCurrent status: ${intake.status.current.name}`);
+    const choices = intake.status.destinations.filter(choice => choice.eligible);
+    const labels = choices.map(choice => `${choice.state.name} (${choice.name}; ${choice.state.type})`);
+    if (new Set(labels).size !== labels.length) fail('Some tracker destinations have indistinguishable names. Review these transitions in the tracker before continuing.');
+    for (const [index,choice] of choices.entries()) dependencies.output.log(`${index+1}. ${choice.state.name} (${choice.name}; ${choice.state.type})`);
+    for (const choice of intake.status.destinations.filter(choice => !choice.eligible)) dependencies.output.log(`Unavailable: ${choice.state.name} (${choice.name}): requires fields or a transition screen.`);
+    if (!choices.length) fail('No supported tracker destinations are available. Complete required fields or transition screens in the tracker.');
+    const selected = await select(dependencies,choices);
+    if (!selected) fail('No destination selected. Tracker status was not changed.','INVALID_INPUT');
+    prepared = await intake.select(selected.id);
+    if (prepared.alreadyDesired) return {...state,trackerStatus:intake.status,trackerTransitionNoop:true};
+  }
+  const service = createDeliveryService({store,executor:prepared.executor,providerId:provider.id,timeoutMs:120000,
+    subjectId:'delivery-cli',expectedApproverId:'terminal-human',
+    authority:createAuthorityEnvelope({actorId:'delivery-cli',principal:'agent',actions:writing?['provider.write']:[],ownedPaths:[],commands:[],
+      providers:writing?[{id:provider.id,mode:provider.mode,capabilities:['tracker-transition']}]:[]}),
+    approvalRegistry:createApprovalRegistry({approvers:[{id:'terminal-human',principal:'human'}]})});
+  if (reconciling) return service.reconcile({expectedVersion:state.version});
+  state = await service.refresh({expectedVersion:state.version});
+  const expiresAt = new Date(Date.now()+5*60*1000).toISOString();
+  state = await service.propose({expectedVersion:state.version,action:'tracker-transition',payload:prepared.payload,expiresAt});
+  dependencies.output.log(`${prepared.preview}\nConfirmed merge: ${mergeReceipt.commitSha}\nRivet delivery operation: ${state.proposal.digest}`);
+  dependencies.output.log('Assurance: precheck and readback; the tracker provides no atomic revision condition. Confirmation observes the desired state and cannot prove that this operation alone caused it.');
+  if (!(await confirm(state))) fail('Tracker transition was not approved. No status change was sent.','INVALID_INPUT');
+  const freshProvider = selectProvider(await reloadConfig(),target,provider.id,true,'tracker-transition');
+  if (hash(freshProvider) !== hash(provider) || hash(await loadTrackerTarget(state.candidate)) !== hash(target)) fail('Tracker source or provider configuration changed. Review a new proposal.');
+  const approval = createApprovalReceipt({id:`tracker-transition-${randomUUID()}`,approverId:'terminal-human',approverPrincipal:'human',subjectId:'delivery-cli',
+    action:'provider.write',resource:state.proposal.approvalResource,policyId:'authority.external-write',decision:'approved',expiresAt,singleUse:true});
+  return service.execute({expectedVersion:state.version,proposalDigest:state.proposal.digest,approval});
+}