@ljwei-stak/dsh-model-route-bot 0.66.4 → 0.67.0

package/packages/orchestration/src/web-panel-store.mjs

@@ -0,0 +1,206 @@
+// The Host's own directory of pinned web panels: the few pages an owner keeps
+// one click away (a local dashboard, a CI board). It is a Host component table
+// next to the other SQLite authorities, never a browser-local preference, so a
+// pinned page survives a restart and every client sees the same list.
+//
+// Two rules shape this file:
+//
+// 1. Identity is never taken from the browser. A panel is minted by the Host,
+//    the caller's owner class comes from the authenticated product channel, and
+//    the only origin the store is told about is the one the client reports as
+//    its own embedding origin — used to refuse framing a page that would run
+//    with the client's own access, never to identify anybody.
+// 2. A write is only a write once it has been read back. Every mutation runs in
+//    one immediate transaction guarded by a revision, and the row is re-read
+//    after the commit: a store that reports a change it did not make is worse
+//    than one that refuses.
+
+import { dirname, resolve } from 'node:path'
+import { mkdirSync } from 'node:fs'
+
+export const MAX_WEB_PANELS = 6
+export const MAX_WEB_PANEL_NAME_CHARS = 40
+export const MAX_WEB_PANEL_NAME_BYTES = 120
+export const MAX_WEB_PANEL_URL_BYTES = 2048
+export const WEB_PANEL_LIMITS = Object.freeze({
+  maxPanels: MAX_WEB_PANELS,
+  maxNameChars: MAX_WEB_PANEL_NAME_CHARS,
+  maxNameBytes: MAX_WEB_PANEL_NAME_BYTES,
+  maxUrlBytes: MAX_WEB_PANEL_URL_BYTES,
+})
+
+const fail = code => { throw Object.assign(new Error(code), { code }) }
+const plain = value => value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+// A panel name is a label in a list: control characters would break the row, and
+// they carry no meaning a person can read.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+const ID = /^panel-[1-9][0-9]{0,9}$/
+
+/**
+ * The closed input check. `embeddingOrigin` is the origin the client framed this
+ * page from; a page on that very origin is refused because the frame keeps its
+ * page's own origin and would run with the client's access.
+ */
+export function validateWebPanelInput(input, embeddingOrigin = '') {
+  if (!plain(input) || Object.keys(input).some(key => !['name', 'url'].includes(key))) fail('WEB_PANEL_INPUT')
+  if (typeof input.name !== 'string' || typeof input.url !== 'string') fail('WEB_PANEL_INPUT')
+  const name = input.name.trim()
+  if (!name || name.length > MAX_WEB_PANEL_NAME_CHARS || Buffer.byteLength(name, 'utf8') > MAX_WEB_PANEL_NAME_BYTES || CONTROL.test(name)) fail('WEB_PANEL_NAME')
+  const raw = input.url.trim()
+  if (!raw || Buffer.byteLength(raw, 'utf8') > MAX_WEB_PANEL_URL_BYTES) fail('WEB_PANEL_URL')
+  let url
+  try { url = new URL(raw) } catch { fail('WEB_PANEL_URL') }
+  // Only plain web pages. `javascript:`, `data:`, `file:` and every other scheme
+  // is refused here rather than being handed to a browser to interpret.
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') fail('WEB_PANEL_URL')
+  if (url.username || url.password || !url.hostname) fail('WEB_PANEL_URL')
+  if (embeddingOrigin && sameOrigin(url, embeddingOrigin)) fail('WEB_PANEL_SELF_URL')
+  return Object.freeze({ name, url: url.href })
+}
+
+function sameOrigin(url, origin) {
+  try { return new URL(origin).origin === url.origin } catch { return false }
+}
+
+/** What a client may see. The stored URL is the owner's own input; nothing here adds a path or a secret. */
+export const publicWebPanel = panel => Object.freeze({
+  id: panel.id, name: panel.name, url: panel.url, host: hostOf(panel.url), position: panel.position,
+})
+
+export function hostOf(url) {
+  try { return new URL(url).host } catch { return '' }
+}
+
+/** The same URL without its fragment: a fragment is for the browser, never for a probe. */
+export function probeUrlOf(url) {
+  try { const parsed = new URL(url); parsed.hash = ''; return parsed.href } catch { return '' }
+}
+
+/** A URL safe to write to a log or a share card: origin and path, never the query. */
+export function redactWebPanelUrl(url) {
+  try { const parsed = new URL(url); return `${parsed.origin}${parsed.pathname}` } catch { return '(unreadable url)' }
+}
+
+export function openWebPanelStore({ Database, file, now = Date.now }) {
+  if (typeof Database !== 'function') throw new TypeError('WEB_PANEL_DATABASE_REQUIRED')
+  if (typeof file !== 'string' || !file) throw new TypeError('WEB_PANEL_FILE_REQUIRED')
+  if (file !== ':memory:') { file = resolve(file); mkdirSync(dirname(file), { recursive: true }) }
+  const db = new Database(file)
+  db.pragma('busy_timeout=5000')
+  db.pragma('journal_mode=WAL')
+  db.pragma('synchronous=FULL')
+  db.exec(`CREATE TABLE IF NOT EXISTS web_panel_component(component TEXT PRIMARY KEY,version INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS web_panel_meta(singleton INTEGER PRIMARY KEY CHECK(singleton=1),revision INTEGER NOT NULL,next_seq INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS web_panels(id TEXT PRIMARY KEY,position INTEGER NOT NULL,name TEXT NOT NULL,url TEXT NOT NULL,created_at_ms INTEGER NOT NULL,updated_at_ms INTEGER NOT NULL);
+    CREATE UNIQUE INDEX IF NOT EXISTS web_panels_position ON web_panels(position);`)
+  const version = db.prepare('SELECT version FROM web_panel_component WHERE component=?').get('web-panels')
+  if (version && version.version !== 1) { db.close(); fail('WEB_PANEL_DATABASE_VERSION_UNSUPPORTED') }
+  db.prepare('INSERT OR IGNORE INTO web_panel_component VALUES(?,1)').run('web-panels')
+  db.prepare('INSERT OR IGNORE INTO web_panel_meta VALUES(1,0,1)').run()
+
+  let closed = false
+  const alive = () => { if (closed) fail('WEB_PANEL_STORE_CLOSED') }
+  const rowOf = id => db.prepare('SELECT * FROM web_panels WHERE id=?').get(id)
+  const revisionOf = () => db.prepare('SELECT revision FROM web_panel_meta WHERE singleton=1').get().revision
+  const ordered = () => db.prepare('SELECT * FROM web_panels ORDER BY position').all()
+
+  // One immediate transaction, so two writers cannot both believe they hold the
+  // list. The busy timeout is what keeps a second Host waiting instead of
+  // failing while this one commits.
+  const transact = work => {
+    db.exec('BEGIN IMMEDIATE')
+    try { const value = work(); db.exec('COMMIT'); return value } catch (error) { db.exec('ROLLBACK'); throw error }
+  }
+
+  const claim = expected => {
+    const current = revisionOf()
+    if (!Number.isSafeInteger(expected) || expected !== current) fail('WEB_PANEL_REVISION_CONFLICT')
+    db.prepare('UPDATE web_panel_meta SET revision=? WHERE singleton=1').run(current + 1)
+    return current + 1
+  }
+
+  // The commit is the claim; this is the proof. A row that does not read back as
+  // written fails the call instead of letting the panel believe it was saved.
+  const readback = (revision, panels) => {
+    const after = ordered()
+    const same = after.length === panels.length
+      && after.every((row, index) => row.id === panels[index].id && row.name === panels[index].name
+        && row.url === panels[index].url && row.position === panels[index].position)
+    if (!same || revisionOf() !== revision) fail('WEB_PANEL_READBACK_MISMATCH')
+    return after
+  }
+
+  const read = () => { alive(); return { revision: revisionOf(), panels: ordered().map(publicWebPanel), limits: WEB_PANEL_LIMITS } }
+
+  const save = ({ id = null, name, url, expectedRevision, embeddingOrigin = '' }) => {
+    alive()
+    if (id !== null && (typeof id !== 'string' || !ID.test(id))) fail('WEB_PANEL_INPUT')
+    if (!Number.isSafeInteger(expectedRevision)) fail('WEB_PANEL_INPUT')
+    const next = validateWebPanelInput({ name, url }, embeddingOrigin)
+    const at = now()
+    const committed = transact(() => {
+      const revision = claim(expectedRevision)
+      const existing = id === null ? undefined : rowOf(id)
+      if (id !== null && !existing) fail('WEB_PANEL_NOT_FOUND')
+      const count = db.prepare('SELECT COUNT(*) AS n FROM web_panels').get().n
+      let row
+      if (existing) {
+        db.prepare('UPDATE web_panels SET name=?,url=?,updated_at_ms=? WHERE id=?').run(next.name, next.url, at, id)
+        row = { ...rowOf(id) }
+      } else {
+        if (count >= MAX_WEB_PANELS) fail('WEB_PANEL_LIMIT')
+        const seq = db.prepare('SELECT next_seq FROM web_panel_meta WHERE singleton=1').get().next_seq
+        const fresh = `panel-${seq}`
+        db.prepare('UPDATE web_panel_meta SET next_seq=? WHERE singleton=1').run(seq + 1)
+        db.prepare('INSERT INTO web_panels VALUES(?,?,?,?,?,?)').run(fresh, count + 1, next.name, next.url, at, at)
+        row = { ...rowOf(fresh) }
+      }
+      readback(revision, ordered())
+      return row
+    })
+    return { revision: revisionOf(), panel: publicWebPanel(committed) }
+  }
+
+  const remove = ({ id, expectedRevision }) => {
+    alive()
+    if (typeof id !== 'string' || !ID.test(id) || !Number.isSafeInteger(expectedRevision)) fail('WEB_PANEL_INPUT')
+    const committed = transact(() => {
+      const revision = claim(expectedRevision)
+      const existing = rowOf(id)
+      if (!existing) fail('WEB_PANEL_NOT_FOUND')
+      db.prepare('DELETE FROM web_panels WHERE id=?').run(id)
+      // Positions stay dense: a gap would let a later insert land in the middle.
+      const at = now()
+      const rest = ordered()
+      for (const [index, row] of rest.entries()) db.prepare('UPDATE web_panels SET position=?,updated_at_ms=? WHERE id=?').run(index + 1, at, row.id)
+      readback(revision, ordered())
+      return existing
+    })
+    return { revision: revisionOf(), removed: committed.id }
+  }
+
+  const order = ({ ids, expectedRevision }) => {
+    alive()
+    if (!Array.isArray(ids) || !ids.every(id => typeof id === 'string' && ID.test(id)) || !Number.isSafeInteger(expectedRevision)) fail('WEB_PANEL_INPUT')
+    if (new Set(ids).size !== ids.length || ids.length > MAX_WEB_PANELS) fail('WEB_PANEL_ORDER_INVALID')
+    const committed = transact(() => {
+      const revision = claim(expectedRevision)
+      const current = ordered()
+      // The request must be the whole list in a new order, never a partial edit
+      // that would silently drop whatever it left out.
+      if (current.length !== ids.length || [...ids].sort().join() !== current.map(row => row.id).sort().join()) fail('WEB_PANEL_ORDER_INVALID')
+      const at = now()
+      // Two passes: an arbitrary permutation cannot be written in place without
+      // tripping the unique position index, so the rows step aside first.
+      for (const [index, id] of ids.entries()) db.prepare('UPDATE web_panels SET position=? WHERE id=?').run(-(index + 1), id)
+      for (const [index, id] of ids.entries()) db.prepare('UPDATE web_panels SET position=?,updated_at_ms=? WHERE id=?').run(index + 1, at, id)
+      readback(revision, ordered())
+      return ordered()
+    })
+    return { revision: revisionOf(), panels: committed.map(publicWebPanel) }
+  }
+
+  const close = () => { closed = true; db.close() }
+
+  return Object.freeze({ kind: 'web-panel-store', limits: WEB_PANEL_LIMITS, read, save, remove, order, close })
+}

package/remote-computer-agent/README.md

@@ -1,29 +1,39 @@
-# DSH remote-computer-agent 0.1.1
-
-Harness Desktop's native viewer uses `dsh-app://app`. Version 0.1.1 accepts this exact Origin only for a live desktop session minted by an authenticated Host; it does not enable it for HTTP API requests or other sessions. Model Router 0.63.3 carries the native viewer Origin through Desktop's HTTP bridge. Upgrade both sides when using the native application; ordinary HTTP/HTTPS viewers retain their existing exact-Origin checks.
-
-Credentials are checked again after reading the request body and before each management action. Cached client rows from an older revision cannot issue or revoke newer tickets, and `tools/list` rechecks a live grant. Rotation during a slow request therefore cannot use the old request to revoke a fresh ticket. Temporary cooling also handles wall-clock rollback without extending its backoff beyond the configured cap.
-
-Authentication now has separate bounded anonymous-source/global-failure and verified-client request limits, with temporary cooling and `Retry-After`. Valid clients behind a shared proxy remain usable during anonymous guessing attacks. Rotation invalidates old pairing tokens and tickets immediately. Native TLS and optional client-certificate checks have local HTTPS tests; deployment still requires user-provided certificates and a private proxy backend. See [network settings and recovery](../deploy/remote-agent/README.md) and `node --test tests/remote-auth.native.mjs` (OpenSSL required).
-
-TypeScript machine-side runtime with a single snake_case tool catalog, versioned MCP transport and a durable SQLite operation ledger. Build with `npm ci && npm run build` in this directory; run `node dist/cli.mjs init CONFIG_JSON AUTHORIZED_ROOT`. Installation and network modes: [deployment guide](../deploy/remote-agent/README.md).
-
-For a user-configured Windows cloud computer, unpack the complete Windows package and double-click `start.cmd` (or run `setup.ps1`). The wizard asks for the workspace, private VPN/listen address, reachable Agent URL, trusted Host/team-Bot permission, and optional command/browser permission. The package needs `dist`, production dependencies, bundled Node or an explicit `-NodePath`, and `helpers/dsh-desktop-helper.exe` (plus `dsh-process-job.exe` when commands are enabled). It creates a private configuration, native secret, and `private/pairing.private.json`; import that file in the Host app. Tokens are never printed. The wizard registers two tasks for the current signed-in user with `InteractiveToken`/`LeastPrivilege`, starts the Agent hidden, and uses explicit full-desktop mode for the tray helper. No Windows password is stored, no VM is provisioned, and the user must remain signed in. Existing installations are backed up and preserved; configuring another installation uses another empty directory and distinct task names. A second helper still obeys the machine's exclusive desktop arbiter.
-
-`hostManagedBots:true` is an explicit local-admin pairing ceiling for a trusted authenticated Host to add newly created team Bots without repairing the machine for each ID. Only `Store(...,{admin:true}).pair`/the local `pair` CLI can enable it. An ordinary grant request cannot enable it; root/tool ceilings, Bot-ID validation, client revision and revocation continue to apply. Existing fixed `botIds` ceilings retain their behavior. The nonsecret flag is included in pairing metadata; the token remains in the protected pairing file.
-
-The trusted Host resolves a pairing `secretRef`, requests a five-minute-or-shorter `/control/v1/grants` ticket, then uses the ticket at `/mcp`. These endpoints accept separate credential classes. Local pairing ceilings restrict Bot IDs, roots and tools. Tickets bind machine/client/Bot/task/attempt, revision and expiry. Caller-supplied business arguments cannot add tools or roots. Control-plane secrets and grant tokens are never tool arguments.
-
-`Agent(config, DatabaseConstructor?)` is the direct integration entry. The injectable constructor is `better-sqlite3@13.0.3`, already used by the Host probes. `Store.pair / issue / rotate / revoke` manage local authority; `Agent.call(tool,args,grantContext,operationId)` executes the same tool catalog as HTTP. The machine identity is stored once and survives restart. MCP `params._meta["dsh/operationId"]` is assigned by the Host; never ask a model to invent it.
-
-Writes and process starts require an operation ID. Admission is committed before side effects, duplicate IDs return original results, and a changed request using an old ID fails with `OPERATION_CONFLICT`. Restart turns unfinished records into `OUTCOME_UNKNOWN`; only status reconciliation can resolve them. This prevents duplicate admission and does not claim arbitrary scripts are transactionally exactly-once. Status and artifacts remain scoped to the original client/Bot/task/attempt. Authentication, Host/Origin and bounded throttling precede body handling.
-
-Filesystem calls are root-relative, reject traversal/ADS/symlink escapes, check descriptors/parents and compare `expectedHash` before atomic replacement. `null` means create-only. Reads and writes are bounded; artifacts have a 256 MiB total quota. The application API does not defeat hostile same-account native processes racing filesystem names; use the dedicated OS account/container profile for the OS boundary. Existing files larger than 1 MiB cannot be replaced through `fs_write`.
-
-`shell_exec` receives `workspaceRef:{kind:"remote",machineId,rootId,relativePath}` and either a fixed configured executable ID in `argv[0]`, or an explicitly enabled script interpreter. argv bypasses shell parsing. Default timeout is 60 seconds, maximum 30 minutes. Output capture is limited to 8 MiB and stored as scoped artifacts. Linux cancels the owned process group. Windows requires the bundled Job Object launcher, which creates its child suspended, assigns the job and closes the job on cancellation/launcher death. Missing native isolation fails explicitly. Arbitrary shell grants still carry the account's OS permissions.
-
-Worktrees record a clean source HEAD, create a detached remote worktree and return scoped diff artifacts. Conditional integration refuses changed/dirty sources and leaves `integration-pending` on conflicts. No automatic commit occurs. Browser operations use task-specific Playwright contexts, exact allowed origins including redirects/subresources, disabled downloads/popups/service workers, snapshot references and owner checks. Browser contexts are state isolation, not an OS sandbox; profile persistence/upload/script/download APIs are not yet implemented.
-
-Desktop calls use a local ACL-protected pipe. Default window mode requires an explicit process/interactive target. Opt-in `--desktop-mode full` enables physical monitor capture for Bots and grant-bound long-lived JPEG WebSocket watching with acknowledged mouse/keyboard takeover. Watch does not block Bot automation; acknowledged human control fences it until release. Renewing the signed grant updates the existing session without reconnecting. See [native helper](../native/windows-desktop/README.md) and [session protocol/acceptance limits](../docs/implementation/20261105-desktop-engine.md). `machine_ping` separates agent health from unverified/unavailable desktop state. Remote CLI adapter execution remains a separate Host integration gate; this runtime does not accept arbitrary CLI executable paths from models.
-
-Reproduce native checks from the repository root with `node scripts/integration-remote-agent.mjs [--driver PATH_TO_BETTER_SQLITE3_ENTRY]`. Tests compile the C# helpers on Windows and exercise real subprocesses, cancellation, filesystem/link escapes, CAS/idempotency, unknown recovery, MCP HTTP, grants and Git integration. See the probe's explicit limitations before interpreting results as product acceptance.
+# DSH remote-computer-agent 0.1.2
+
+Version 0.1.2 ships the short-lived QR invitation and six-digit secure pairing flow with Model Router 0.67.0. Use this matching package for the updated Host pairing and desktop transport.
+
+Harness Desktop's native viewer uses `dsh-app://app`. Version 0.1.1 accepts this exact Origin only for a live desktop session minted by an authenticated Host; it does not enable it for HTTP API requests or other sessions. Model Router 0.63.3 carries the native viewer Origin through Desktop's HTTP bridge. Upgrade both sides when using the native application; ordinary HTTP/HTTPS viewers retain their existing exact-Origin checks.
+
+Credentials are checked again after reading the request body and before each management action. Cached client rows from an older revision cannot issue or revoke newer tickets, and `tools/list` rechecks a live grant. Rotation during a slow request therefore cannot use the old request to revoke a fresh ticket. Temporary cooling also handles wall-clock rollback without extending its backoff beyond the configured cap.
+
+Authentication now has separate bounded anonymous-source/global-failure and verified-client request limits, with temporary cooling and `Retry-After`. Valid clients behind a shared proxy remain usable during anonymous guessing attacks. Rotation invalidates old pairing tokens and tickets immediately. Native TLS and optional client-certificate checks have local HTTPS tests; deployment still requires user-provided certificates and a private proxy backend. See [network settings and recovery](../deploy/remote-agent/README.md) and `node --test tests/remote-auth.native.mjs` (OpenSSL required).
+
+TypeScript machine-side runtime with a single snake_case tool catalog, versioned MCP transport and a durable SQLite operation ledger. Build with `npm ci && npm run build` in this directory; run `node dist/cli.mjs init CONFIG_JSON AUTHORIZED_ROOT`. Installation and network modes: [deployment guide](../deploy/remote-agent/README.md).
+
+For a user-configured Windows computer, unpack the complete Windows package and double-click `start.cmd` (or run `setup.ps1`). The setup wizard defaults to short secure invitations: it selects the shared workspace, one reachable local address, trusted Host/team-Bot permission, and optional command/browser permission, then creates `private/pairing.html` with a QR code, six-digit confirmation and device fingerprint. Scan/copy the invitation into the Host's secure pairing panel within two minutes. `pair-device.cmd` refreshes an unredeemed invitation without changing tasks or permissions. Compatibility mode (`pairingMode:legacy` in an answers file) still creates `private/pairing.private.json`. No device credential is created until a secure invitation is redeemed; invitation proofs and native secrets are not printed.
+
+The package needs `dist`, production dependencies, bundled Node or an explicit `-NodePath`, and `helpers/dsh-desktop-helper.exe` (plus `dsh-process-job.exe` when commands are enabled). The wizard registers two tasks for the current signed-in user with `InteractiveToken`/`LeastPrivilege`, starts the Agent hidden, and uses explicit full-desktop mode for the tray helper. No Windows password is stored, no VM is provisioned, and the user must remain signed in. Existing installations are backed up and preserved; configuring another installation uses another empty directory and distinct task names. A second helper still obeys the machine's exclusive desktop arbiter. The QR page is generated offline using [node-qrcode](https://github.com/soldair/node-qrcode); its camera/image counterpart is in the Host client and never uploads images for decoding.
+
+`hostManagedBots:true` is an explicit local-admin pairing ceiling for a trusted authenticated Host to add newly created team Bots without repairing the machine for each ID. Only `Store(...,{admin:true}).pair`/the local `pair` CLI can enable it. An ordinary grant request cannot enable it; root/tool ceilings, Bot-ID validation, client revision and revocation continue to apply. Existing fixed `botIds` ceilings retain their behavior. The nonsecret flag is included in pairing metadata; the token remains in the protected pairing file.
+
+The trusted Host resolves a pairing `secretRef`, requests a five-minute-or-shorter `/control/v1/grants` ticket, then uses the ticket at `/mcp`. These endpoints accept separate credential classes. Local pairing ceilings restrict Bot IDs, roots and tools. Tickets bind machine/client/Bot/task/attempt, revision and expiry. Caller-supplied business arguments cannot add tools or roots. Control-plane secrets and grant tokens are never tool arguments.
+
+`Agent(config, DatabaseConstructor?)` is the direct integration entry. The injectable constructor is `better-sqlite3@13.0.3`, already used by the Host probes. `Store.pair / issue / rotate / revoke` manage local authority; `Agent.call(tool,args,grantContext,operationId)` executes the same tool catalog as HTTP. The machine identity is stored once and survives restart. MCP `params._meta["dsh/operationId"]` is assigned by the Host; never ask a model to invent it.
+
+Writes and process starts require an operation ID. Admission is committed before side effects, duplicate IDs return original results, and a changed request using an old ID fails with `OPERATION_CONFLICT`. Restart turns unfinished records into `OUTCOME_UNKNOWN`; only status reconciliation can resolve them. This prevents duplicate admission and does not claim arbitrary scripts are transactionally exactly-once. Status and artifacts remain scoped to the original client/Bot/task/attempt. Authentication, Host/Origin and bounded throttling precede body handling.
+
+Filesystem calls are root-relative, reject traversal/ADS/symlink escapes, check descriptors/parents and compare `expectedHash` before atomic replacement. `null` means create-only. Reads and writes are bounded; artifacts have a 256 MiB total quota. The application API does not defeat hostile same-account native processes racing filesystem names; use the dedicated OS account/container profile for the OS boundary. Existing files larger than 1 MiB cannot be replaced through `fs_write`.
+
+`shell_exec` receives `workspaceRef:{kind:"remote",machineId,rootId,relativePath}` and either a fixed configured executable ID in `argv[0]`, or an explicitly enabled script interpreter. argv bypasses shell parsing. Default timeout is 60 seconds, maximum 30 minutes. Output capture is limited to 8 MiB and stored as scoped artifacts. Linux cancels the owned process group. Windows requires the bundled Job Object launcher, which creates its child suspended, assigns the job and closes the job on cancellation/launcher death. Missing native isolation fails explicitly. Arbitrary shell grants still carry the account's OS permissions.
+
+Worktrees record a clean source HEAD, create a detached remote worktree and return scoped diff artifacts. Conditional integration refuses changed/dirty sources and leaves `integration-pending` on conflicts. No automatic commit occurs. Browser operations use task-specific Playwright contexts, exact allowed origins including redirects/subresources, disabled downloads/popups/service workers, snapshot references and owner checks. Browser contexts are state isolation, not an OS sandbox; profile persistence/upload/script/download APIs are not yet implemented.
+
+Desktop calls use a local ACL-protected pipe. Default window mode requires an explicit process/interactive target. Opt-in `--desktop-mode full` enables physical monitor capture for Bots and grant-bound long-lived JPEG WebSocket watching with acknowledged mouse/keyboard takeover. Watch does not block Bot automation; acknowledged human control fences it until release. Renewing the signed grant updates the existing session without reconnecting. See [native helper](../native/windows-desktop/README.md) and [session protocol/acceptance limits](../docs/implementation/20261105-desktop-engine.md). `machine_ping` separates agent health from unverified/unavailable desktop state. Remote CLI adapter execution remains a separate Host integration gate; this runtime does not accept arbitrary CLI executable paths from models.
+
+Reproduce native checks from the repository root with `node scripts/integration-remote-agent.mjs [--driver PATH_TO_BETTER_SQLITE3_ENTRY]`. Tests compile the C# helpers on Windows and exercise real subprocesses, cancellation, filesystem/link escapes, CAS/idempotency, unknown recovery, MCP HTTP, grants and Git integration. See the probe's explicit limitations before interpreting results as product acceptance.
+
+### Recover an interrupted secure pairing
+
+The importable invitation JSON omits the six-digit confirmation code. Read the code from the private pairing page on the target computer and type it in the Host. Keep that page on the target computer.
+
+If the Agent already committed a client but the Host lost its credential, inspect the local device list first. Run `pair-device.cmd -ResetPairing` on that target computer to explicitly revoke the previous client and create a fresh invitation under the same client ID. This disconnects its old connections and grants. Refreshing an invitation without this switch never revokes an active pairing. Existing configuration, sharing scope and scheduled tasks are preserved.

package/remote-computer-agent/build.mjs

@@ -25,6 +25,9 @@ const files = [...main.outputFiles, ...bridge.outputFiles]
 for (const helper of ['native-peer.ps1', 'native-peer.py']) {
   files.push({ path: join(output, helper), contents: await readFile(resolve(root, '../packages/cli-runtime/src', helper)) })
 }
+for (const [source, name] of [['vendor/LICENSE','OPENMAUSBOT_LICENSE'],['NOTICE','OPENMAUSBOT_NOTICE'],['SOURCE.json','OPENMAUSBOT_SOURCE.json']]) {
+  files.push({ path: join(output, name), contents: await readFile(resolve(root, '../modules/openmaus-protocol', source)) })
+}
 for (const file of files) assert.equal(dirname(resolve(file.path)), output, 'Agent build files must remain directly inside dist')
 await checkOutput()
 await mkdir(output, { recursive: true })

package/remote-computer-agent/dist/OPENMAUSBOT_LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/remote-computer-agent/dist/OPENMAUSBOT_NOTICE

@@ -0,0 +1,10 @@
+OpenMausBot protocol components
+Upstream: https://github.com/milind-soni/OpenMausBot
+Pinned commit: 1bc4749aa8307d7d6998bf86de4ef6478460dd93
+Author: Milind Soni and OpenMausBot contributors
+License: Apache License 2.0; see vendor/LICENSE.
+
+The companion end-to-end encryption protocol, descriptor, credentials, yamux
+codec and interoperability vectors are copied without modification. Product
+adapters and their permission policy are separate from the frozen upstream
+files. SOURCE.json records each source path and byte hash.

package/remote-computer-agent/dist/OPENMAUSBOT_SOURCE.json

@@ -0,0 +1,68 @@
+{
+  "schemaVersion": 1,
+  "upstream": "https://github.com/milind-soni/OpenMausBot",
+  "commit": "1bc4749aa8307d7d6998bf86de4ef6478460dd93",
+  "license": "Apache-2.0",
+  "files": [
+    {
+      "source": "companion/src/e2e/credentials.ts",
+      "target": "vendor/companion/src/e2e/credentials.ts",
+      "sha256": "1b576030c9e795eb64f5bee9fdc5918d6cfb92f2481b70259f7636991d6f5f6f",
+      "bytes": 6328
+    },
+    {
+      "source": "companion/src/e2e/noise.ts",
+      "target": "vendor/companion/src/e2e/noise.ts",
+      "sha256": "9269403237b43246142d5dd69bee0269d3b41f81c6bfe95520693320b6469250",
+      "bytes": 15871
+    },
+    {
+      "source": "companion/src/e2e/descriptor.ts",
+      "target": "vendor/companion/src/e2e/descriptor.ts",
+      "sha256": "5a7b39e4571e8b83fd85a3b6141cc09501918326afcc58c6ccb4a61344bbb2c8",
+      "bytes": 4570
+    },
+    {
+      "source": "companion/src/e2e/yamux.ts",
+      "target": "vendor/companion/src/e2e/yamux.ts",
+      "sha256": "1292b278d229d3ed8b92a32aec4137e04329d6fb2497d90ffee6f6d4bef20683",
+      "bytes": 13359
+    },
+    {
+      "source": "companion/src/e2e/session.ts",
+      "target": "vendor/companion/src/e2e/session.ts",
+      "sha256": "1ff7d26fe674ccab9f75026fec15f85bd791f99d75b888eaf24b7be744c4da0e",
+      "bytes": 14336
+    },
+    {
+      "source": "companion/src/e2e/phone.ts",
+      "target": "vendor/companion/src/e2e/phone.ts",
+      "sha256": "9fd5a069eecdea29afe5fb00ea2bfc5d42d8aae448927cd9ce3770a8cd2de5d0",
+      "bytes": 4083
+    },
+    {
+      "source": "companion/src/e2e/vectors/v1.json",
+      "target": "vendor/companion/src/e2e/vectors/v1.json",
+      "sha256": "5471a0070ddbb69dca34dee6da550de4581e8e1a40e22e0f97873d539793bf4e",
+      "bytes": 204553
+    },
+    {
+      "source": "companion/src/e2e/vectors/v1.sha256",
+      "target": "vendor/companion/src/e2e/vectors/v1.sha256",
+      "sha256": "99de21e9eef973a92e651517d88e977a1ef91fb441183648115b8a06b24796ee",
+      "bytes": 74
+    },
+    {
+      "source": "companion/src/e2e/README.md",
+      "target": "vendor/companion/src/e2e/README.md",
+      "sha256": "b752ee693e97c9674a207561be536105a34f90e99eaaead49b1f644f2b69589d",
+      "bytes": 29207
+    },
+    {
+      "source": "LICENSE",
+      "target": "vendor/LICENSE",
+      "sha256": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
+      "bytes": 11358
+    }
+  ]
+}