@revoengine/cli 1.0.31 → 1.0.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +152 -24
  3. package/dist/src/argument-contract.d.ts +17 -0
  4. package/dist/src/argument-contract.js +359 -0
  5. package/dist/src/automation-contract.generated.d.ts +56 -22
  6. package/dist/src/automation-contract.generated.js +68 -26
  7. package/dist/src/cli.js +15 -13
  8. package/dist/src/client.d.ts +34 -2
  9. package/dist/src/client.js +76 -13
  10. package/dist/src/commands/agents.js +5 -1
  11. package/dist/src/commands/auth.js +2 -0
  12. package/dist/src/commands/component.js +34 -17
  13. package/dist/src/commands/database-tables.js +15 -4
  14. package/dist/src/commands/database-views.js +5 -1
  15. package/dist/src/commands/endpoints.js +5 -1
  16. package/dist/src/commands/env.js +5 -1
  17. package/dist/src/commands/events.js +5 -1
  18. package/dist/src/commands/groups.js +5 -1
  19. package/dist/src/commands/info.js +2 -0
  20. package/dist/src/commands/job-templates.js +5 -1
  21. package/dist/src/commands/metadata.js +2 -0
  22. package/dist/src/commands/migrate.d.ts +2 -2
  23. package/dist/src/commands/migrate.js +33 -7
  24. package/dist/src/commands/project.js +19 -14
  25. package/dist/src/commands/request.js +2 -0
  26. package/dist/src/commands/role-groups.js +5 -1
  27. package/dist/src/commands/schedules.js +5 -1
  28. package/dist/src/commands/search.js +2 -0
  29. package/dist/src/commands/service-accounts.js +5 -1
  30. package/dist/src/commands/studio.js +2 -0
  31. package/dist/src/commands/terminal-browser-central-profile.d.ts +65 -0
  32. package/dist/src/commands/terminal-browser-central-profile.js +203 -0
  33. package/dist/src/commands/terminal-browser-human-input.d.ts +3 -1
  34. package/dist/src/commands/terminal-browser-human-input.js +3 -1
  35. package/dist/src/commands/terminal-browser-interaction.js +1 -1
  36. package/dist/src/commands/terminal-browser-live-protocol.d.ts +34 -2
  37. package/dist/src/commands/terminal-browser-live-protocol.js +28 -12
  38. package/dist/src/commands/terminal-browser-live-transport.d.ts +1 -0
  39. package/dist/src/commands/terminal-browser-live-transport.js +9 -5
  40. package/dist/src/commands/terminal-browser-live.d.ts +24 -3
  41. package/dist/src/commands/terminal-browser-live.js +199 -30
  42. package/dist/src/commands/terminal-browser-page-input.d.ts +4 -1
  43. package/dist/src/commands/terminal-browser-page-input.js +46 -1
  44. package/dist/src/commands/terminal-browser-profile-crypto.d.ts +30 -0
  45. package/dist/src/commands/terminal-browser-profile-crypto.js +101 -0
  46. package/dist/src/commands/terminal-browser-profile-import-runner.d.ts +31 -0
  47. package/dist/src/commands/terminal-browser-profile-import-runner.js +112 -0
  48. package/dist/src/commands/terminal-browser-profile-import.d.ts +28 -0
  49. package/dist/src/commands/terminal-browser-profile-import.js +125 -0
  50. package/dist/src/commands/terminal-browser-profile-import.protocol.d.ts +50 -0
  51. package/dist/src/commands/terminal-browser-profile-import.protocol.js +52 -0
  52. package/dist/src/commands/terminal-browser-profile-preferences.d.ts +1 -0
  53. package/dist/src/commands/terminal-browser-profile-preferences.js +16 -0
  54. package/dist/src/commands/terminal-browser-profile-sync.d.ts +14 -0
  55. package/dist/src/commands/terminal-browser-profile-sync.js +169 -0
  56. package/dist/src/commands/terminal-browser-profile-sync.protocol.d.ts +50 -0
  57. package/dist/src/commands/terminal-browser-profile-sync.protocol.js +19 -0
  58. package/dist/src/commands/terminal-browser-profile.d.ts +10 -1
  59. package/dist/src/commands/terminal-browser-profile.js +30 -4
  60. package/dist/src/commands/terminal-browser-recording.d.ts +39 -0
  61. package/dist/src/commands/terminal-browser-recording.js +74 -0
  62. package/dist/src/commands/terminal-browser-recording.protocol.d.ts +49 -0
  63. package/dist/src/commands/terminal-browser-recording.protocol.js +16 -0
  64. package/dist/src/commands/terminal-browser.d.ts +14 -1
  65. package/dist/src/commands/terminal-browser.js +98 -33
  66. package/dist/src/commands/terminal-file-descriptor.d.ts +9 -0
  67. package/dist/src/commands/terminal-file-descriptor.js +39 -0
  68. package/dist/src/commands/terminal-file.js +41 -6
  69. package/dist/src/commands/terminal-image.js +3 -31
  70. package/dist/src/commands/terminal-output-buffer.d.ts +18 -1
  71. package/dist/src/commands/terminal-output-buffer.js +95 -8
  72. package/dist/src/commands/terminal-process-group.d.ts +25 -0
  73. package/dist/src/commands/terminal-process-group.js +144 -0
  74. package/dist/src/commands/terminal.d.ts +3 -1
  75. package/dist/src/commands/terminal.js +366 -80
  76. package/dist/src/commands/tests.js +2 -0
  77. package/dist/src/component-lock.d.ts +15 -1
  78. package/dist/src/component-lock.js +96 -10
  79. package/dist/src/env-sync.js +12 -6
  80. package/dist/src/migration.d.ts +7 -0
  81. package/dist/src/migration.js +39 -21
  82. package/dist/src/planning-snapshot.d.ts +3 -0
  83. package/dist/src/planning-snapshot.js +60 -2
  84. package/dist/src/project.d.ts +1 -0
  85. package/dist/src/project.js +7 -8
  86. package/dist/src/resource-syncs/agent-sync.js +76 -24
  87. package/dist/src/resource-syncs/database-table-sync.d.ts +8 -1
  88. package/dist/src/resource-syncs/database-table-sync.js +66 -32
  89. package/dist/src/resource-syncs/database-view-sync.js +41 -28
  90. package/dist/src/resource-syncs/endpoint-sync.js +90 -18
  91. package/dist/src/resource-syncs/event-sync.js +33 -14
  92. package/dist/src/resource-syncs/group-sync.js +21 -11
  93. package/dist/src/resource-syncs/job-template-sync.js +98 -37
  94. package/dist/src/resource-syncs/role-group-sync.js +22 -11
  95. package/dist/src/resource-syncs/schedule-sync.js +26 -11
  96. package/dist/src/resource-syncs/service-account-sync.js +22 -11
  97. package/dist/src/reviewed-plan.js +3 -0
  98. package/dist/src/runtime-view.js +2 -18
  99. package/dist/src/sync-omit-command.d.ts +6 -0
  100. package/dist/src/sync-omit-command.js +49 -0
  101. package/dist/src/sync-omit-write-fence.d.ts +10 -0
  102. package/dist/src/sync-omit-write-fence.js +134 -0
  103. package/dist/src/sync-omit.d.ts +59 -0
  104. package/dist/src/sync-omit.js +469 -0
  105. package/dist/src/sync-output.d.ts +3 -3
  106. package/dist/src/ui.js +11 -5
  107. package/dist/src/update-notifier.d.ts +1 -1
  108. package/dist/src/update-notifier.js +2 -1
  109. package/dist/src/utils.js +46 -17
  110. package/dist/src/workspace-prune.js +11 -3
  111. package/dist/src/workspace-write-lock.d.ts +7 -0
  112. package/dist/src/workspace-write-lock.js +144 -0
  113. package/package.json +6 -5
package/CHANGELOG.md ADDED
@@ -0,0 +1,25 @@
1
+ # Changelog
2
+
3
+ ## 1.0.34 — 2026-10-30
4
+
5
+ ### Destination property preservation
6
+
7
+ - Added CLI-only `--omit` for all twelve tracked resource families across repository and dedicated pull/plan/push, deployment, named migration, and Component environment synchronization.
8
+ - Pull preserves selected properties from the existing local manifest; push/deploy preserves them from the target. Creates initialize omitted definition values from the source. `--force` continues to preserve omitted destination values.
9
+ - Supports nested dot paths, JSON Pointer, repeated flags and family-qualified paths. Arrays are atomic; unsupported, structural, identity and permission paths are rejected. Job input and Event legacy input aliases remain consistent.
10
+ - Keeps full local source integrity separate from managed comparisons and remote baselines. Updates verify preserved values, including absence and `null`; creates verify the complete source definition. Saved plans retain omission policy, source integrity and live target revision checks.
11
+
12
+ ### CLI and terminal fixes
13
+
14
+ - Reject unknown options, missing values, conflicting aliases, ambiguous selectors and invalid booleans before executing the requested operation. Boolean values must be exactly `true` or `false`; bare and negated flags remain supported.
15
+ - Reject unsupported `--dry-run` on push/deploy and direct users to `plan`. Command help works without authentication. Command-specific `-t`/`-i` options no longer override API credentials or instance selection, and `--no-update-notifier` suppresses update checks correctly.
16
+ - Retain control of the terminal process group through cancellation, timeout and policy expiry, including after its leader exits. If cleanup cannot be confirmed, report uncertain execution instead of permitting automatic retry. Preserve buffered output in its original streams.
17
+ - Verify the opened workspace file before upload or image transport. Downloads retain the opened descriptor and check parent and temporary-file identities before committing.
18
+ - Protect workspace writes across CLI processes, reject stale lock snapshots, and replace JSON state atomically. Read-only plans and diffs remain available while another command holds the workspace write lock.
19
+
20
+ ### Upgrade notes
21
+
22
+ - Remote mutations with `--omit` require a matching RevoEngine API whose fresh `/api/v1/me` response advertises `capabilities.atomicResourceUpdates: true`. Older APIs are rejected before writing; upgrading the CLI alone does not enable this server capability.
23
+ - Existing scripts that relied on ignored flags or values such as `--yes=0`, `--force=no` or `--activate=FALSE` must use supported options and boolean values.
24
+ - Legacy lock hashes and changes to omission ownership may require a fresh full pull and review, or the command's existing explicitly reviewed force/source-wins reconciliation. Properties that remain omitted stay destination-owned.
25
+ - Event and Schedule activation keeps its existing repository behavior: deployment preserves target activation and creates definitions inactive unless `--activate` is selected. Existing Studio and Browser server compatibility requirements remain unchanged.
package/README.md CHANGED
@@ -10,11 +10,13 @@ The CLI has three main capabilities:
10
10
  2. **Project migration** — plan, run, and verify a direct migration between two saved projects with `--from` and `--to`.
11
11
  3. **Resource synchronization** — work with one supported resource family through its dedicated `pull`, `plan`, and `push` commands.
12
12
 
13
- ## Version 1.0.30
13
+ ## Version 1.0.34
14
14
 
15
- This release includes the complete CLI Studio session and native test commands, terminal Browser profiles, Live Preview, recording and public-page rendering, together with definition contract fixes. Studio sessions/native tests require a backend with the Studio APIs; Live Preview and recording require matching Realtime/API/Gateway and frontend support. Updating the CLI alone does not enable these server features. Existing runner registration and older terminal/browser operations remain compatible with backends that filter unsupported capabilities.
15
+ This release adds `--omit` to preserve selected destination properties during synchronization, stricter argument validation, terminal process cleanup, opened-file workspace checks, and protection against concurrent or interrupted workspace state writes. See the [1.0.34 changelog](CHANGELOG.md) for changes and upgrade requirements. Writes with `--omit` require the matching API capability `atomicResourceUpdates`; upgrading the CLI alone does not enable it.
16
16
 
17
- Runtime packages include all compiled modules, including native test workspace capture, Browser helpers and subprocess workers. Named authentication profiles require a foreground macOS runner and the host Keychain. Live profile choices are bounded to 32 entries while the complete encrypted catalog remains available for profile management.
17
+ Studio sessions/native tests require a backend with the Studio APIs; Live Preview and recording require matching Realtime/API/Gateway and frontend support. Updating the CLI alone does not enable these server features. Existing runner registration and older terminal/browser operations remain compatible with backends that filter unsupported capabilities.
18
+
19
+ Runtime packages include all compiled modules, including native test workspace capture, Browser helpers and subprocess workers. Central browser-profile support requires matching API/Realtime and frontend changes; it is capability-gated independently from the published CLI version.
18
20
 
19
21
  ## Repository reconciliation
20
22
 
@@ -108,7 +110,7 @@ Terminal connection and execution metadata is also written under the CLI configu
108
110
 
109
111
  The Agent terminal has independent command and network grants. Grants are ceilings; each execution frame carries the requested sandbox and `networkAccess=none|local|full`, so a Full grant does not silently widen a workspace or local-only call. Workspace commands keep writes inside the registered workspace and a private temporary directory; a workspace shell with external networking uses `workspace-network`. An explicit `unrestricted` command requests host file access without adding network access. A localhost development server must request Local network access to bind its port. macOS uses Seatbelt for workspace isolation and host plus local-only network; Linux uses `bwrap` and fails closed for shell Local access because enforceable localhost-only isolation is unavailable there. Missing isolation support fails closed. The runner requires a complete `terminal_policy_v2` execution frame from Realtime, including requested command/network modes, grant revision and optional expiry. New runners advertise `terminal_policy_selective_v1`: an increased grant takes effect on subsequent calls without disconnecting; a reduced grant stops only commands and Browser sessions no longer covered by the current grant or an unexpired temporary scope. Temporary scope expiry stops affected work and closes Browser sessions using that scope. Workspace patches and stdin for a running process are supported. A personal API key is required.
110
112
 
111
- Browser actions use Playwright's Chromium headless shell. The CLI's npm install downloads that browser into Playwright's per-user cache without requiring Python 3; a separate Chrome installation is not required. If npm scripts were disabled or the download was interrupted, reinstall the CLI with scripts enabled before using Browser. Linux hosts still need Playwright's system libraries; an administrator can install them with `npx playwright install-deps chromium`.
113
+ Browser actions use Playwright's full Chromium in its standard headless mode. The CLI's npm install downloads that browser into Playwright's per-user cache without requiring Python 3; a separate Chrome installation is not required. If npm scripts were disabled or the download was interrupted, reinstall the CLI with scripts enabled before using Browser. Linux hosts still need Playwright's system libraries; an administrator can install them with `npx playwright install-deps chromium`.
112
114
 
113
115
  On macOS, workspace commands may use Unix-domain sockets only inside their own private temporary directory. This lets build tools exchange worker messages without enabling IP networking or access to workspace, other-command or host-service sockets. Local development servers still need Local network access and must bind to localhost. Ordinary process deadlines cover the whole lifetime, not startup. The runner advertises `background_shell_v1`: `terminal.start` with `background=true` and `timeout_ms=null` keeps a dev server or watcher on the existing execution ID without the ordinary lifetime timer. Status, output, stdin, PTY and cancel remain available; hiding the terminal view does not stop the process. Scope expiry, revocation, runner stop and the two-minute (120-second) disconnect grace still apply. Reuse a healthy project server or check fresh HTTP readiness after starting it.
114
116
 
@@ -141,32 +143,79 @@ web loading until upgraded and reconnected.
141
143
 
142
144
  The saved `agentTerminalId` identifies the device across terminal restarts. `deviceId` is an alias. Connecting another directory with the same profile and terminal name reuses the saved device secret and registers a pending workspace under that device. Approve its access in AI Agents → Terminals → Workspaces. A running device refreshes its contract; it does not need a second runner. Ambiguous older duplicate registrations require `--terminal-id`. Services remain pinned to the device UUID and original service directory.
143
145
 
146
+ Current runners also negotiate `terminal_output_capture_v1` with durable resume: shell output can be retained separately (up to 1,000,000,000 bytes (decimal 1 GB) and 1,000,000 chunks / 24 hours centrally) from the bounded 100 KB execution preview, and reloaded using the same execution without running its command again. Older servers keep their existing preview behavior.
147
+
148
+ Unacknowledged shell output uses a private process-local disk spool and an ACK-driven 256 KB estimated wire window. Reconnect sends only uncommitted output; completion follows its committed ACKs. Capture quota or spool-write failure is explicitly partial and does not terminate or replay the command. The spool is removed after result acknowledgement, resume rejection, or runner shutdown; it does not recover a process after a CLI crash. The separate local runner log retains its 10 MB limit.
149
+
144
150
  Current runners advertise `terminal_workspaces_v1`, `browser_control_v1`, `file_transfer_v1` and `terminal_resume_durable_v1`. When Realtime confirms durable resume support, output is retained until the server acknowledges its PostgreSQL commit; reconnect resumes the same execution from the last committed output sequence. Redis loss alone does not stop the PTY. Older servers remain compatible without advertising durable recovery. This protocol preserves a running CLI process; it does not restore processes after a CLI or machine crash. Gateway can request socket reconnect without stopping the CLI. Temporary transport/dependency failures retry and resume within two minutes (120 seconds); authentication failures and revocation stop retry. Newly installed services stop on fatal authentication and restart other failed processes. Reinstall existing services to adopt that supervisor behavior. CLI stop does not persist local processes or browser cookies. Changing workspace grant revision conservatively terminates workspace-bound work and contexts.
145
151
 
146
152
  Browser inventory exposes its owning chat and workspace. The model can explicitly close permitted same-actor sessions/tabs to free the four-session/sixteen-tab capacity; active sessions are never silently evicted. Inventory/cleanup preserves the existing network lease. Local/full scope changes recreate the browser context and require browser workflow recovery.
147
153
 
148
- #### Remember browser authentication on macOS
154
+ #### Remember browser authentication in Vault
149
155
 
150
- Browser state is ephemeral by default. A foreground runner can explicitly opt in to a named authentication profile:
156
+ Connect the approved workspace normally:
151
157
 
152
158
  ```bash
153
- revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac" --browser-profile "AP work"
154
- revo terminal browser-profile forget --workspace "$HOME/projects/my-project" --terminal-id <terminal-uuid> --browser-profile "AP work"
159
+ revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
155
160
  ```
156
161
 
157
- The selected profile reuses cookies, local storage and IndexedDB (including Firebase Authentication state) across browser context closure and foreground runner restarts. The CLI flag selects a profile for that invocation. In Live Preview, selecting a profile and choosing it as the default saves the selection in an encrypted, scoped catalog; later chats and foreground restarts restore that default without repeating the flag. Stop an already connected runner before selecting a profile. macOS Keychain holds the encryption key; AES-256-GCM snapshots under the CLI configuration's `browser-profiles/` directory are private and written atomically. Locked or unavailable Keychain access fails closed. Live profile operations use asynchronous Keychain subprocesses so access-expiry timers remain active while the operating system responds. No plaintext key file, environment-key fallback or personal Chrome profile is used. This option currently rejects Linux, Windows and background service runners; passing it to service installation also fails rather than losing the selection.
158
-
159
- A profile belongs to one API URL, instance, actor, terminal and canonical workspace. The same name in another scope is a separate profile. Each chat still gets its own live context. Only one live context can hold a named profile's writer lease at a time; a concurrent chat receives `browser_profile_busy` and must wait for the first context to close or use another profile. This prevents one chat silently replacing another chat's authentication changes. A dead runner's writer lease can be recovered on the next open.
160
-
161
- State is checkpointed after browser actions and on explicit browser close. The CLI never copies secure-input values from the bridge or password-field DOM into a profile. Snapshots capture site-owned cookies, local storage and IndexedDB, which can contain authentication tokens and other sensitive values; all of that state is encrypted. A checkpoint does not certify that login succeeded. Network lease expiry, revocation and runner shutdown close Chromium without waiting for a new checkpoint; the last committed encrypted snapshot remains available for a later authorized invocation. No profile extends network grants, restores running tabs or guarantees the identity provider's session lifetime. Websites can expire tokens, require MFA or require a new interactive login. Local/full scope changes still recreate the runtime context and reinstall network guards before restoring approved state.
162
-
163
- Live Preview uses a separate authenticated outbound Realtime WebSocket. It streams the active tab and SSO popups as JPEG frames at up to five frames per second, with CSS viewport and image geometry; it opens no local server or CDP port. During human takeover, static pages receive a genuine viewport refresh every two seconds so the latest displayed frame remains usable after reading; observation expiry and authorization checks remain enforced. Read-only preview can be closed while the model continues. Takeover pauses all model browser actions for the entire chat browser session. Human input is encrypted to the current runner connection, scoped to the actor, chat, workspace, session, control epoch and fresh observation, and is never replayed after a disconnect. Private takeover is the default. Release clears secret-like inputs, checkpoints the opted-in profile and returns a fresh observation before the model resumes. A disconnect during takeover leaves the browser blocked until explicit reconnection and release. Connected takeover prevents idle cleanup but never extends network permission expiry.
164
-
165
- Coordinates require a recent observation of the active tab. Navigation, tab changes, resize, scrolling and interaction invalidate previous geometry; media frames alone do not invalidate the model's recent screenshot. Model text/key input rejects a focused secret control and must use the secure credential flow. Profile selection creates a new named profile from the current authenticated state; selecting an existing profile restores it. Making the current profile the default preserves current authentication. Reset explicitly clears the selected profile. Profiles remain isolated by actor, API URL, instance, device and workspace; a busy profile returns a safe error before changing the active browser.
166
-
167
- Recording is optional and off by default. It can be enabled in read-only preview to capture model work; private human/authentication phases reject a new recording, and Stop remains available. Explicit public/demo recording uses Playwright's native WebM segments and can continue while the model works after release. Private takeover and secret-focused input stop the active recording before typing; resuming public work starts another segment. Input text and action labels are not added to video or runner logs. Local recordings are stored in private directories with private file permissions; Storage or Both additionally requires current Full network access and a separately authorized upload descriptor. Recordings and browser grants have separate lifetimes. Encrypted profiles are currently available only to foreground macOS runners; unsupported hosts and background service profiles fail closed.
168
-
169
- `forget` requires the profile's workspace and selected terminal, authenticates the actor with the current API profile, and deletes its snapshot and Keychain key. It rejects a profile currently in use; close that chat's browser or stop its runner first. Forgetting local state does not revoke the website's server-side sessions. An ordinary browser close or terminal disconnect retains the opted-in snapshot; revoked grants cannot open a new browser until access is approved again. Use `forget` when the stored login should be removed.
162
+ Create website profiles in Settings → Vault → Browser profiles. Assign each profile
163
+ to approved terminal workspaces and grant its use to selected users/groups. Sharing
164
+ a terminal does not share a login. Live Preview selects assigned profiles; model
165
+ actions discover only authorized metadata and use explicit profile/session refs.
166
+ Each profile opens an independent context with cookies, localStorage and IndexedDB.
167
+ A busy profile cannot be stolen.
168
+
169
+ The v2 runner restores central profiles in memory on macOS, Linux and service
170
+ runners without a Keychain dependency. Revo wraps each profile data key with its
171
+ Vault deployment key and seals only that profile key to the current runner
172
+ connection. State uploads are encrypted, revision-bound and verified before commit.
173
+ A failed save retains the last confirmed cloud revision. Revocation and network
174
+ expiry close affected contexts; uncertain writes are not silently replayed.
175
+ The snapshot captures website-owned authentication state, not entered form values.
176
+ A saved revision does not certify successful login or extend provider session life.
177
+
178
+ The obsolete `terminal connect --browser-profile` flag is rejected. Existing local
179
+ encrypted snapshots remain untouched unless you explicitly migrate them through
180
+ Live Preview → Browser settings → Import an older local profile on an updated
181
+ foreground macOS runner. This creates a new private Vault profile assigned to the
182
+ source workspace. The source is kept by default; optional cleanup runs only after
183
+ the uploaded version is downloaded, decrypted and restored successfully in native
184
+ Chromium. Status checks never replay an import. Linux and service runners restore
185
+ central profiles without the legacy-import capability or a Keychain dependency.
186
+ The legacy `terminal browser-profile forget`
187
+ command remains available for explicitly removing a local snapshot and its Keychain
188
+ key; it does not revoke the website's server-side login.
189
+
190
+ Live Preview uses a separate authenticated outbound Realtime WebSocket. It streams the active tab and SSO popups as JPEG frames at a configurable 5–60 frames per second, with CSS viewport and image geometry; it opens no local server or CDP port. During human takeover, static pages receive a genuine viewport refresh every two seconds so the latest displayed frame remains usable after reading; observation expiry and authorization checks remain enforced. Read-only preview can be closed while the model continues. Takeover pauses all model browser actions for the entire chat browser session. Human input is encrypted to the current runner connection, scoped to the actor, chat, workspace, session, control epoch and fresh observation, and is never replayed after a disconnect. Private takeover is the default. Release clears secret-like inputs, checkpoints the opted-in profile and returns a fresh observation before the model resumes. A disconnect during takeover leaves the browser blocked until explicit reconnection and release. Connected takeover prevents idle cleanup but never extends network permission expiry.
191
+
192
+ Coordinates require a recent observation of the active tab. Navigation, tab changes, resize, scrolling and interaction invalidate previous geometry; media frames alone do not invalidate the model's recent screenshot. Model text/key input rejects a focused secret control and must use the secure credential flow. Central profile selection opens another context and preserves existing tabs. Profile owner controls in Vault clear or remove saved authentication and manage use grants, workspace assignments and active sessions. A grantee cannot expand profile access.
193
+
194
+ Recording is optional and off by default. It can be enabled in read-only preview to capture model work; private human/authentication phases reject a new recording, and Stop remains available. Explicit public/demo recording uses Playwright's native WebM segments and can continue while the model works after release. Private takeover and secret-focused input stop the active recording before typing; resuming public work starts another segment. Input text and action labels are not added to video or runner logs. Local recordings are stored in private directories with private file permissions; Storage or Both additionally requires current Full network access and a separately authorized upload descriptor. Recordings and browser grants have separate lifetimes. Central v2 profiles work without an OS credential store; older runners are capability-gated.
195
+
196
+ Live Preview uses full Chromium in its standard headless mode. The CLI installation
197
+ installs the matching browser; existing installations can run `npx playwright-core
198
+ install chromium` from their CLI package directory after upgrading. Workspace browser
199
+ settings are managed in Revo: preview 5–60 FPS, viewport size, recording destination
200
+ and explicit Always record. A `browser_recording_session_v1` runner applies profile
201
+ defaults (or workspace defaults when inherited) before the first native navigation.
202
+ Native WebM encoding uses the selected viewport and 5–60 FPS setting. Verify the
203
+ finalized file before sharing it: encoded FPS does not guarantee that every frame
204
+ contains a distinct browser update. Updated CLI capture requires its matching Chromium.
205
+ Always record starts without opening Live Preview; Storage/Both uploads completed
206
+ 30-second WebM segments in the background. Live viewing remains on demand, and
207
+ closing an observe preview does not stop either automatic or manually started
208
+ recording. A normal browser-session close flushes the last segment. Private control
209
+ and authentication pause recording; Finish & resume reports the resumed segment.
210
+ Storage destinations are resolved by Revo: personal Assistant recordings use the actor’s Private Storage; autonomous-Agent recordings use the Agent’s linked workspace and its access rules. The terminal owner and CLI connect flags do not select this destination. Local-device recording paths remain unchanged.
211
+
212
+ Saved Revo recordings appear in the preview Sources list even after the browser
213
+ session closes. Connection loss, expired/revoked scope or a failed upload stops
214
+ background recording; failed local segments are retained without blindly replaying
215
+ the PUT. Matching API/Realtime and an upgraded runner are required. Provider challenges may
216
+ still reject automated browsing; no spoofed headers or challenge bypass is enabled.
217
+
218
+ For explicit cleanup of an older local snapshot, `terminal browser-profile forget` requires its workspace and selected terminal, authenticates the actor with the current API profile, and removes only that local snapshot and Keychain key. It rejects a profile currently in use; close its browser or stop its runner first. Manage central profiles and their grants in Revo Vault. Forgetting a legacy local snapshot does not remove a Vault profile or revoke the website's server-side login.
170
219
 
171
220
  `upload_file` and `download_file` stream an explicit authorized workspace file directly to/from GCS HTTPS signed/resumable URLs with permitted headers. Full network permission is required. WebSocket carries metadata only. Resumable uploads report committed offsets and partial completion; do not finalize a Storage upload before completion or blindly repeat an uncertain upload. Downloads commit atomically and do not overwrite unless explicitly requested. The stream's idle timeout is 90 seconds; grant expiry and runner lifetime still apply. Signed URLs/headers are credentials and must not be copied into logs or source files.
172
221
 
@@ -308,11 +357,11 @@ revo pull \
308
357
  --yes
309
358
  ```
310
359
 
311
- `pull` requires either `--all` or `--resources`. It writes resources in dependency order and records the source baseline under the authenticated instance ID. Add `--skip-groups` to omit Group and Role Group resources from the selected scope.
360
+ Select pull resources with `--all`, `--resources`, or positional family names. For example, `revo pull databases --omit=name --yes` pulls Database Tables while preserving names in existing local manifests. Pull writes resources in dependency order and records the source baseline under the authenticated instance ID. Add `--skip-groups` to omit Group and Role Group resources from the selected scope.
312
361
 
313
362
  Repository pull, plan, and deployment use Stable Keys for Component identity, including projects with a legacy UUID lock or no explicit `componentIdentity` setting. Pull reports resources without a Stable Key as unmanaged WIP and skips them while continuing with managed resources; `--force` does not assign missing keys or include WIP resources.
314
363
 
315
- A normal pull protects locally changed files and does not remove source-deleted manifests. After review, `pull --force` replaces managed resource directories and prunes managed manifests that no longer exist on the source. Keep hand-written files outside generated resource directories.
364
+ A normal pull protects locally changed files and does not remove source-deleted manifests. With `--omit`, differences confined to omitted properties do not block the pull; those existing local values remain intact. After review, `pull --force` replaces managed resource directories and prunes managed manifests that no longer exist on the source. Omitted properties in retained manifests remain local even with `--force`. Keep hand-written files outside generated resource directories.
316
365
 
317
366
  ### Review and deploy the repository
318
367
 
@@ -473,7 +522,7 @@ Older Event manifests without `custom` must be refreshed with `revo events pull`
473
522
 
474
523
  Event and Schedule manifests retain runtime `input` (a JSON object) and `inputMode` at the top level. Pull, plan, push, migration and readback verification include both fields. Supported modes are `override` (shallow overlay onto Job template input), `deep_override` (nested object overlay, replacing arrays and retaining null values), and `replace` (whole-input replacement, including clearing it with `{}`). The CLI migrates these definitions; the backend resolves the Job input. Unknown modes, null/scalar/array input and duplicate top-level/extension fields block writes, including with `--force`.
475
524
 
476
- Previously pulled Event manifests with `extensions.input` and `extensions.inputMode` remain accepted; only those extension fields are writable. A fresh pull writes them at the top level. Old Event lock hashes are recognized using the complete live input values, so they cannot hide remote drift. Other extension fields still block deployment.
525
+ Previously pulled Event manifests with `extensions.input` and `extensions.inputMode` remain accepted; only those extension fields are writable. A fresh pull writes them at the top level. With `--omit`, both layouts share runtime ownership and pulls retain the existing destination layout while refreshing managed nested siblings. Omitting all `extensions` also preserves runtime input and mode. Old Event lock hashes are recognized using the complete live input values, so they cannot hide remote drift. Other extension fields still block deployment.
477
526
 
478
527
  Omitted fields mean `input: {}` and `inputMode: "override"` in the CLI's desired definition, including updates. Older Schedule pulls did not export these fields: re-pull from the source before promotion if that source uses nondefault automation input. A plan shows any difference from the target; approving an overwrite applies the manifest defaults. Regenerate saved reviewed plans after updating the CLI because input and mode now participate in definition hashes.
479
528
 
@@ -546,6 +595,10 @@ RAW_SQL validation sends `take: 0` without an `output` overlay, using the backen
546
595
 
547
596
  Table Stable Keys match resources across instances; a table name is the physical SQL name. Dedicated `database-tables plan/push` leaves table renames and column removals for manual handling, even with `--force`. Repository `plan/deploy` and named `migrate` use a broader source-wins policy: they can rename tables and apply supported column changes, while column removal requires `--force`. Table kind, partition parent or bounds, unsupported array changes, and ambiguous identities remain blocked. Every accepted write needs portable readback verification before its lock baseline advances.
548
597
 
598
+ Durable Database Operations require Platform 1.7.0. Older instances returning a completed Table synchronously remain supported for ordinary schema writes. Schema writes use durable Database Operations when the target instance supports them. The CLI submits with `async=true` and a UUID `Idempotency-Key`, then waits for `FINISHED` and reads the resource back before advancing the baseline. Transport retries reuse the exact key, body and optimistic base version. A disconnected client does not cancel accepted DDL. Operations remain visible under Database Operations; a lost status/readback reports the operation ID and leaves the baseline unchanged. Full `deploy` and named migration wait before creating dependent partitions, Views, Components or other consumers.
599
+
600
+ For admission only, use one explicit table: `revo database-tables push 'Sales/Orders#1234abcd' --yes --async --json`. The result includes `status: "accepted"` and `operation: { accepted, jobId, status }`; no success/readback baseline is claimed. `--async` cannot be combined with `--all` or pruning, and full deploy rejects it. Inspect the receipt with `revo request GET /api/v1/databases/operations/<jobId>`; after `FINISHED`, rerun normal push to verify and reconcile the baseline. For a retry across CLI invocations, supply the same `--idempotency-key <uuid>` and unchanged request/base version. Standard index builds and heavy ALTER TABLE can block writes; asynchronous execution does not remove PostgreSQL DDL locks.
601
+
549
602
  Root-table columns can carry unique, non-empty Stable Keys in `definition[].metadata.<stable-key-name>`. `metadata plan/apply` can backfill missing root-column keys; partitions inherit the root definition. Existing column keys are immutable even with `--force`, and malformed or duplicate keys block backfill. A shared key matches columns before exact-name fallback, and writes attach the live target column ID. Source column IDs and reserved `__*` metadata never become portable column identity.
550
603
 
551
604
  Dedicated push allows reviewed key-matched changes to existing columns, including name, type, default, nullability, array, primary-key, unique, and index fields. These operations can scan, lock, rewrite, or validate live data. Exact-name matching remains a fallback for safe presentation changes and an ordinary nullable column addition; it never guesses a rename. A required, defaulted, indexed, unique, or primary-key addition needs a unique column Stable Key. Structural changes to an existing unkeyed column and unkeyed operational additions remain manual. Active Database Views block dependent column renames, removals, type changes, and array changes at plan time and again before the write.
@@ -599,6 +652,40 @@ revo component debug <componentId> --read-only=false
599
652
 
600
653
  Use low-level `request` carefully; it bypasses the higher-level migration planner.
601
654
 
655
+ ## Command arguments and local workspace safety
656
+
657
+ The next CLI release rejects unknown options, missing option values and unsupported
658
+ option combinations before authentication or execution. Boolean options accept a
659
+ bare flag, `--flag=true`, `--flag=false`, or `--no-flag`; explicit values must be
660
+ the lowercase strings `true` or `false`. Values such as `0`, `1`, `no`, `FALSE`
661
+ and empty strings are errors, and conflicting repeated options are rejected.
662
+ For example, use `--no-force` rather than `--force=no`.
663
+
664
+ Named migration commands accept `--dry-run` to follow their read-only plan flow;
665
+ `env apply` supports it too. Use the corresponding `plan` command to preview
666
+ dedicated pushes, and `revo plan` to preview `revo deploy`.
667
+ Passing `--dry-run` to an unsupported command is an error; it never authorizes a
668
+ write. `revo <command> --help` shows help without connecting or executing.
669
+ Conflicting aliases are rejected as well as repeated values. Terminal connection
670
+ commands do not accept a child command or hidden options after `--`; raw request
671
+ JSON and query values remain data.
672
+
673
+ Commands that modify a workspace or its baseline take an exclusive local project
674
+ lock. A second writer fails before making changes; finish the active command and
675
+ retry. Read-only plan and diff commands remain available. Locks from a confirmed
676
+ dead process can be reclaimed; a live or unverifiable owner is never evicted just
677
+ because time has passed. A stale baseline snapshot is rejected rather than
678
+ replacing updates from another process. JSON state is written through a private
679
+ temporary file and atomic replacement, retaining the previous valid file if the
680
+ write fails before replacement.
681
+
682
+ Project init/update excludes the transient `.revoengine/workspace-write.lock/`
683
+ directory from Git. Keep `revo.lock.json` under its existing repository policy;
684
+ the operational writer lock is separate from that baseline file.
685
+
686
+ These local safeguards are separate from the target API's optimistic version
687
+ checks and do not make a multi-resource deployment one remote transaction.
688
+
602
689
  ## HTTP diagnostics
603
690
 
604
691
  Enable a per-invocation HTTP trace in `.revoengine/revo.lock.json`:
@@ -702,6 +789,47 @@ MCP URLs must use public HTTPS without embedded credentials, query or fragment.
702
789
  Agent and Agent Plugin synchronization is upsert-only. Repository prune blocks deletion of either family; retained Agents and inline/registry plugin references also protect Components, Groups and Service Accounts from unsafe pruning. Existing Service Account synchronization remains unchanged, including target-local credentials and membership policy.
703
790
 
704
791
 
792
+ ### Preserve destination properties with `--omit`
793
+
794
+ `--omit` is an invocation-only CLI policy for all twelve resource families. Use it with every repository and dedicated family `pull`, repository `diff`/`plan`/`deploy`, dedicated family `plan`/`push`, named `migrate plan`/`run`/`verify`, and Component `env diff`/`apply`. On pull, the destination is the existing local manifest: selected properties stay local while the other fields refresh from the remote resource. On push or deploy, selected properties stay on the remote target. Resource metadata does not configure omission.
795
+
796
+ ```bash
797
+ revo pull databases --omit=name --yes
798
+ revo pull --all --omit='job-template:inputs,endpoint:options.input' --yes
799
+ revo job-templates pull --all --omit='inputs,options.retry.maxAttempts'
800
+ revo job-templates plan --all --omit='inputs,options.retry.maxAttempts'
801
+ revo job-templates push --all --yes --omit='inputs,options.retry.maxAttempts'
802
+
803
+ revo plan --prune --omit='job-template:inputs,endpoint:options.input' --out reviewed-plan.json
804
+ revo deploy --prune --yes --reviewed-plan reviewed-plan.json \
805
+ --omit='job-template:inputs,endpoint:options.input'
806
+ ```
807
+
808
+ An unqualified path must be supported by every selected family. Qualify family-specific fields in a mixed workspace, as above; a misspelled, unsupported, or out-of-scope path fails before writes. `--omit=name` applies to every selected family. Comma-separated paths and repeated `--omit` flags combine. Use dot paths for ordinary keys or JSON Pointer for literal dots and slashes, for example `--omit='endpoint:/options/input/feature.flag'`. Arrays are atomic: omit their complete property; indexes and wildcards are rejected.
809
+
810
+ | Resource family | Configurable omission examples |
811
+ | --- | --- |
812
+ | `database-table`, `database-view` | `name`, `category`, `description`, `metadata.label` |
813
+ | `component` | `name`, `description` (alias of `desc`), `active`, `testConfig`, `metadata.label` |
814
+ | `job-template` | `name`, `category`, `description`, `timeout`, `inputs`, `options.retry.maxAttempts` |
815
+ | `endpoint` | `name`, `category`, `description`, `active`, `timeout`, `options.input.tenant` |
816
+ | `schedule` | `name`, `category`, `description`, `cron`, `timezone`, `input.tenant`, `inputMode` |
817
+ | `event` | `name`, `category`, `description`, `filter`, `input.tenant`, `inputMode` |
818
+ | `group`, `role-group` | `name`, `category`, `description`, `metadata.label` |
819
+ | `service-account` | `name`, `metadata.label` |
820
+ | `agent` | `name`, `description`, `definition.config.model`, `definition.policy.maxTicks` |
821
+ | `agent-plugin` | `name`, `category`, `description`, `active`, `definition.timeoutMs` |
822
+
823
+ The first pull of a resource seeds its complete remote definition, including properties named by `--omit`. Later pulls preserve those properties from the existing local manifest, including nested values and absent or `null` fields. Normal pulls still protect changes to managed local fields. `--force` replaces conflicting managed fields while preserving omitted local properties. The remote environment baseline records the incoming instance state; a separate full local source proof records the complete definition written to disk.
824
+
825
+ Omitted properties do not contribute to managed differences or content conflicts. Existing targets retain their current values when another managed property changes, including nested siblings and the distinction between absent and `null`. Unchanged Job/Endpoint option envelopes are left out of update requests. If an actual option change would normalize an ignored legacy missing/null field, the CLI rejects it before writing; align the target defaults or omit the complete `options` envelope. Whole Endpoint `options` omission also blocks a conflicting schema-binding change. `--force` still preserves these properties. New resources use complete source values as their initial configuration and verify the full source definition, including omitted properties; omission never supplies missing creation fields. Job `inputs` and `options.input` aliases share ownership, including when omitting all `options`. Plugin name omission covers both its display name and writable definition name. JSON reports expose the normalized omission policy.
826
+
827
+ Identity, resource kind, Stable Key metadata, whole metadata envelopes, versions, code, database structure, routes, dependency bindings, owners, execution principals, roles, members, and built-in credential bindings cannot be omitted. Automation activation continues to use `--activate`. Omission does not authorize pruning or relax identity, dependency, request validation, or current-version checks.
828
+
829
+ The CLI advertises `capabilities.syncOmit` in `revo --version --json`. Before a remote mutation with `--omit`, it requires a fresh target `/api/v1/me` response with `capabilities.atomicResourceUpdates: true`; older APIs are rejected before writing, even when authentication was cached. Install the matching API safeguards before enabling this option in delivery pipelines.
830
+
831
+ Lock baselines record versioned property digests without raw configuration values, allowing comparison under the same or a broader omission policy. A legacy hash alone cannot prove unchanged managed fields; an unavailable baseline is reported as drift rather than silently converted. Equal managed definitions can adopt or refresh a baseline. Removing or narrowing omission invalidates its previous proof, because formerly ignored values were target-owned. Establish a fresh full baseline through pull without `--omit` and review, or explicitly review reconciliation through the command's existing `--force` or source-wins deployment policy. These overrides can replace managed differences and still preserve every property that remains omitted. Keep the same omission policy when applying a saved reviewed plan. Reviewed deployment still fences live versions and target revisions, so a target change after review requires a fresh plan. It also fences complete managed source manifests, including source values that initialize new resources; changing an omitted local value after review requires a new plan.
832
+
705
833
  ### Deployment verification in 1.0.22
706
834
 
707
835
  Portable comparison includes ordinary Component metadata and full structured Database Table / Materialized View index definitions (logical names, methods, expressions, predicates, ordering, null placement, collation, operator classes and included columns). Physical index names, resource IDs and backend-reserved metadata remain instance-local. Older table/view manifests that omitted index settings should be refreshed from the source before promotion.
@@ -0,0 +1,17 @@
1
+ import type { ParsedArgs } from './types.ts';
2
+ /** Keep repetitions for validation without changing the public parsed argument shape. */
3
+ export declare function recordParsedOption(args: ParsedArgs, name: string, value: string | boolean): void;
4
+ export declare function readBooleanOption(args: ParsedArgs, names: readonly string[]): boolean;
5
+ /** Short options owned by a command never become authentication overrides. */
6
+ export declare function runtimeConnectionOverrides(args: ParsedArgs): {
7
+ baseUrl: string | undefined;
8
+ token: string | undefined;
9
+ instance: string | undefined;
10
+ envName: string | undefined;
11
+ };
12
+ /** Pure preflight: no configuration, filesystem, authentication or network effects. */
13
+ export declare function validateCommandArguments(args: ParsedArgs, options?: {
14
+ allowHelp?: boolean;
15
+ }): void;
16
+ /** Terminal owns connection arguments only; a suffix after -- is not a child command. */
17
+ export declare function validateTerminalArguments(argv: string[]): string[];