orches 0.0.0-stage → 0.1.0-beta.1

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# Orches CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Orches is a command-line tool for local development tasks and authenticated control of paired devices. **This is an early, pre-release package**.
+
+## Install (after the first npm release is published)
+
+```sh
+npm install --global orches@next
+orches help
+orches doctor --output text
+```
+
+Requires Node.js 20.9+ and a supported platform. Windows screen capture uses native modules and is available only in an interactive Windows session.
+
+## Authentication and host
+
+```sh
+orches auth login --gateway https://orches-dev.vulcis.com
+orches auth status
+orches device pair --name NOTEBOOK
+orches device list
+orches host start
+```
+
+The DEV Gateway requires a Vulcis Identity account. Remote execution requires an authenticated paired device and its local policy; the CLI does not enable anonymous remote commands. Never paste OAuth tokens into a support ticket.
+
+## Local usage
+
+```sh
+orches help
+orches status
+orches policy status
+orches config list
+orches screen --output screenshot.jpg
+```
+
+The old `orches update` command updates a **Git checkout**, not an npm installation. Automatic npm updates, staged host replacement and rollback are not yet implemented. See [npm release and update plan](https://github.com/vulcis/orches/blob/main/docs/npm-distribution.md).
+
+## Support and license
+
+Repository: https://github.com/vulcis/orches
+
+Issues: https://github.com/vulcis/orches/issues
+
+Copyright Vulcis. **All rights reserved.** This package's license is `UNLICENSED`: public availability of the tarball does not grant a redistribution or modification license.
+
+The npm package contains the CLI runtime only, not the Gateway deployment, credentials or project workspaces.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "orches",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "description": "Orches CLI for local development tools and authenticated device control",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "orches": "./src/cli.js"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vulcis/orches.git"
+  },
+  "homepage": "https://vulcis.com/orches",
+  "bugs": {
+    "url": "https://github.com/vulcis/orches/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "^2.1.2",
+    "@modelcontextprotocol/server": "^2.4.0",
+    "node-screenshots": "0.2.8",
+    "sharp": "0.35.5",
+    "zod": "^4.6.7"
+  },
+  "files": [
+    "src/*.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/agent-instance.js

@@ -0,0 +1,82 @@
+import {randomUUID} from 'node:crypto';
+import {closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+
+const DEVICE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function lockPath(deviceId, directory) {
+ if(typeof deviceId !== 'string' || !DEVICE_ID.test(deviceId)) throw Error('Invalid paired device ID');
+ return join(directory, 'agent-' + deviceId.toLowerCase() + '.lock');
+}
+
+function isProcessAlive(pid) {
+ if(!Number.isSafeInteger(pid) || pid <= 0) return false;
+ try {
+  process.kill(pid, 0);
+  return true;
+ } catch(error) {
+  if(error.code === 'EPERM') return true;
+  if(error.code === 'ESRCH') return false;
+  throw error;
+ }
+}
+
+export function agentInstanceStatus(deviceId, {directory=join(homedir(), '.orches'), alive=isProcessAlive}={}) {
+ const path=lockPath(deviceId, directory);
+ let record;
+ try { record=JSON.parse(readFileSync(path, 'utf8')); }
+ catch(error) {
+  if(error.code === 'ENOENT') return {status:'stopped'};
+  return {status:'stale',pid:null};
+ }
+ if(record?.deviceId !== deviceId || !Number.isSafeInteger(record.pid) ||
+    record.pid <= 0 || typeof record.owner !== 'string') return {status:'stale',pid:null};
+ return {status:alive(record.pid)?'running':'stale',pid:record.pid};
+}
+
+export function acquireAgentInstance(deviceId, {directory=join(homedir(), '.orches'), alive=isProcessAlive}={}) {
+ const path=lockPath(deviceId, directory);
+ mkdirSync(directory, {recursive:true,mode:0o700});
+ const owner=randomUUID();
+ let fd;
+ try { fd=openSync(path, 'wx', 0o600); }
+ catch(error) {
+  if(error.code !== 'EEXIST') throw error;
+  const previous=agentInstanceStatus(deviceId,{directory,alive});
+  if(previous.status === 'running') {
+   throw Error('Host already running for device ' + deviceId + ' (PID ' + previous.pid + '). Run orches host status.');
+  }
+  throw Error('A stale host lock was found for device ' + deviceId + '. Run orches host repair, then orches host start.');
+ }
+ try {
+  writeFileSync(fd, JSON.stringify({deviceId,pid:process.pid,startedAt:new Date().toISOString(),owner})+'\n');
+ } catch(error) {
+  closeSync(fd);
+  unlinkSync(path);
+  throw error;
+ }
+ closeSync(fd);
+ let released=false;
+ return {pid:process.pid,release() {
+  if(released) return;
+  released=true;
+  let stored;
+  try {stored=JSON.parse(readFileSync(path,'utf8'));}
+  catch(error){if(error.code === 'ENOENT')return;throw error;}
+  // Do not remove another process's lease if the file was replaced.
+  if(stored.owner === owner && stored.pid === process.pid) unlinkSync(path);
+ }};
+}
+
+export function repairAgentInstance(deviceId, {directory=join(homedir(), '.orches'), alive=isProcessAlive}={}) {
+ const previous=agentInstanceStatus(deviceId,{directory,alive});
+ if(previous.status === 'running') throw Error('Host is still running (PID ' + previous.pid + '); refusing to delete its lock.');
+ if(previous.status === 'stopped') return {status:'not-needed',deviceId};
+ const path=lockPath(deviceId,directory);
+ // Double-check the process immediately before removing a stale lease.
+ const rechecked=agentInstanceStatus(deviceId,{directory,alive});
+ if(rechecked.status === 'running') throw Error('Host started while checking stale lock; refusing to delete its lock.');
+ if(existsSync(path)) unlinkSync(path);
+ return {status:'repaired',deviceId};
+}

package/src/bridge-worker.js

@@ -0,0 +1,59 @@
+import {spawnSync} from 'node:child_process';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {setTimeout as sleep} from 'node:timers/promises';
+
+const checkoutRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export function readCheckoutRevision(root = checkoutRoot) {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: root, encoding: 'utf8', windowsHide: true, shell: false, timeout: 5000,
+  });
+  const revision = (result.stdout || '').trim();
+  return result.status === 0 && /^[0-9a-f]{40,64}$/i.test(revision) ? revision : null;
+}
+
+function safeRevision(probe) {
+  try { return probe(); } catch { return null; }
+}
+
+/**
+ * Finish each poll before responding to checkout updates.
+ * The Windows host supervisor restarts an exited child from the new source.
+ */
+export async function runBridgeWorker({
+  poll,
+  intervalMs = 5000,
+  getRevision = readCheckoutRevision,
+  wait = sleep,
+  report = () => {},
+  onError = () => {},
+  shouldStop = () => false,
+} = {}) {
+  if (typeof poll !== 'function') throw Error('Bridge poll function is required');
+  if (!Number.isFinite(intervalMs) || intervalMs < 1000) throw Error('Invalid bridge polling interval');
+
+  let initialRevision = safeRevision(getRevision);
+  while (!shouldStop()) {
+    const before = safeRevision(getRevision);
+    if (!initialRevision && before) initialRevision = before;
+    if (initialRevision && before && before !== initialRevision) {
+      return {reason: 'source-updated', previousRevision: initialRevision, revision: before};
+    }
+    try {
+      const jobs = await poll();
+      if (Array.isArray(jobs)) {
+        const actionable = jobs.filter(job => !['ignored','invalid','acknowledged'].includes(job.status));
+        if (actionable.length) report(actionable);
+      }
+    } catch (error) {
+      onError(error);
+    }
+    const after = safeRevision(getRevision);
+    if (initialRevision && after && after !== initialRevision) {
+      return {reason: 'source-updated', previousRevision: initialRevision, revision: after};
+    }
+    await wait(intervalMs);
+  }
+  return {reason: 'stopped'};
+}

package/src/bridge.js

@@ -0,0 +1,140 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { parseEnvelope, validateEnvelope } from './core.js';
+import { execute } from './operations.js';
+import { evaluatePermission } from './permission-policy.js';
+import { createCommandService } from './commands.js';
+import { getSettings } from './settings.js';
+
+const defaultHome = join(homedir(), '.orches');
+function ghCli(args) {
+  const proc = spawnSync(process.platform==='win32'?'gh.exe':'gh', args, {encoding:'utf8', timeout:30000, shell:false, windowsHide:true});
+  return {ok:proc.status===0, output:(proc.stdout||'').slice(0,100000), error:(proc.error?.message||proc.stderr||'').slice(0,1500)};
+}
+function parseGh(result, context) {
+  if (!result.ok) throw Error(context+': '+result.error);
+  try { return JSON.parse(result.output); } catch { throw Error(context+': invalid JSON'); }
+}
+export function markerPath(home, repository, number) {
+  if(!/^[-\w]+\/[-\w.]+$/.test(repository) || !Number.isInteger(number) || number<1)throw Error('Invalid marker identity');
+  return join(home, 'bridge', repository.replace('/','__'), `issue-${number}.json`);
+}
+function readMarker(path) {
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path,'utf8'));
+}
+function writeMarker(path, data) {
+  const tmp=`${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data,null,2), {mode:0o600});
+  renameSync(tmp, path);
+}
+function claimMarker(path, number) {
+  mkdirSync(dirname(path),{recursive:true});
+  try {
+    const fd=openSync(path,'wx',0o600);
+    try { writeFileSync(fd, JSON.stringify({issue:number,state:'started',createdAt:new Date().toISOString()})); }
+    finally {closeSync(fd);}
+    return true;
+  } catch(error) { if(error.code==='EEXIST')return false; throw error; }
+}
+function runAction(job, settings, runner, executor, commandService) {
+  try {
+    if(job.action==='ping')return {ok:true,host:hostname()};
+    if(job.action==='status')return {ok:true,host:hostname(),node:process.version};
+    if(job.action==='agents_list'){
+      const r=runner('paseo',['ls','--json']);
+      return {ok:r.ok,agents:r.ok?parseGh(r,'paseo ls'):[],error:r.ok?'':r.error};
+    }
+    if(job.action==='task_inspect'){
+      const r=runner('gh',['issue','view',String(job.number),'--repo',job.repository,'--json','number,title,state,url']);
+      return {ok:r.ok,data:r.ok?parseGh(r,'task inspect'):null,error:r.ok?'':r.error};
+    }
+    if(job.action==='exec'){
+      if(!settings.bridge.allowRemoteExec)throw Error('Remote execution disabled by host settings');
+      const risk=evaluatePermission(job,settings.permissions);
+      if(risk.action==='deny')throw Error(risk.reason);
+      if(risk.action==='review'){
+        const pending=commandService.submit({
+          program:job.program,args:job.args,cwd:job.cwd,
+          timeoutMs:Math.min(job.timeoutMs||settings.execution.timeoutMs,60000),
+        });
+        return {ok:true,status:'pending_approval',id:pending.id,reason:risk.reason,rule:risk.rule};
+      }
+      // A verified GitHub author may run ordinary commands without an executable allowlist.
+      // The restricted mode still supports explicit workspace fences when needed.
+      if(settings.commands?.mode==='restricted'){
+        const allowed=(settings.bridge.allowedWorkspaces||[]).map(x=>resolve(x).toLowerCase());
+        if(!allowed.length||!allowed.includes(resolve(job.cwd).toLowerCase()))throw Error('Working directory not enabled in host settings');
+      }
+      const limit=settings.execution.timeoutMs;
+      return executor(job.program,job.args,{cwd:job.cwd,timeoutMs:Math.min(job.timeoutMs||limit,limit)});
+    }
+    throw Error('Unsupported action');
+  }catch(error){return {ok:false,error:String(error.message||error)}}
+}
+function deliveryMarker(repository, number) {
+  return `<!-- orches-delivery:${repository}:${number} -->`;
+}
+function hasComment(gh, repository, number) {
+  const r=gh(['issue','view',String(number),'--repo',repository,'--json','comments']);
+  if(!r.ok)throw Error('Delivery lookup failed: '+r.error);
+  const comments=parseGh(r,'delivery lookup').comments||[];
+  return comments.some(c=>typeof c.body==='string'&&c.body.includes(deliveryMarker(repository,number)));
+}
+export function processBridgeIssue(item, settings, {repository=settings.bridge.repository, home=defaultHome, gh=ghCli, runner=processRunner, executor=execute, commandService=createCommandService()}={}) {
+  if(!item.title?.startsWith('[Orches]')||item.author?.login!==settings.bridge.author)return {status:'ignored'};
+  let job;
+  try { job=validateEnvelope(parseEnvelope(item.body)); }
+  catch { return {status:'invalid'}; }
+  const path=markerPath(home,repository,item.number);
+  let marker=readMarker(path);
+  if(marker?.state==='acknowledged')return {status:'acknowledged'};
+  if(!marker) {
+    if(!claimMarker(path,item.number))return {status:'claimed-elsewhere'};
+    marker=readMarker(path);
+    const result=runAction(job,settings,runner,executor,commandService);
+    marker={...marker,state:'completed',result,finishedAt:new Date().toISOString()};
+    writeMarker(path,marker);
+  } else if(marker.state==='started'){
+    // The previous process might have executed part of the operation. Never replay it automatically.
+    marker={...marker,state:'completed',result:{ok:false,error:'Execution interrupted. Original outcome unknown; manual retry requires a new issue.'}};
+    writeMarker(path,marker);
+  }
+  if(marker.state==='completed'){
+    if(hasComment(gh,repository,item.number)){
+      marker={...marker,state:'commented',commentedAt:new Date().toISOString()};
+      writeMarker(path,marker);
+    }else{
+      const message=deliveryMarker(repository,item.number)+'\nOrches result:\n```json\n'+JSON.stringify(marker.result,null,2).slice(0,12000)+'\n```';
+      const sent=gh(['issue','comment',String(item.number),'--repo',repository,'--body',message]);
+      if(!sent.ok) return {status:'delivery-retry',error:sent.error};
+      marker={...marker,state:'commented',commentedAt:new Date().toISOString()};
+      writeMarker(path,marker);
+    }
+  }
+  if(marker.state==='commented'){
+    const closed=gh(['issue','close',String(item.number),'--repo',repository,'--reason',marker.result.ok?'completed':'not planned']);
+    if(!closed.ok)return {status:'close-retry',error:closed.error};
+    writeMarker(path,{...marker,state:'acknowledged',acknowledgedAt:new Date().toISOString()});
+    return {status:'acknowledged'};
+  }
+  return {status:marker.state};
+}
+export function pollBridgeOnce({settings=getSettings(),home=defaultHome,gh=ghCli,runner}={}) {
+  const repository=settings.bridge.repository;
+  if(!/^[-\w]+\/[-\w.]+$/.test(repository))throw Error('Invalid bridge.repository');
+  const r=gh(['issue','list','--repo',repository,'--state','open','--limit','100','--json','number,title,body,author']);
+  const issues=parseGh(r,'bridge poll');
+  const results=[];
+  for(const issue of issues) {
+    try {results.push({number:issue.number,...processBridgeIssue(issue,settings,{repository,home,gh,runner})});}
+    catch(error){results.push({number:issue.number,status:'error',error:String(error.message||error)});}
+  }
+  return results;
+}
+export function processRunner(program,args) {
+  const r=spawnSync(program,args,{encoding:'utf8',timeout:30000,shell:process.platform==='win32',windowsHide:true});
+  return {ok:r.status===0,output:(r.stdout||'').slice(0,8000),error:(r.error?.message||r.stderr||'').slice(0,1000)};
+}

package/src/cli.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { homedir, hostname } from 'node:os';
+import { join, resolve } from 'node:path';
+import {writeFileSync} from 'node:fs';
+import {captureWindowsScreenshot} from './screenshot.js';
+import { pollBridgeOnce, processRunner } from './bridge.js';
+import { runBridgeWorker } from './bridge-worker.js';
+import { diagnose } from './doctor.js';
+import { runDoctor } from './doctor-report.js';
+import { parseSetupOptions, buildSetupPlan, applySetupPlan } from './setup.js';
+import { execute, updateCheckout } from './operations.js';
+import {createCommandService} from './commands.js';
+import {getSettings,setSetting,settingsPath,rememberApprovedCommand} from './settings.js';
+import {getPairedDevice,listEdgeDevices,pairEdgeDevice,pollEdgeOnce,revokeEdgeDevice,runEdgeAgent} from './edge-agent.js';
+import {getEdgeLogin, refreshEdgeLogin, loginEdge, logoutEdge} from './edge-auth.js';
+import {acquireAgentInstance, agentInstanceStatus, repairAgentInstance} from './agent-instance.js';
+const home = join(homedir(), '.orches');
+let [command, subcommand, ...args] = process.argv.slice(2);
+// Normalize pre-v1 command names at the parser boundary while keeping one implementation per capability.
+if(command==='login'&&['--help','-h'].includes(subcommand)){subcommand='--help';args=[];command='auth';}
+else if(command==='login'||command==='logout'){args=[...(subcommand?[subcommand]:[]),...args];subcommand=command;command='auth';}
+if(command==='devices')command='device';
+if(command==='screenshot')command='screen';
+if(command==='permissions')command='policy';
+if(command==='settings')command='config';
+function run(exe, argv, cwd=process.cwd()) {
+  const r=spawnSync(exe,argv,{cwd,encoding:'utf8',timeout:30000,shell:process.platform==='win32'});
+  if(r.error) throw r.error;
+  return {ok:r.status===0,exitCode:r.status,output:(r.stdout||'').slice(0,8000),error:(r.stderr||'').slice(0,1000)};
+}
+function output(v){console.log(JSON.stringify(v,null,2));}
+function printDevices(devices){
+ if(!devices.length){console.log('No paired devices for this account.');return;}
+ for(const device of devices){
+  const seen=device.lastSeenAt??'never';
+  console.log(`${device.status==='online'?'ONLINE ':'OFFLINE'}  ${String(device.name).padEnd(22)}  ${device.id}  Last seen: ${seen}`);
+ }
+}
+async function main(){
+ if(command==='auth'){
+  if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches auth login --gateway HTTPS_URL | status | logout');return}
+  if(subcommand==='status'){
+   if(args.length)throw Error('Usage: orches auth status');
+   try{const current=getEdgeLogin({allowExpired:true});output({status:current.expiresAt>Date.now()?'connected':'expired',gateway:current.gateway,expiresAt:current.expiresAt});}
+   catch(error){if(!String(error.message).startsWith('No Vulcis account linked.'))throw error;output({status:'disconnected'});}
+   return;
+  }
+  if(subcommand==='login'){
+   if(args.includes('--help')||args.includes('-h')){console.log('Usage: orches auth login --gateway HTTPS_URL');return}
+   const argv=args;
+   if(argv.length!==2||argv[0]!=='--gateway')throw Error('Usage: orches auth login --gateway HTTPS_URL');
+   const result=await loginEdge({gateway:argv[1]});
+   output(result);return;
+  }
+  if(subcommand==='logout'){
+   if(args.length)throw Error('Usage: orches auth logout');
+   output(await logoutEdge());return;
+  }
+  throw Error('Usage: orches auth login|status|logout');
+ }
+ if(command==='screen'){
+  const argv=process.argv.slice(3);
+  if(argv.includes('--help')||argv.includes('-h')){console.log('Usage: orches screen --output FILE.jpg [--display 0..7] [--overwrite]');return;}
+  let filename=null,display=0,overwrite=false;
+  for(let i=0;i<argv.length;i++){
+   if(argv[i]==='--output'){filename=argv[++i];}
+   else if(argv[i]==='--display'){display=Number(argv[++i]);}
+   else if(argv[i]==='--overwrite'){overwrite=true;}
+   else throw Error('Usage: orches screen --output FILE.jpg [--display 0..7] [--overwrite]');
+  }
+  if(!filename || !filename.toLowerCase().endsWith('.jpg'))throw Error('Screenshot output must be an explicit .jpg path');
+  const shot=await captureWindowsScreenshot(display);
+  const destination=resolve(filename);
+  writeFileSync(destination,Buffer.from(shot.imageData,'base64'),{flag:overwrite?'w':'wx'});
+  output({status:'saved',file:destination,width:shot.width,height:shot.height,bytes:Buffer.from(shot.imageData,'base64').length});
+  return;
+ }
+ if(command==='device'){
+  if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches device pair --name NAME | list [--output text|json] | status | revoke DEVICE_ID');return;}
+  const options={};
+  for(let i=0;i<args.length;i++){
+   if(args[i]==='--gateway')options.gateway=args[++i];
+   else if(args[i]==='--name')options.name=args[++i];
+   else if(args[i]==='--output')options.output=args[++i];
+   else if(args[i]==='--json')options.output='json';
+   else if(args[i].startsWith('--'))throw Error('Unknown option '+args[i]);
+   else options.deviceId=args[i];
+  }
+  if(['pair','list','revoke'].includes(subcommand)){
+   const auth=await refreshEdgeLogin();
+   if(options.gateway&&options.gateway!==auth.gateway)throw Error('Device gateway differs from OAuth login. Run orches auth login --gateway URL first.');
+   if(subcommand==='pair'){
+    if(!options.name)throw Error('Usage: orches device pair --name NAME');
+    output(await pairEdgeDevice({gateway:auth.gateway,name:options.name,accessToken:auth.accessToken}));return;
+   }
+   if(subcommand==='list'){
+    if(options.output&&!['json','text'].includes(options.output))throw Error('Usage: orches device list --output text|json');
+    const response=await listEdgeDevices({gateway:auth.gateway,accessToken:auth.accessToken});
+    if(options.output==='text'||(!options.output && process.stdout.isTTY))printDevices(response.devices??[]);
+    else output(response);
+    return;
+   }
+   if(!options.deviceId)throw Error('Usage: orches device revoke DEVICE_ID');
+   output(await revokeEdgeDevice({gateway:auth.gateway,accessToken:auth.accessToken,deviceId:options.deviceId}));return;
+  }
+  if(subcommand==='status'){
+   const device=getPairedDevice();
+   output(device?{status:'paired',deviceId:device.deviceId,gateway:device.gateway}:{status:'not-paired'});return;
+  }
+  throw Error('Usage: orches device pair|list|status|revoke');
+ }
+ if(command==='host'){
+  if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches host start|status|once|repair');return}
+  if(subcommand==='status'){
+   const device=getPairedDevice();
+   if(!device){output({status:'not-paired'});return;}
+   const instance=agentInstanceStatus(device.deviceId);
+   output({status:'paired',deviceId:device.deviceId,gateway:device.gateway,mode:'foreground',
+     hostStatus:instance.status,hostPid:instance.pid??null});return;
+  }
+  if(subcommand==='repair'){
+   const device=getPairedDevice();if(!device)throw Error('No Edge device is paired. Run orches device pair first.');
+   output(repairAgentInstance(device.deviceId));return;
+  }
+  if(subcommand==='once'){
+   const device=getPairedDevice();if(!device)throw Error('No Edge device is paired. Run orches device pair first.');
+   output(await pollEdgeOnce(device));return;
+  }
+  if(subcommand==='start'){
+   const device=getPairedDevice();if(!device)throw Error('No Edge device is paired. Run orches device pair first.');
+   const instance=acquireAgentInstance(device.deviceId);
+   let stop=false;
+   const stopSignal=()=>{stop=true;};
+   process.once('SIGINT',stopSignal);process.once('SIGTERM',stopSignal);
+   output({status:'running',deviceId:device.deviceId,gateway:device.gateway,
+     message:'Host started. Polling for commands. Press Ctrl+C to stop.'});
+   try {
+    await runEdgeAgent({shouldStop:()=>stop,report:result=>output(result),
+      onError:error=>console.error('Host polling error: '+error.message)});
+   } finally {
+    instance.release();
+    process.removeListener('SIGINT',stopSignal);process.removeListener('SIGTERM',stopSignal);
+    output({status:'stopped',deviceId:device.deviceId,message:'Host stopped.'});
+   }
+   return;
+  }
+  throw Error('Usage: orches host start|status|once|repair');
+ }
+ if(command==='setup'){
+  if(subcommand==='--help'||subcommand==='-h'){
+   console.log('Usage: orches setup [--plan] [--profile development|worker] [--with codex,opencode,paseo,paseo-hub,cloudflared|none]');
+   console.log('Interactive by default. Installations and sign-ins always require confirmation.');
+   return;
+  }
+  const options=parseSetupOptions(process.argv.slice(3));
+  const current=await runDoctor(getSettings(),{profile:options.profile});
+  const plan=buildSetupPlan(current,options);
+  if(options.plan){output(plan);return}
+  if(!process.stdin.isTTY||!process.stdout.isTTY){
+   throw Error('Interactive terminal required. Use orches setup --plan to inspect the actions.');
+  }
+  console.log('Orches Setup ('+options.profile+')');
+  console.log('The CLI will offer '+plan.steps.length+' approved actions. It will not start workers or agents.');
+  if(!plan.steps.length)console.log('No setup actions are required for selected integrations.');
+  const results=await applySetupPlan(plan);
+  const finalReport=await runDoctor(getSettings(),{profile:options.profile});
+  const authChecks={
+   'github.login':'github.auth',
+   'codex.login':'integration.codex.credentials',
+   'opencode.login':'integration.opencode.credentials',
+  };
+  for(const result of results){
+   if(result.status!=='executed'||!result.id.endsWith('.login'))continue;
+   const checkId=authChecks[result.id];
+   const check=finalReport.checks.find(item=>item.id===checkId);
+   result.verification=checkId?(check?.status==='pass'?'configured':'not_confirmed'):'not_checked';
+  }
+  console.log('Setup results: '+JSON.stringify(results));
+  console.log('Doctor summary: '+JSON.stringify(finalReport.summary));
+  for(const check of finalReport.checks.filter(item=>['warn','fail','unknown'].includes(item.status))){
+   console.log('['+check.status.toUpperCase()+'] '+check.id+': '+check.message);
+   if(check.remedy)console.log('  Action: '+check.remedy);
+  }
+  if(results.some(result=>result.status==='failed'||result.verification==='not_confirmed'))process.exitCode=1;
+  return;
+ }
+ if(command==='commands'){
+  const service=createCommandService();
+  if(subcommand==='list'){output(service.list());return}
+  if(subcommand==='status'){if(args.length!==1)throw Error('Usage: orches commands status REQUEST_ID');const result=service.get(args[0]);if(!result)throw Error('Command request not found');output(result);return}
+  if(subcommand==='approve'){if(args.length!==2||args[1]!=='--confirm')throw Error('Usage: orches commands approve REQUEST_ID --confirm');const request=service.list().find(item=>item.id===args[0]);const result=service.approve(args[0],getSettings());const remembered=request&&result.status==='completed'?rememberApprovedCommand(request):false;output({...result,rememberedApproval:remembered});return}
+  if(subcommand==='deny'){if(args.length!==1)throw Error('Usage: orches commands deny REQUEST_ID');output(service.deny(args[0]));return}
+  throw Error('Usage: orches commands list|status REQUEST_ID|approve REQUEST_ID --confirm|deny REQUEST_ID');
+ }
+ if(command==='policy'){
+  if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches policy status | mode manual|balanced|automatic|full | check PROGRAM [ARG...]');return}
+  const config=getSettings();
+  if(subcommand==='status'||!subcommand){output(config.permissions);return;}
+  if(subcommand==='mode'){
+   if(args.length!==1||!['manual','balanced','automatic','full'].includes(args[0]))throw Error('Usage: orches policy mode manual|balanced|automatic|full');
+   output(setSetting('permissions.mode',args[0]).permissions);return;
+  }
+  if(subcommand==='check'){
+   if(args.length<1)throw Error('Usage: orches policy check PROGRAM [ARG...]');
+   const {evaluatePermission}=await import('./permission-policy.js');
+   output(evaluatePermission({program:args[0],args:args.slice(1)},config.permissions));return;
+  }
+  throw Error('Usage: orches policy status|mode manual|balanced|automatic|full|check PROGRAM [ARG...]');
+ }
+ if(command==='config'){if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches config list|get KEY|set KEY JSON_VALUE|path');return}if(subcommand==='path'){console.log(settingsPath());return}if(subcommand==='list'||subcommand==='show'||!subcommand){output(getSettings());return}if(subcommand==='get'){const value=args[0]?.split('.').reduce((o,k)=>o?.[k],getSettings());if(value===undefined)throw Error('Unknown setting');output(value);return}if(subcommand==='set'){const key=args[0];const raw=args.slice(1).join(' ');if(!key||!raw)throw Error('Usage: orches config set section.key JSON_VALUE');output(setSetting(key,JSON.parse(raw)));return}throw Error('Usage: orches config list|get|set|path')}
+
+ if(command==='exec'){if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches exec [--cwd DIR] [--timeout MS] -- PROGRAM [ARG...]');return}const sep=process.argv.indexOf('--');if(sep<0||!process.argv[sep+1])throw Error('Usage: orches exec [--cwd DIR] [--timeout MS] -- PROGRAM [ARG...]');const before=process.argv.slice(3,sep);let cwd=process.cwd(),timeoutMs=30000;for(let i=0;i<before.length;i++){if(before[i]==='--cwd')cwd=before[++i];else if(before[i]==='--timeout')timeoutMs=Number(before[++i]);else throw Error('Unknown option '+before[i])}const result=execute(process.argv[sep+1],process.argv.slice(sep+2),{cwd,timeoutMs});output(result);if(!result.ok)process.exitCode=1;return}
+ if(command==='update'){if(subcommand==='--help'||subcommand==='-h'){console.log('Usage: orches update [--dir PATH] [--ref BRANCH]');return}let dir=process.cwd(),ref='main';for(let i=0;i<process.argv.slice(3).length;i++){const a=process.argv.slice(3);if(a[i]==='--dir')dir=a[++i];else if(a[i]==='--ref')ref=a[++i];else throw Error('Unknown option '+a[i])}output(updateCheckout(dir,ref));return}
+ if(command==='help'||command==='--help'||!command){console.log('Orches CLI: auth login|status|logout | host start|status|once|repair | device pair|list|status|revoke | policy status|mode|check | config list|get|set|path | screen --output FILE.jpg [--display N] | exec -- PROGRAM [ARG...] | setup | doctor | update | status | commands list|status|approve|deny');console.log('Migration: login/logout → auth; devices → device; screenshot → screen; settings → config; permissions → policy; agent → host (agent command removed).');return}
+ if(command==='doctor'){
+  if(subcommand==='--help'||subcommand==='-h'){
+   console.log('Usage: orches doctor [--deep] [--profile development|worker] [--cwd PATH] [--timeout-ms N] [--output json|text] [--strict]');
+   return;
+  }
+  const options={};
+  let format='json', strict=false;
+  const argv=process.argv.slice(3);
+  for(let i=0;i<argv.length;i++){
+   const token=argv[i];
+   if(token==='--deep')options.deep=true;
+   else if(token==='--strict')strict=true;
+   else if(['--profile','--cwd','--timeout-ms','--output'].includes(token)){
+    const value=argv[++i];
+    if(value===undefined)throw Error('Missing value for '+token);
+    if(token==='--profile')options.profile=value;
+    else if(token==='--cwd')options.cwd=value;
+    else if(token==='--timeout-ms')options.timeoutMs=Number(value);
+    else format=value;
+   }else throw Error('Unknown doctor option: '+token);
+  }
+  if(!['json','text'].includes(format))throw Error('Invalid output format');
+  let settings,configError=false;
+  try{settings=getSettings()}catch{settings={};configError=true}
+  const report=await runDoctor(settings,{...options,configError});
+  if(format==='json')output(report);
+  else{
+   console.log('Orches Doctor ('+report.profile+', '+report.mode+')');
+   for(const check of report.checks){
+    console.log('['+check.status.toUpperCase()+'] '+check.id+': '+check.message);
+    if(check.remedy)console.log('  Action: '+check.remedy);
+   }
+   console.log('Summary: '+JSON.stringify(report.summary));
+   if(report.summary.warn||report.summary.fail)console.log('Next: orches setup --plan (review), then orches setup (guided repair).');
+  }
+  if(strict&&(report.summary.fail>0||report.summary.warn>0))process.exitCode=2;
+  return;
+ }
+ if(command==='status'){output({host:hostname(),node:process.version,platform:process.platform,tools:Object.fromEntries(['gh','paseo','opencode','codex'].map(t=>{try{return [t,run(t,['--version']).ok]}catch{return [t,false]}}))});return}
+ if(command==='agents'&&subcommand==='list'){const r=run('paseo',['ls','--json']);if(!r.ok)throw Error(r.error);output(JSON.parse(r.output));return}
+ if(command==='quotas'){output({status:'not-configured',message:'Provider quota adapters are not yet implemented; no balances inferred.'});return}
+ if(command==='task'&&subcommand==='inspect'){const ref=args[0];if(!/^[-\w]+\/[-\w.]+#\d+$/.test(ref||''))throw Error('Expected owner/repo#number');const [repo,num]=ref.split('#');const r=run('gh',['issue','view',num,'--repo',repo,'--json','number,title,state,url,labels']);if(!r.ok)throw Error(r.error);output(JSON.parse(r.output));return}
+ if(command==='bridge'&&subcommand==='doctor'){output({home,configPath:settingsPath(),settings:getSettings().bridge,hint:'GitHub Bridge is experimental. Prefer authenticated MCP for future remote execution.'});return}
+ if(command==='bridge'&&subcommand==='once'){output(pollBridgeOnce({runner:processRunner}));return}
+ if(command==='bridge'&&subcommand==='start'){
+  const seconds=Math.max(5,Number(process.env.ORCHES_POLL_SECONDS||getSettings().bridge.pollSeconds));
+  const result=await runBridgeWorker({
+   intervalMs:seconds*1000,
+   poll:()=>pollBridgeOnce({runner:processRunner}),
+   report:jobs=>output(jobs),
+   onError:e=>console.error(e.message),
+  });
+  if(result.reason==='source-updated')console.log('Bridge source updated; exiting for host restart.');
+  return;
+ }
+ throw Error('Unknown command. Run orches help');
+}
+main().catch(e=>{console.error(e.message);process.exitCode=1});