@omnitron-dev/omnitron 0.3.0 → 0.3.2

package/dist/cli/omnitron.js

@@ -5,40 +5,98 @@
  * Entry point. Uses commander for command parsing,
  * @xec-sh/kit for TUI rendering.
  */
-import { Command } from 'commander';
+import { OutputCommand, prepareCommandOutput } from './output-command.js';
 import { CLI_VERSION } from '../config/defaults.js';
-import { setEnvOverride } from '../shared/env-config.js';
-const program = new Command();
+import { exitAfterOutput } from './exit-after-output.js';
+const program = new OutputCommand();
+let foregroundDaemonRunning = false;
+program.command('migrate [action]')
+    .description('Inspect or execute application migrations (default: status)')
+    .option('-c, --config <path>', 'Migration config (default: omnitron.migrations.ts)')
+    .option('--daemon', 'Use the local daemon database and built-in registry')
+    .option('--steps <count>', 'Number of migrations to roll back with down')
+    .option('--to <name>', 'Apply through this migration, inclusive')
+    .option('--dry-run', 'Preview up/down without writing to the database')
+    .structuredAction(async (action = 'status', options) => {
+    const { migrateCommand } = await import('../commands/migrate.js');
+    await migrateCommand(action, options);
+});
 program.name('omnitron').description('Production-grade Titan application supervisor').version(CLI_VERSION);
 // Global --json flag toggles structured machine-readable output and
 // suppresses spinners / styled prose. Also honors `OMNITRON_OUTPUT=json`
 // for environments where flag plumbing is awkward (CI templates, hooks).
 program.option('--json', 'Emit machine-readable JSON output (no spinners, no styling)');
-program.hook('preAction', async (cmd, actionCommand) => {
-    const opts = cmd.opts();
-    if (opts['json'] || process.env['OMNITRON_OUTPUT'] === 'json') {
-        // Update both the actual env (for child processes / subprocess
-        // inheritance) and the cached snapshot in env-config so
-        // subsequent getEnv() readers in this process see the flag.
-        process.env['OMNITRON_OUTPUT'] = 'json';
-        setEnvOverride({ OMNITRON_OUTPUT: 'json' });
-        // Most commands render tables regardless of this flag and say nothing
-        // about it, so a caller asking for JSON silently receives a picture of a
-        // table. The guard makes that refusal explicit and parseable.
-        // The full path, not the leaf: `status` alone names four different
-        // subcommands, so the message has to say which one refused.
-        const path = [];
-        for (let node = actionCommand; node; node = node.parent) {
-            if (node.parent)
-                path.unshift(node.name());
-        }
-        const { installJsonModeGuard } = await import('../commands/output.js');
-        installJsonModeGuard(path.join(' ') || actionCommand.name());
-    }
-});
+program.hook('preAction', (_root, actionCommand) => prepareCommandOutput(actionCommand));
 // ============================================================================
 // Daemon Lifecycle
 // ============================================================================
+const backend = program.command('backend').description('Inspect and replace the control plane without restarting resident applications');
+const ownerRecovery = backend.command('owner-reconcile').description('Explicit offline recovery after an execution-owner crash; never stops applications');
+ownerRecovery.command('prepare <worker-pids>').description('Seal native recovery evidence on macOS/Linux; pass every recorded application/worker/descendant PID, comma-separated')
+    .structuredAction(async (pids) => { const { ownerReconciliationCommand } = await import('../daemon/owner-reconciliation.js'); await ownerReconciliationCommand('prepare', pids); });
+ownerRecovery.command('acknowledge <plan>').description('Certify quiescent native ownership groups after a separately approved drain, preserving the crash receipt')
+    .structuredAction(async (file) => { const { ownerReconciliationCommand } = await import('../daemon/owner-reconciliation.js'); await ownerReconciliationCommand('acknowledge', file); });
+const schema = backend.command('schema').description('Prepare and apply reviewed compatible schema expansions');
+schema.command('prepare <runtime>').description('Inspect the current schema and save an exact expansion plan without database writes')
+    .option('--from-plan <plan>', 'Bind an already applied expansion to a corrected candidate after rollback')
+    .structuredAction(async (runtime, options) => {
+    const { backendSchemaPrepareCommand } = await import('../commands/backend.js');
+    await backendSchemaPrepareCommand(runtime, options);
+});
+schema.command('apply <plan>').description('Apply or resume a reviewed expansion under the shared migration lock')
+    .structuredAction(async (plan) => {
+    const { backendSchemaApplyCommand } = await import('../commands/backend.js');
+    await backendSchemaApplyCommand(plan);
+});
+const guardian = backend.command('guardian').description('Update independent service supervision while preserving the execution owner');
+guardian.command('prepare <runtime>').description('Install a sealed management runtime and save a private guardian transition plan')
+    .structuredAction(async (runtime) => {
+    const { backendSupervisorPrepareCommand } = await import('../commands/backend.js');
+    await backendSupervisorPrepareCommand(runtime);
+});
+guardian.command('apply <plan>').description('Apply or resume a prepared guardian transition; preserve execution ownership')
+    .option('--check', 'Recheck a prepared transition against the current host before approval')
+    .structuredAction(async (plan, options) => {
+    const { backendSupervisorApplyCommand } = await import('../commands/backend.js');
+    await backendSupervisorApplyCommand(plan, options.check === true);
+});
+backend.command('install <runtime>').description('Copy a sealed runtime into permanent storage without activation')
+    .structuredAction(async (runtime) => {
+    const { backendInstallCommand } = await import('../commands/backend.js');
+    await backendInstallCommand(runtime);
+});
+backend.command('installation').description('Inspect the cold-start selection and any unfinished activation')
+    .structuredAction(async () => {
+    const { backendInstallationCommand } = await import('../commands/backend.js');
+    await backendInstallationCommand();
+});
+backend.command('select <sha256>').description('Select an installed runtime while backend and execution owner are stopped')
+    .option('--check', 'Verify cold selection and rollback compatibility while services are running')
+    .structuredAction(async (sha256, options) => {
+    const { backendSelectCommand } = await import('../commands/backend.js');
+    await backendSelectCommand(sha256, options.check);
+});
+backend.command('abort <checkpoint>').description('Cancel preparation before backend retirement')
+    .structuredAction(async (checkpoint) => {
+    const { backendAbortCommand } = await import('../commands/backend.js');
+    await backendAbortCommand(checkpoint);
+});
+backend.command('status').description('Show backend and execution-owner capabilities').structuredAction(async () => {
+    const { backendStatusCommand } = await import('../commands/backend.js');
+    await backendStatusCommand();
+});
+backend.command('upgrade <dist>').description('Activate a built backend artifact; retain application processes')
+    .option('--check', 'Validate compatibility without draining or activating')
+    .option('--schema-plan <path>', 'Require the exact applied expansion plan for a schema-changing upgrade or rollback')
+    .structuredAction(async (dist, options) => {
+    const { backendUpgradeCommand } = await import('../commands/backend.js');
+    await backendUpgradeCommand(dist, options);
+});
+backend.command('recover [checkpoint]').description('Recover a dead backend from its certified state, or reconcile an explicit activation checkpoint')
+    .structuredAction(async (checkpoint) => {
+    const { backendRecoverCommand } = await import('../commands/backend.js');
+    await backendRecoverCommand(checkpoint);
+});
 program
     .command('up')
     .description('Start omnitron daemon (background by default)')
@@ -53,7 +111,7 @@ program
     .option('--no-webapp', 'Disable Console UI (webapp) auto-start')
     .action(async (opts) => {
     const { upCommand } = await import('../commands/up.js');
-    await upCommand({
+    const completion = await upCommand({
         configPath: opts.config,
         project: opts.project,
         foreground: opts.foreground,
@@ -63,6 +121,7 @@ program
         slave: opts.slave,
         webapp: opts.webapp,
     });
+    foregroundDaemonRunning = completion === 'foreground-running';
 });
 program
     .command('down')
@@ -81,6 +140,8 @@ service
     .command('install')
     .description('Install + start the OS service (macOS launchd / Linux systemd)')
     .option('--scope <scope>', 'user (stops at logout) or system (starts at boot, needs root). Default: system for a slave, user otherwise')
+    .option('--prepare', 'Write an independent supervision plan without stopping processes or loading OS services')
+    .option('--owner-runtime <sha256>', 'Use an already installed sealed owner runtime; defaults to the selected runtime')
     .action(async (options) => {
     if (options.scope && options.scope !== 'user' && options.scope !== 'system') {
         const { log } = await import('@xec-sh/kit');
@@ -89,7 +150,7 @@ service
         return;
     }
     const { serviceInstall } = await import('../commands/service.js');
-    await serviceInstall(options.scope ? { scope: options.scope } : {});
+    await serviceInstall({ ...(options.scope ? { scope: options.scope } : {}), ...(options.prepare ? { prepare: true } : {}), ...(options.ownerRuntime !== undefined ? { ownerRuntime: options.ownerRuntime } : {}) });
 });
 service
     .command('uninstall')
@@ -119,10 +180,18 @@ project
 project
     .command('list')
     .description('List registered projects')
-    .action(async () => {
+    .structuredAction(async () => {
     const { projectListCommand } = await import('../commands/project.js');
     await projectListCommand();
 });
+project
+    .command('topology [name]')
+    .description('Inspect configured dependencies without exposing credentials')
+    .option('--stack <name>', 'Limit to one stack')
+    .structuredAction(async (name, options) => {
+    const { projectTopologyCommand } = await import('../commands/project.js');
+    await projectTopologyCommand(name, options);
+});
 project
     .command('remove <name>')
     .description('Remove a project from registry')
@@ -130,6 +199,24 @@ project
     const { projectRemoveCommand } = await import('../commands/project.js');
     await projectRemoveCommand(name);
 });
+const configuration = project.command('configuration').description('Manage configuration sources inside one project');
+configuration.command('list <project>').description('Show project stack sources and preserved runtime identities')
+    .structuredAction(async (name) => {
+    const { projectConfigurationCommand } = await import('../commands/project.js');
+    await projectConfigurationCommand('list', name);
+});
+configuration.command('import <project> <name> <path>').description('Import stack configuration without restarting applications')
+    .option('--registration <name>', 'Preserve an existing registration and its execution/history namespace')
+    .requiredOption('--stack <source=target...>', 'Map each source stack to its name inside the project')
+    .structuredAction(async (projectName, name, directory, options) => {
+    const { projectConfigurationCommand } = await import('../commands/project.js');
+    await projectConfigurationCommand('import', projectName, name, directory, options);
+});
+configuration.command('detach <project> <name>').description('Undo a configuration import; keep processes and history intact')
+    .structuredAction(async (projectName, name) => {
+    const { projectConfigurationCommand } = await import('../commands/project.js');
+    await projectConfigurationCommand('detach', projectName, name);
+});
 project
     .command('scan')
     .description('Scan app bootstraps and show infrastructure requirements')
@@ -143,12 +230,43 @@ project
 // ============================================================================
 // Stack Management
 // ============================================================================
+const topology = program.command('topology').description('Inspect, edit and plan desired application placement');
+topology.command('refresh <project> [stack]')
+    .description('Read trusted bootstrap declarations in isolated processes; save metadata without restarting workloads (admin)')
+    .structuredAction(async (projectName, stackName) => {
+    const { topologyCommand } = await import('../commands/topology.js');
+    await topologyCommand('refresh', projectName, stackName);
+});
+for (const action of ['show', 'export', 'plan']) {
+    topology.command(`${action} <project> <stack>`)
+        .description(action === 'export'
+        ? 'Export portable topology JSON'
+        : action === 'plan'
+            ? 'Validate the saved draft and preview changes'
+            : 'Show desired placement and observation gaps')
+        .structuredAction(async (projectName, stackName) => {
+        const { topologyCommand } = await import('../commands/topology.js');
+        await topologyCommand(action, projectName, stackName);
+    });
+}
+topology.command('draft <project> <stack> <file>')
+    .description('Save a versioned draft from JSON; no workloads change')
+    .structuredAction(async (projectName, stackName, file) => {
+    const { topologyCommand } = await import('../commands/topology.js');
+    await topologyCommand('draft', projectName, stackName, file);
+});
+topology.command('apply <project> <stack> <plan>')
+    .description('Accept a reviewed target; executable deployment configuration is unchanged')
+    .structuredAction(async (projectName, stackName, plan) => {
+    const { topologyCommand } = await import('../commands/topology.js');
+    await topologyCommand('apply', projectName, stackName, plan);
+});
 const stack = program.command('stack').aliases(['stacks']).description('Manage deployment stacks across projects');
 stack
     .command('list')
     .description('List all stacks across all projects')
     .option('-p, --project <name>', 'Filter to specific project')
-    .action(async (opts) => {
+    .structuredAction(async (opts) => {
     const { stackListCommand } = await import('../commands/stack.js');
     await stackListCommand({ project: opts.project });
 });
@@ -171,10 +289,31 @@ stack
 stack
     .command('status <project> <stack>')
     .description('Show stack detail (apps, nodes, infrastructure, sync)')
-    .action(async (projectName, stackName) => {
+    .structuredAction(async (projectName, stackName) => {
     const { stackStatusCommand } = await import('../commands/stack.js');
     await stackStatusCommand(projectName, stackName);
 });
+stack
+    .command('progress <project> [stack]')
+    .description('Inspect the latest remote transfer phases in a project or stack')
+    .structuredAction(async (projectName, stackName) => {
+    const { stackProgressCommand } = await import('../commands/stack.js');
+    await stackProgressCommand(projectName, stackName);
+});
+stack
+    .command('diagnose <project> <stack>')
+    .description('Inspect stack prerequisites without starting, provisioning or migrating')
+    .structuredAction(async (projectName, stackName) => {
+    const { stackDiagnoseCommand } = await import('../commands/stack.js');
+    await stackDiagnoseCommand(projectName, stackName);
+});
+stack
+    .command('prepare-release <project> <stack> <release>')
+    .description('Verify and stage local application archives before a maintenance window')
+    .structuredAction(async (projectName, stackName, release) => {
+    const { stackPrepareReleaseCommand } = await import('../commands/stack.js');
+    await stackPrepareReleaseCommand(projectName, stackName, release);
+});
 stack
     .command('start <project> <stack>')
     .description('Start a stack — provision infra + deploy + start apps')
@@ -186,24 +325,36 @@ stack
     // A release instead of the working tree: built by `omnitron release build`
     // from two commits in clean clones, every gate run. A stack whose config
     // says `release: { mode: 'required' }` takes nothing else.
-    .option('--release <id>', 'Deploy this release (see `omnitron release build`) instead of the working tree')
+    .option('--release <id>', 'Start from a verified release; local stacks retain this choice across restarts')
+    .option('--working-tree', 'Return a stopped local stack to its registered working tree')
     // For an operator who doubts a node's record of what an app runs: every
     // artifact is shipped and every app restarted, whatever the record says.
     .option('--reinstall', "Ship and restart every app, whatever the node's record says it runs")
-    .action(async (projectName, stackName, options) => {
+    .structuredAction(async (projectName, stackName, options) => {
     const { stackStartCommand } = await import('../commands/stack.js');
     await stackStartCommand(projectName, stackName, {
         allowDirty: options.allowDirty === true,
         ...(typeof options.release === 'string' ? { release: options.release } : {}),
+        ...(options.workingTree === true ? { workingTree: true } : {}),
         ...(options.reinstall === true ? { reinstall: true } : {}),
     });
 });
+stack
+    .command('resume <project> <stack>')
+    .description('Resume installed applications after a recipient-confirmed HA stack stop')
+    .structuredAction(async (projectName, stackName) => {
+    const { stackResumeCommand } = await import('../commands/stack.js');
+    await stackResumeCommand(projectName, stackName);
+});
 stack
     .command('stop <project> <stack>')
-    .description('Stop a stack — stop apps + disconnect slaves + teardown infra')
-    .action(async (projectName, stackName) => {
+    .description('Stop a stack and verify each target')
+    .option('--keep-infrastructure', 'Stop applications and disable automatic resume while preserving infrastructure')
+    .option('--dry-run', 'Inspect applications, containers and unresolved targets without creating a stop operation')
+    .option('--review <digest>', 'Stop only if the inventory matches the inspected digest')
+    .structuredAction(async (projectName, stackName, options) => {
     const { stackStopCommand } = await import('../commands/stack.js');
-    await stackStopCommand(projectName, stackName);
+    await stackStopCommand(projectName, stackName, options);
 });
 stack
     .command('account <project> <stack>')
@@ -218,7 +369,7 @@ stack
     .option('--remove <name>', 'Take the account with this name away — with --id, and its password from the vault')
     .option('--id <uuid>', 'The id of the account --remove takes away (as --show prints it)')
     .option('--vault-key <key>', 'Where the password is kept (default: <project>.<stack>.account.<username>.password)')
-    .action(async (projectName, stackName, options) => {
+    .structuredAction(async (projectName, stackName, options) => {
     const { stackAccountCommand } = await import('../commands/stack.js');
     await stackAccountCommand(projectName, stackName, options);
 });
@@ -226,14 +377,14 @@ stack
     .command('maintenance <project> <stack> [action]')
     .description("The stack's maintenance lock at its gateway: `status` (the default), `on` — hold the platform for --minutes and let go by itself — or `off`")
     .option('--minutes <n>', 'With `on`: how long to hold, 1–60 (default 15)')
-    .action(async (projectName, stackName, action, options) => {
+    .structuredAction(async (projectName, stackName, action, options) => {
     const { stackMaintenanceCommand } = await import('../commands/stack.js');
     await stackMaintenanceCommand(projectName, stackName, action, options);
 });
 stack
     .command('runtime <project> <stack>')
     .description('Show stack runtime status as JSON')
-    .action(async (projectName, stackName) => {
+    .structuredAction(async (projectName, stackName) => {
     const { stackRuntimeCommand } = await import('../commands/stack.js');
     await stackRuntimeCommand(projectName, stackName);
 });
@@ -242,7 +393,7 @@ stack
 // ============================================================================
 program
     .command('start [app]')
-    .description('Start app(s), auto-starts daemon if needed')
+    .description('Start a named app via RPC, or start all apps (can start the daemon)')
     .action(async (app) => {
     const { startCommand } = await import('../commands/start.js');
     await startCommand(app);
@@ -276,36 +427,48 @@ program
     .command('list')
     .aliases(['ls'])
     .description('List all managed processes')
-    .action(async () => {
+    .structuredAction(async () => {
     const { listCommand } = await import('../commands/list.js');
     await listCommand();
 });
 program
     .command('status')
     .description('Show daemon status overview')
-    .action(async () => {
+    .structuredAction(async () => {
     const { statusCommand } = await import('../commands/status.js');
     await statusCommand();
 });
 // ============================================================================
 // Monitoring
 // ============================================================================
+program
+    .command('system')
+    .description('Read the connected host or a registered node, including collection time and missing measurements')
+    .option('--node <id>', 'Read this registered node over the mesh')
+    .structuredAction(async (opts) => {
+    const { systemCommand } = await import('../commands/system.js');
+    await systemCommand(opts);
+});
 program
     .command('logs [app]')
     .description('View logs (omit app for daemon log, specify app name for app log)')
     .option('-f, --follow', 'Follow log output')
     .option('-n, --lines <N>', 'Number of lines', '50')
-    .option('-l, --level <level>', 'Minimum log level (trace|debug|info|warn|error|fatal)')
+    .option('-l, --level <level>', 'Minimum severity (trace|debug|info|warn|error|fatal), or an exact level such as unknown')
     .option('-g, --grep <pattern>', 'Filter by message pattern (regex)')
+    .option('--node <node>', 'Read replicated logs from one registered node (name or ID)')
     .option('--file', 'Read from log files instead of daemon (auto when daemon offline)')
-    .action(async (app, opts) => {
+    .option('--status', 'Show local capture, durable queue and database commit status')
+    .structuredAction(async (app, opts) => {
     const { logsCommand } = await import('../commands/logs.js');
     await logsCommand(app, {
+        status: opts.status,
         lines: parseInt(opts.lines, 10),
         follow: opts.follow,
         file: opts.file,
         level: opts.level,
         grep: opts.grep,
+        node: opts.node,
     });
 });
 program
@@ -318,21 +481,21 @@ program
 program
     .command('doctor')
     .description('Diagnose why the platform is unhealthy — findings, evidence, and what to do')
-    .action(async () => {
+    .structuredAction(async () => {
     const { doctorCommand } = await import('../commands/doctor.js');
     await doctorCommand();
 });
 program
     .command('health [app]')
     .description('Health check report')
-    .action(async (app) => {
+    .structuredAction(async (app) => {
     const { healthCommand } = await import('../commands/health.js');
     await healthCommand(app);
 });
 program
     .command('metrics [app]')
     .description('Show CPU/memory/latency metrics')
-    .action(async (app) => {
+    .structuredAction(async (app) => {
     const { metricsCommand } = await import('../commands/metrics.js');
     await metricsCommand(app);
 });
@@ -341,10 +504,11 @@ program
 // ============================================================================
 program
     .command('scale <app> <count>')
-    .description('Scale app instances')
-    .action(async (app, count) => {
+    .description('Resize one declared process pool until restart (automatic policy remains active)')
+    .requiredOption('--process <name>', 'Exact declared pool process name')
+    .structuredAction(async (app, count, options) => {
     const { scaleCommand } = await import('../commands/scale.js');
-    await scaleCommand(app, count);
+    await scaleCommand(app, count, options.process);
 });
 // ============================================================================
 // Diagnostics
@@ -356,7 +520,7 @@ program
     .option('--format <format>', 'Graph format: mermaid (default), dot, or json', 'mermaid')
     .option('--focus <token>', 'Restrict the graph to a token + its closure (use with --graph)')
     .option('--direction <dir>', 'Closure direction when --focus is set: ancestors, descendants, or both (default)', 'both')
-    .action(async (app, opts) => {
+    .structuredAction(async (app, opts) => {
     if (opts.graph) {
         const { inspectGraphCommand } = await import('../commands/inspect-graph.js');
         await inspectGraphCommand(app, {
@@ -380,7 +544,7 @@ program
     .command('env <app>')
     .description('Show resolved environment variables, secrets replaced')
     .option('--reveal', 'Show secrets in clear (admin only; recorded in the audit trail)')
-    .action(async (app, options) => {
+    .structuredAction(async (app, options) => {
     const { envCommand } = await import('../commands/env.js');
     await envCommand(app, options);
 });
@@ -429,6 +593,50 @@ remote
 // Fleet
 // ============================================================================
 const fleet = program.command('fleet').description('Fleet-wide operations across remote servers');
+const rollout = fleet.command('rollout').description('Distribute and activate managed backends across registered servers');
+rollout.command('import <runtimes...>')
+    .description('Admit qualified sealed builds into the local controller catalog for distribution')
+    .structuredAction(async (runtimes) => {
+    const { importFleetBuilds } = await import('../commands/fleet-rollout.js');
+    await importFleetBuilds(runtimes);
+});
+rollout.command('builds')
+    .description('List the builds available for distribution by the controller')
+    .structuredAction(async () => {
+    const { listFleetBuilds } = await import('../commands/fleet-rollout.js');
+    await listFleetBuilds();
+});
+rollout.command('plan <commit> [nodes...]')
+    .description('Review sealed backend updates in the requested node order; omit nodes to select all registered remotes')
+    .option('--apply', 'Start the plan if all selected servers are eligible')
+    .option('--stage', 'Distribute matching builds from the controller catalog before qualification')
+    .option('--wait', 'Wait for qualification, and for activation if requested')
+    .option('--request-id <uuid>', 'Reuse a plan ID when retrying the same request')
+    .structuredAction(async (commit, nodes, options) => {
+    const { fleetRolloutCommand } = await import('../commands/fleet-rollout.js');
+    await fleetRolloutCommand({ kind: 'plan', commit, nodes, apply: options.apply === true, wait: options.wait === true,
+        stage: options.stage === true, ...(options.requestId && { requestId: options.requestId }) });
+});
+rollout.command('apply <id>')
+    .description('Start the reviewed rollout and return its durable operation ID')
+    .option('--wait', 'Follow the operation through completion')
+    .structuredAction(async (id, options) => {
+    const { fleetRolloutCommand } = await import('../commands/fleet-rollout.js');
+    await fleetRolloutCommand({ kind: 'apply', id, wait: options.wait === true });
+});
+rollout.command('reconcile <id>')
+    .description('Observe an uncertain backend rollout without replaying activation or rolling it back')
+    .structuredAction(async (id) => {
+    const { fleetRolloutCommand } = await import('../commands/fleet-rollout.js');
+    await fleetRolloutCommand({ kind: 'reconcile', id });
+});
+rollout.command('status [id]')
+    .description('Show a rollout or the most recent plan')
+    .option('--wait', 'Follow the same operation until it finishes')
+    .structuredAction(async (id, options) => {
+    const { fleetRolloutCommand } = await import('../commands/fleet-rollout.js');
+    await fleetRolloutCommand({ kind: 'status', id, wait: options.wait === true });
+});
 fleet
     .command('status')
     .description('Aggregated fleet status')
@@ -450,9 +658,16 @@ fleet
     const { fleetMetricsCommand } = await import('../commands/fleet.js');
     await fleetMetricsCommand();
 });
+fleet
+    .command('recover <node> <receipt>')
+    .description('Recover an interrupted host upgrade from its recorded receipt')
+    .structuredAction(async (node, receipt) => {
+    const { fleetRecoverCommand } = await import('../commands/fleet-recover.js');
+    await fleetRecoverCommand(node, receipt);
+});
 fleet
     .command('upgrade [nodes...]')
-    .description('Install the omnitron built from this working tree on registered nodes')
+    .description('Install a source bundle from this workspace; use fleet rollout for sealed managed backend updates')
     .option('--dry-run', 'Print the plan and ship nothing')
     .option('--keep <n>', 'Versions to keep on each node (default: 3)', (v) => Number(v))
     .option('--allow-dirty', 'Ship a working tree with uncommitted changes, deliberately')
@@ -465,30 +680,45 @@ fleet
 // ============================================================================
 const release = program
     .command('release')
-    .description('Build a release: a named commit of the project AND omni, in clean clones, gated and packed');
+    .description('Build and inspect project releases with verified framework inputs');
 release
     .command('build <project>')
-    .description('Clone both commits, install, run every gate, pack the artifacts, write the manifest')
+    .description('Build a clean project revision with its locked framework, run gates and package the artifacts')
     .option('--project-commit <sha>', "The project commit to build (default: the project checkout's HEAD)")
-    .option('--omni-commit <sha>', "The omni commit to build (default: the omni checkout's HEAD)")
+    .option('--omni-commit <sha>', "Linked checkout revision, or the exact full commit to require from registry packages")
+    .option('--framework-repository <repository>', 'Override the committed SDK source repository for this build')
+    .option('--framework-ref <ref>', 'Require a full refs/heads/... or refs/tags/... in the selected SDK repository')
     .option('--keep-source', 'Keep the clones after a successful build')
     .option('--skip-gates', 'Record every gate as not-run instead of running them — a look, never a release for a stack')
     .option('--for <stack>', "Also build the static bundle this stack's gateway serves, with its environment")
     .action(async (projectName, options) => {
     const { releaseBuildCommand } = await import('../commands/release.js');
-    await releaseBuildCommand(projectName, { ...options, ...(options.for ? { forStack: options.for } : {}) });
+    const { parseFrameworkSource } = await import('../shared/framework-source.js');
+    const { frameworkRepository, frameworkRef, ...buildOptions } = options;
+    if (frameworkRef && !frameworkRepository)
+        throw new Error('--framework-ref requires --framework-repository; use omnitron.framework in package.json for project defaults');
+    const frameworkSource = frameworkRepository ? parseFrameworkSource({ repository: frameworkRepository, ...(frameworkRef ? { ref: frameworkRef } : {}) }) : undefined;
+    await releaseBuildCommand(projectName, { ...buildOptions, ...(frameworkSource ? { frameworkSource } : {}), ...(options.for ? { forStack: options.for } : {}) });
 });
 release
     .command('list')
     .description('Every release built on this machine, newest first')
-    .action(async () => {
+    .structuredAction(async () => {
     const { releaseListCommand } = await import('../commands/release.js');
     await releaseListCommand();
 });
+release
+    .command('status <project>')
+    .description('Observe stack placement and execution separately from deployment history')
+    .option('--inspect-installed', 'Explicitly compare installed entry points with retained release archives (read-only)')
+    .structuredAction(async (projectName, options) => {
+    const { releaseStatusCommand } = await import('../commands/release.js');
+    await releaseStatusCommand(projectName, options);
+});
 release
     .command('show <id>')
     .description('One release in full: its commits, its gates, its artifacts')
-    .action(async (id) => {
+    .structuredAction(async (id) => {
     const { releaseShowCommand } = await import('../commands/release.js');
     await releaseShowCommand(id);
 });
@@ -507,7 +737,7 @@ release
     .description("Put a release in the artifact store (`releaseStore` in ~/.omnitron/config.json, its key in the daemon's vault)")
     .option('--root <dir>', 'Where the release is read from (default: ~/.omnitron/releases)')
     .option('--repair', "Write every object again even where the store's index matches — for a store a pull found damaged")
-    .action(async (id, options) => {
+    .structuredAction(async (id, options) => {
     const { releasePushCommand } = await import('../commands/release-store.js');
     await releasePushCommand(id, options);
 });
@@ -515,7 +745,7 @@ release
     .command('pull <id>')
     .description('Take a release from the artifact store and check it as a deployment would, before it appears here')
     .option('--root <dir>', 'Where the release is written (default: ~/.omnitron/releases)')
-    .action(async (id, options) => {
+    .structuredAction(async (id, options) => {
     const { releasePullCommand } = await import('../commands/release-store.js');
     await releasePullCommand(id, options);
 });
@@ -535,8 +765,8 @@ release
 const cluster = program.command('cluster').description('Cluster management — leader election, state');
 cluster
     .command('status')
-    .description('Show cluster state: leader, followers, election term')
-    .action(async () => {
+    .description('Show cluster participation, supported controls and controller lease observations')
+    .structuredAction(async () => {
     const { clusterStatusCommand } = await import('../commands/cluster.js');
     await clusterStatusCommand();
 });
@@ -552,11 +782,12 @@ cluster
 // ============================================================================
 const secret = program.command('secret').description('Encrypted secrets management');
 secret
-    .command('set <key> <value>')
-    .description('Set a secret (encrypted at rest)')
-    .action(async (key, value) => {
+    .command('set <key> [value]')
+    .description('Set a secret using hidden terminal input or stdin (encrypted at rest)')
+    .option('--stdin', 'Read the value from stdin instead of a positional argument')
+    .action(async (key, value, opts) => {
     const { secretSetCommand } = await import('../commands/secret.js');
-    await secretSetCommand(key, value);
+    await secretSetCommand(key, value, opts);
 });
 secret
     .command('get <key>')
@@ -617,7 +848,7 @@ program
 program
     .command('health-check [app]')
     .description('Detailed composable health report (HTTP/TCP probes)')
-    .action(async (app) => {
+    .structuredAction(async (app) => {
     const { healthCheckCommand } = await import('../commands/health-check.js');
     await healthCheckCommand(app);
 });
@@ -663,11 +894,28 @@ program
 program
     .command('tor [project] [stack]')
     .description('Show Tor hidden service onion addresses (every tor container on this machine, or one stack\'s)')
-    .action(async (projectName, stackName) => {
+    .structuredAction(async (projectName, stackName) => {
     const { torCommand } = await import('../commands/tor.js');
     await torCommand(projectName, stackName);
 });
 const infra = program.command('infra').description('Manage infrastructure containers (PostgreSQL, Redis, MinIO, etc.)');
+const ingress = infra.command('ingress').description('Manage host-owned public ingress independently of application stacks');
+for (const operation of ['configure', 'check', 'validate', 'apply', 'restore', 'rollback-takeover', 'remove']) {
+    ingress.command(`${operation} <manifest>`)
+        .description(`${operation} host ingress using a JSON manifest (host daemon, exact generation CAS)`)
+        .structuredAction(async (manifest) => {
+        const { hostIngressCommand } = await import('../commands/host-ingress.js');
+        await hostIngressCommand(operation, manifest);
+    });
+}
+for (const operation of ['status', 'recover']) {
+    ingress.command(operation)
+        .description(operation === 'status' ? 'Read configured and observed ingress generation' : 'Recover an interrupted host ingress publication')
+        .structuredAction(async () => {
+        const { hostIngressCommand } = await import('../commands/host-ingress.js');
+        await hostIngressCommand(operation);
+    });
+}
 infra
     .command('up')
     .description('Provision and start all infrastructure services')
@@ -677,8 +925,8 @@ infra
 });
 infra
     .command('down')
-    .description('Stop all infrastructure containers')
-    .option('--volumes', 'Remove data volumes (DESTRUCTIVE)')
+    .description('Remove this standalone ecosystem’s declared containers, preserving their volumes')
+    .option('--volumes', 'Refuse teardown if volume deletion is required (unsupported)')
     .action(async (opts) => {
     const { infraDownCommand } = await import('../commands/infra.js');
     await infraDownCommand(opts);
@@ -700,7 +948,7 @@ infra
     .option('--path <path>', 'Also measure this path: owner, size, free space (repeatable)', collect)
     .option('--snap <name>', 'Also read this snap package (repeatable)', collect)
     .option('--config <file:key,key>', 'Also read these keys of a key=value file; credentials refused (repeatable)', collect)
-    .action(async (target, opts) => {
+    .structuredAction(async (target, opts) => {
     const { infraInspectCommand } = await import('../commands/infra.js');
     await infraInspectCommand(target, opts);
 });
@@ -730,15 +978,17 @@ infra
 });
 infra
     .command('migrate [app]')
-    .description('Run database migrations')
-    .action(async (app) => {
+    .description('Run explicit database migration owners, or legacy workspace package scripts')
+    .option('--stack <name>', 'Select the local infrastructure-owning stack')
+    .option('--dry-run', 'Inspect migration ownership and programs without connecting to the database')
+    .structuredAction(async (app, options) => {
     const { infraMigrateCommand } = await import('../commands/infra.js');
-    await infraMigrateCommand(app);
+    await infraMigrateCommand(app, options);
 });
 infra
     .command('reset')
-    .description('Destroy all infrastructure data and recreate (DESTRUCTIVE)')
-    .option('--yes', 'Skip confirmation prompt')
+    .description('Recreate this standalone ecosystem’s declared containers with their existing volumes')
+    .option('--yes', 'Confirm container recreation')
     .action(async (opts) => {
     const { infraResetCommand } = await import('../commands/infra.js');
     await infraResetCommand(opts);
@@ -750,28 +1000,51 @@ const pipeline = program.command('pipeline').description('CI/CD pipeline managem
 pipeline
     .command('list')
     .description('List all pipelines')
-    .action(async () => {
+    .structuredAction(async () => {
     const { pipelineListCommand } = await import('../commands/pipeline.js');
     await pipelineListCommand();
 });
 pipeline
     .command('run <id>')
     .description('Execute a pipeline')
-    .action(async (id) => {
+    .option('--params-file <file>', 'JSON parameters, supplied as data to the executor')
+    .structuredAction(async (id, options) => {
     const { pipelineRunCommand } = await import('../commands/pipeline.js');
-    await pipelineRunCommand(id);
+    await pipelineRunCommand(id, options);
 });
 pipeline
     .command('status <runId>')
     .description('Check pipeline run status')
-    .action(async (runId) => {
+    .option('--output', 'Include retained stdout and stderr')
+    .structuredAction(async (runId, options) => {
     const { pipelineStatusCommand } = await import('../commands/pipeline.js');
-    await pipelineStatusCommand(runId);
+    await pipelineStatusCommand(runId, options);
+});
+pipeline.command('save <file>').description('Create a pipeline from JSON, or update an existing definition')
+    .option('--id <id>', 'Existing pipeline ID to update')
+    .option('--expected-revision <sha256>', 'Reviewed revision, required with --id')
+    .structuredAction(async (file, options) => {
+    const { pipelineSaveCommand } = await import('../commands/pipeline.js');
+    await pipelineSaveCommand(file, options);
+});
+pipeline.command('cancel <runId>').description('Cancel a run and wait for its executor to stop')
+    .structuredAction(async (runId) => {
+    const { pipelineCancelCommand } = await import('../commands/pipeline.js');
+    await pipelineCancelCommand(runId);
 });
 // ============================================================================
 // Backup/Restore
 // ============================================================================
 const backup = program.command('backup').description('Database backup and restore');
+backup.command('artifact <kind>')
+    .description('Back up storage-objects or tor-keys of an explicit provisioned stack')
+    .requiredOption('--project <name>', 'Project registration')
+    .requiredOption('--stack <name>', 'Stack owning this infrastructure')
+    .option('--bucket <name>', 'Required for storage-objects')
+    .structuredAction(async (kind, options) => {
+    const { backupArtifactCommand } = await import('../commands/backup.js');
+    await backupArtifactCommand(kind, options);
+});
 backup
     .command('create [database]')
     .description('Create a database backup')
@@ -846,6 +1119,16 @@ k8sDeploy
 // Node Management (infrastructure machines)
 // ============================================================================
 const node = program.command('node').description('Manage infrastructure nodes (machines)');
+node.command('reconcile <node>').description('Inspect historical metric receipts; explicitly restore missing retained payloads')
+    .option('--restore', 'Restore missing samples and settle source evidence after the database commits')
+    .option('--pages <count>', 'Maximum pages of 256 entries', '1')
+    .option('--after <sequence>', 'Resume after this source sequence')
+    .option('--through <sequence>', 'Fixed source frontier returned by a previous page')
+    .option('--epoch <id>', 'Require the buffer epoch returned by a previous page')
+    .structuredAction(async (name, options) => {
+    const { nodeReconcileCommand } = await import('../commands/node-reconcile.js');
+    await nodeReconcileCommand(name, options);
+});
 node
     .command('list')
     .alias('ls')
@@ -863,7 +1146,7 @@ node
     .option('--ssh-user <user>', 'SSH user', 'root')
     .option('--ssh-auth <method>', 'Auth method: password|key', 'key')
     .option('--ssh-key <path>', 'Path to SSH private key')
-    .option('--ssh-secret-stdin', 'Read the SSH password (or key passphrase) from stdin')
+    .option('--ssh-secret-stdin', 'Read an SSH secret: hidden prompt on a terminal (Enter), or pipe until EOF')
     .option('--runtime <runtime>', 'Runtime: node|bun', 'node')
     .option('--daemon-port <port>', 'Omnitron daemon port', '9700')
     .option('--tags <tags>', 'Comma-separated tags')
@@ -891,7 +1174,7 @@ node
     .option('--ssh-user <user>', 'SSH user')
     .option('--ssh-auth <method>', 'Auth method: password|key')
     .option('--ssh-key <path>', 'Path to SSH private key')
-    .option('--ssh-secret-stdin', 'Read the SSH password (or key passphrase) from stdin')
+    .option('--ssh-secret-stdin', 'Read an SSH secret: hidden prompt on a terminal (Enter), or pipe until EOF')
     .option('--runtime <runtime>', 'Runtime: node|bun')
     .option('--daemon-port <port>', 'Omnitron daemon port')
     .option('--tags <tags>', 'Comma-separated tags')
@@ -920,6 +1203,30 @@ node
         input['secretFromStdin'] = true;
     await nodeUpdateCommand(id, input);
 });
+const access = program.command('access').description('Console roles, effective RPC permissions and human accounts');
+access.command('show').description('Show effective permissions from the running daemon').structuredAction(async () => {
+    const { accessCommand } = await import('../commands/access.js');
+    await accessCommand('show');
+});
+access.command('users').description('List console accounts without secrets').option('--after <id>', 'Continue after this account ID').structuredAction(async (opts) => {
+    const { accessCommand } = await import('../commands/access.js');
+    await accessCommand('users', opts);
+});
+access.command('create <username>').description('Create a human console account; password stays out of arguments and output')
+    .option('--role <role>', 'viewer, operator or admin', 'viewer').option('--display-name <name>', 'Display name')
+    .requiredOption('--password-stdin', 'Read password from a hidden terminal prompt or stdin until EOF').structuredAction(async (username, opts) => {
+    const { accessCommand } = await import('../commands/access.js');
+    await accessCommand('create', { ...opts, username });
+});
+access.command('role <id> <role>').description('Change an account role and revoke its sessions')
+    .requiredOption('--expect <role>', 'The role you reviewed; refuse if it changed').structuredAction(async (id, role, opts) => {
+    const { accessCommand } = await import('../commands/access.js');
+    await accessCommand('role', { id, role, expect: opts.expect });
+});
+access.command('revoke <id>').description('Revoke all sessions for a console account').structuredAction(async (id) => {
+    const { accessCommand } = await import('../commands/access.js');
+    await accessCommand('revoke', { id });
+});
 program
     .command('audit')
     .description('Who changed this control plane, and what they changed')
@@ -928,7 +1235,8 @@ program
     .option('--resource <type>', 'Only this resource type, e.g. node')
     .option('--actor <who>', 'Only this actor: user, service or system — or an id, e.g. omnitron-local')
     .option('--before <time>', 'Only entries older than this ISO time, e.g. 2026-09-22T21:20:37Z')
-    .action(async (opts) => {
+    .option('--before-id <id>', 'Continue after an audit entry without skipping timestamp ties')
+    .structuredAction(async (opts) => {
     const { auditListCommand } = await import('../commands/audit.js');
     // As typed. `parseInt` here turned `-n abc` into NaN, which reached
     // Postgres as `LIMIT NaN`, and `-n 0` into a request for one row; the
@@ -939,6 +1247,7 @@ program
         resource: opts.resource,
         actor: opts.actor,
         before: opts.before,
+        beforeId: opts.beforeId,
     });
 });
 node
@@ -966,11 +1275,47 @@ node
 // ============================================================================
 // Webapp Management
 // ============================================================================
+node.command('ssh <node>').description('Open an audited interactive SSH terminal (Ctrl+] disconnects)')
+    .action(async (name) => { const { nodeSshCommand } = await import('../commands/terminal.js'); await nodeSshCommand(name); });
+node.command('ssh-key <node>').description('Inspect SSH host fingerprint; trust only after independent verification')
+    .option('--trust <fingerprint>', 'Store an independently verified SHA256 fingerprint')
+    .structuredAction(async (name, options) => { const { nodeHostKeyCommand } = await import('../commands/terminal.js'); await nodeHostKeyCommand(name, options); });
+const fileWorkspace = program.command('files').description('Audited multi-node file workspace');
+for (const [name, signature, description] of [
+    ['archive-formats', '', 'Probe archive formats on source and optional destination'],
+    ['roots', '', 'List explicitly exported roots'], ['list', '[path]', 'List a directory page'],
+    ['stat', '<path>', 'Inspect metadata and current version'], ['read', '<path>', 'Read a bounded UTF-8 document'],
+    ['save', '<path>', 'Save UTF-8 input with an expected version'], ['mkdir', '<path>', 'Create a folder'],
+    ['rename', '<path>', 'Rename without overwriting'], ['trash', '<path>', 'Move a versioned item to recoverable trash'],
+    ['trash-list', '', 'List this identity’s retained trash'], ['restore', '<id>', 'Restore without overwriting'],
+    ['copy', '<path>', 'Start a durable node-to-node copy'], ['transfers', '', 'Inspect this identity’s transfer queue'],
+    ['pause', '<id>', 'Pause a transfer'], ['resume', '<id>', 'Reconcile and resume a transfer'], ['cancel', '<id>', 'Cancel uncommitted transfer work'],
+    ['upload', '<path>', 'Upload a local file in bounded verified chunks'], ['download', '<path>', 'Download without overwriting a local file'],
+    ['upload-status', '<id>', 'Inspect a durable upload receipt'], ['upload-finish', '<id>', 'Reconcile publication after a lost acknowledgement'], ['upload-abort', '<id>', 'Discard an unfinished upload'],
+]) {
+    fileWorkspace.command(`${name} ${signature}`.trim()).description(description)
+        .option('--node <id>', 'Registered node ID or local', 'local').option('--root <id>', 'Exported root ID')
+        .option('--version <version>', 'Expected version; save accepts new for creation')
+        .option('--from <file>', 'Local input file').option('--to <path>', 'Rename destination or local download path')
+        .option('--to-node <id>', 'Copy destination node').option('--to-root <id>', 'Copy destination root').option('--to-path <path>', 'Copy destination folder', '')
+        .option('--archive-format <format>', 'Source-side archive format; inspect archive-formats')
+        .option('--archive-output <mode>', 'Explicit result: archive or directory').option('--archive-name <name>', 'New archive filename or restored directory name')
+        .option('--after <name>', 'Directory page cursor').option('--revision <version>', 'Directory revision from first page')
+        .structuredAction(async (...args) => {
+        const { filesCommand } = await import('../commands/files.js');
+        await filesCommand(name, signature ? args[0] : undefined, signature ? args[1] : args[0]);
+    });
+}
+const terminal = program.command('terminal').description('Manage SSH sessions owned by this local CLI identity');
+terminal.command('list').description('List this caller’s SSH sessions')
+    .structuredAction(async () => { const { terminalSessionsCommand } = await import('../commands/terminal.js'); await terminalSessionsCommand(); });
+terminal.command('close <id>').description('Close this caller’s SSH session')
+    .structuredAction(async (id) => { const { terminalSessionsCommand } = await import('../commands/terminal.js'); await terminalSessionsCommand(id); });
 const webapp = program.command('webapp').description('Manage Omnitron Console webapp');
 webapp
     .command('build')
     .description('Build webapp (vite build)')
-    .action(async () => {
+    .structuredAction(async () => {
     const { webappBuildCommand } = await import('../commands/webapp.js');
     await webappBuildCommand();
 });
@@ -978,28 +1323,28 @@ webapp
     .command('start')
     .description('Start webapp (nginx container serving static + API gateway)')
     .option('-f, --force', 'Force recreate container even if already running')
-    .action(async (opts) => {
+    .structuredAction(async (opts) => {
     const { webappStartCommand } = await import('../commands/webapp.js');
     await webappStartCommand({ force: opts.force });
 });
 webapp
     .command('stop')
     .description('Stop webapp nginx container')
-    .action(async () => {
+    .structuredAction(async () => {
     const { webappStopCommand } = await import('../commands/webapp.js');
     await webappStopCommand();
 });
 webapp
     .command('status')
     .description('Show webapp status')
-    .action(async () => {
+    .structuredAction(async () => {
     const { webappStatusCommand } = await import('../commands/webapp.js');
     await webappStatusCommand();
 });
 webapp
     .command('open')
     .description('Open webapp in browser')
-    .action(async () => {
+    .structuredAction(async () => {
     const { webappOpenCommand } = await import('../commands/webapp.js');
     await webappOpenCommand();
 });
@@ -1031,13 +1376,11 @@ program
     .command('config')
     .description('Show resolved ecosystem configuration')
     .option('--json', 'Output as JSON')
-    .action(async (opts) => {
+    .structuredAction(async () => {
     const { loadEcosystemConfig } = await import('../config/loader.js');
+    const { emitJson } = await import('../commands/output.js');
     const config = await loadEcosystemConfig();
-    if (opts.json) {
-        process.stdout.write(JSON.stringify(config, null, 2) + '\n');
-    }
-    else {
+    if (!emitJson(config)) {
         const { log } = await import('@xec-sh/kit');
         log.info(`Project: ${config.project ?? '(unnamed)'}`);
         log.info(`Apps: ${config.apps.map((a) => a.name).join(', ')}`);
@@ -1107,15 +1450,28 @@ kb.command('query <question>')
  * `process.exitCode` is what the commands set to report failure, so it is
  * what is used — this changes when the process leaves, not what it says.
  *
- * Commands that run indefinitely by design — `monit`, `logs --follow` — hold
- * the loop with their own work and never reach here.
+ * A successful `up --foreground` finishes startup, but its daemon still owns
+ * this process. Leave its handles and Titan shutdown lifecycle intact. An
+ * already-running refusal or a completed forwarded runtime owns no daemon
+ * here, so those calls retain the ordinary CLI completion path.
  */
-program.parseAsync().then(() => process.exit(process.exitCode ?? 0), (err) => {
+program.parseAsync().then(async () => {
+    const { finishJsonModeGuard } = await import('../commands/output.js');
+    finishJsonModeGuard();
+    if (!foregroundDaemonRunning)
+        await exitAfterOutput(process.exitCode ?? 0);
+}, async (err) => {
     // Commander prints its own errors and sets an exit code; anything else
     // reaching here is a bug in a command, and swallowing it would hide it.
     if (err?.exitCode == null) {
-        console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+        const { emitError, isJsonMode } = await import('../commands/output.js');
+        if (isJsonMode())
+            emitError(err instanceof Error ? err.message : String(err), { code: 'COMMAND_FAILED', outcome: 'unknown' });
+        else
+            console.error(err instanceof Error ? err.stack ?? err.message : String(err));
     }
-    process.exit(process.exitCode ?? 1);
+    const { finishJsonModeGuard } = await import('../commands/output.js');
+    finishJsonModeGuard();
+    return exitAfterOutput(process.exitCode ?? 1);
 });
 //# sourceMappingURL=omnitron.js.map