@amaster.ai/mirrorx-device-client 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,488 @@
-# Temporary Holding Version
+# MirrorX device client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package is a small Node.js bridge for a user-owned Pi, Codex, or WorkBuddy executor.
+It makes outbound requests to MirrorX; the device needs no inbound connection.
+The package has no runtime dependencies on Pi Agent. With
+`MIRRORX_DEVICE_SERVER_URL` set by the Pi distribution, Pi uses its existing
+IAM login to register in every MirrorX company where the linked IAM subject is
+already a member. No second browser approval is needed. The MirrorX server
+uses its existing `IAM_INTERNAL_BASE_URL` to verify the login token through
+IAM userinfo, and `IAM_PUBLIC_BASE_URL` (or `IAM_BASE_URL`) as the issuer used
+by existing IAM account links. No separate device userinfo URL is needed.
+Email is not an identity fallback.
+The Amaster desktop app is the ordinary entry point and carries this library in its own runtime; users do not install Node/npm. In MirrorX Settings → Runtime and integrations, select a connected computer, name the employee and choose Amaster, Codex or WorkBuddy. Automatic managed workspaces are the default and require no second native confirmation. Custom Codex/WorkBuddy project directories retain native confirmation of the exact path; the `amaster://device/connect?intent=UUID` link contains no credential. Login creates/restores only the personal twin. Additional employees consume explicit authorized enrollment intents.
+
+The standalone CLI connects a **computer only**. In the web connection dialog,
+generate a one-use computer pairing code, then run `setup --server URL`. No tool,
+workspace, personal twin or other employee is created during pairing. Codes last
+ten minutes and can be generated before a computer is online. Already connected
+computers can be selected directly without another code.
+
+## Online-only operation and recovery
+
+V1 submits work only while online and ready. Known offline/not-ready submissions retain browser drafts and send no new task/run request. Reconnection refreshes state; the user must submit again. Existing accepted tasks/timers can still fail while the computer sleeps. There is no offline queue or automatic scheduling in this connector.
+
+`setup` installs a current-user LaunchAgent, Windows task or systemd user service. It asks before a foreground-only fallback on unsupported systems. `service stop` requests drain through a matching private instance record; uncertain commands remain for reconciliation. Repeated start does not create another owned supervisor, and unknown service ownership is rejected. OS service installations still require real per-platform validation. App background and login-start options are separate from standalone service ownership.
+
+Normal restore requires the original owner, safe disconnect and no unsettled commands/leases. Permanent loss is a distinct MirrorX recovery permission with an exact command-set confirmation, immutable receipt and generation fence. It abandons results, never claims the old process stopped, preserves usage and pauses affected task trees until manual action. Restoring retains the original employee/history and starts new native sessions. Lost index repair requires a valid narrow session; completely lost references require an explicit existing-Pi/new-computer choice.
+
+Protocol and distribution metadata are available at `/api/devices/compatibility`. Desktop and enabled npm channels have independent exact versions and integrity/provenance checks. Missing published npm does not block the app. Unsupported protocol stops fresh claims/enrollment, retaining identities and allowing authenticated original in-flight claims to settle. Never delete identity files to fix an upgrade requirement.
+
+## Standalone installation and updates
+
+After the first public release, install this connector without the Pi Agent app:
+
+```sh
+npm install -g @amaster.ai/mirrorx-device-client@VERSION
+mirrorx-device --version
+mirrorx-device --help
+```
+
+Replace `VERSION` with a published version number.
+Generate a computer pairing code in MirrorX and run the commands below. Install
+and sign in to the chosen tool later, before assigning work to an employee. Node.js22.19+ is required. Update
+by selecting the new version in the same npm command after your own connector's
+tasks finish and the bridge exits; restart it afterward. Publishing a new version never updates or stops
+existing bridge processes automatically. Keep the old version available while
+reconciling any interrupted work.
+
+The release-branch/manual npm release workflow, maintainer credential setup, exact-tarball
+native smoke and rollback instructions are in
+[the release runbook](../../docs/releasing-mirrorx-device-client.md). Before the
+first successful publication, maintainers can use the verified tgz attached to
+a dry-run workflow; a new workflow file in a Draft PR is not a published npm version.
+
+```sh
+mirrorx-device setup --server https://YOUR-MIRRORX
+mirrorx-device service status
+mirrorx-device doctor --kind codex
+```
+
+`setup` prompts for the code without putting it in shell history. A narrow
+computer credential is stored in the owner-only identity directory. The connector
+reports presence every 15 seconds with a 60-second fenced lease, even with zero
+employees or while a tool is unready. The supervisor discovers new computer
+connections without requiring an existing service to be replaced.
+
+Create employees explicitly in MirrorX after pairing. This package supports
+managed Codex/WorkBuddy workspaces on macOS (Seatbelt confinement); it does not
+bundle the Amaster Pi runtime. Other platforms can connect and report presence,
+but must not claim managed-workspace support. The desktop app supplies Amaster's
+runtime. Tool execution retains its existing journals, approval gates and local
+readiness checks. A computer credential cannot execute tasks directly.
+
+Legacy `pair --kind ... --workspace ...` remains an employee-bound maintainer
+command; its codes are deliberately incompatible with computer-only pairing.
+`setup` rejects those legacy flags rather than silently creating an employee.
+Pi sign-out stops only app-owned bridges and clears their narrow credentials, retaining non-secret binding references. Natural expiry/normal rotation may renew the same Pi binding through the current IAM identity. Explicit revocation, membership loss and protocol rejection never authorize automatic re-enrollment.
+
+The bridge journals each claim and durably records a launch intent before
+spawning the process. A verified pre-spawn claim can retry a failed start;
+an already launched or older ambiguous journal entry requires reconciliation.
+A private random UUID lives in an OS-user identity directory independent of the overridable task state/install directory. No hardware identifiers are read. An atomic local lock covers canonical server origin, authenticated principal, profile, company and executor; it never signals unknown owners. MirrorX also leases the active bridge
+instance in PostgreSQL and stores the instance that started each command, so
+a copied configuration on another computer cannot start the same command.
+The bridge includes up to 32 locally in-flight command IDs in each poll,
+including commands awaiting output transfer or completion acknowledgement. MirrorX
+can then deliver queued control commands while a long process runs; a command
+omitted from this list or owned by an older bridge still blocks new claims until
+it is reconciled. Older MirrorX servers ignore the optional poll parameter.
+Acknowledged terminal entries are removed from the local journal. The client
+spools output segments under `~/.mirrorx-device/output-outbox/` and uploads
+their bytes directly to S3 using short-lived URLs while the Run is active.
+PostgreSQL keeps the segment cursor and transfer metadata; the plugin verifies
+each segment before forwarding it to the Run log. A slow upload temporarily pauses
+stdout/stderr reads; if transfer remains unavailable, the process continues
+and output stays in the local outbox for reconnect. There is no task-wide
+output byte limit or output-volume kill switch. If the
+process finished before an acknowledgement was lost, the bridge replays its
+outbox on reconnect. A process crash with uncertain side effects still needs
+reconciliation. If local output staging fails, the bridge stops the process and
+reports a failed command with an explicit output-loss message; it cannot safely
+replay missing bytes. On macOS and Linux, individual stop requests signal the
+managed process group, then escalate to SIGKILL after three seconds if any
+member remains and the root is still owned. If the root exits before escalation,
+the bridge observes for a bounded grace, then requires reconciliation; it cannot
+safely signal an unowned/reused PID. On Windows, the bridge uses `taskkill /T /F` for the process
+tree. A stop is not reported complete until that operation has finished; a
+failed tree stop leaves the command for reconciliation. If the Run
+controller is interrupted, the device keeps running
+and MirrorX acknowledges later ordinary log segments without uploading them.
+The final command result carries a summary budgeted in UTF-8 bytes across both
+output streams so the whole terminal request stays below the host's one-megabyte
+limit. The device plugin removes
+forwarded temporary objects and expires orphaned output after a short grace
+period; it does not keep a second full stdout archive. The host's live log
+notification is best effort and has no durable acknowledgement. Real multi-Pod/OSS
+validation remains before production use.
+
+Pi Billing commands use the device's configured model catalog together with
+the per-run routing supplied by MirrorX. The Pi server passes its effective
+configuration directory and default model to the bridge. Standalone Pi bridges
+use `PI_CODING_AGENT_DIR`, falling back to `~/.pi/agent`; that directory must
+contain a configured `amaster` model catalog. A routing-only provider is not a
+catalog. The bridge builds a private, disposable command configuration, retains
+explicit model selection, and only fills an omitted model from the device's
+configured default. Local provider credentials and model-level routing are
+excluded from the merge so the organization Billing lease remains authoritative.
+The user's configuration and the server-staged files are left unchanged.
+
+For Billing commands, an omitted model can reuse the configured default model ID
+from another provider only when that ID exists in the `amaster` Billing catalog.
+An unmatched default is an explicit configuration failure, not an arbitrary model
+selection. Missing values for `--model`, `-m`, or `--provider` are rejected before
+injection. Only `models.json` and staged `settings.json` are materialized; caches,
+sessions, local OAuth/authHeader settings and provider-level compat are not copied.
+The injected Billing authentication remains authoritative. Preparation retries
+filesystem resource errors at most three times before launching a process;
+deterministic invalid configuration is not retried.
+
+On POSIX, a Billing command remains active while observing managed descendants
+for up to 30 seconds starting at the root's `exit` event. Root exit and stdio
+`close` are tracked separately: descendants inheriting stdout/stderr cannot keep
+the observation deadline or abort cleanup from running. Normal completion still
+waits for output EOF within that deadline. Unconfirmed completion closes only
+local pipe handles, retains the running journal without ACK, and applies the
+platform cleanup policy below. Once the root has exited, this is strictly
+observation: no new stop signal is sent to that PID/group, including on abort or
+deadline. An already-started stop may escalate only while the root is still live;
+otherwise it also switches to observation/reconciliation. This trades automatic
+termination of surviving tools for protection against signalling a reused PID.
+Stop/reap observation is bounded (three-second TERM and KILL grace, followed by
+at most five seconds of reap grace; abort skips the extra reap wait).
+
+If exit cannot be confirmed, no completion ACK is sent; the running journal
+requires manual reconciliation and a replacement bridge refuses to relaunch it.
+Execution timers/active ownership are cleared and shutdown releases its bridge lock.
+Unconfirmed execution retains its private Billing directory on both POSIX and
+Windows; the running journal records `configurationDirectory` and an ownership
+token, never the credential contents.
+A surviving tool may still read those files. Retention does not extend the
+server's Billing lease or establish successful completion. Normal completion
+persists cleanup evidence and removes private configuration before replacing the
+running record or sending the completion ACK. Startup and subsequent polls scan
+all journal configuration references, even if the server no longer returns the command.
+POSIX reconciliation keeps passive, unreferenced pipe readers: actual stdout and
+stderr EOF after root exit is persisted in a private ownership marker. Once the
+original process group is also absent, a live desktop reclaims the directory;
+a later bridge can consume the same evidence. Local stream destruction, EPERM,
+an elapsed timeout or PID reuse never establishes exit. These readers/timers do
+not keep a closing CLI alive and send no process signals. Windows uses
+a foreground-command contract: tools must not outlive a normally completed Pi
+root. Normal root close is not evidence of native Windows job/tree containment.
+If the application exits before observing EOF, an old journal has no ownership
+evidence, or a Windows tree stop fails, automatic reclamation cannot prove safety.
+After stopping the bridge and confirming **all tools for that command stopped**, run:
+
+```sh
+mirrorx-device reclaim-config --kind pi --company COMPANY_ID --command COMMAND_ID --confirm-stopped
+```
+
+This local recovery command consumes only that journal entry's private temporary
+directory; it validates the canonical absolute path, location/ownership and token when present,
+refuses an active company/executor bridge lock, and preserves the running state
+and claim for reconciliation. It never acknowledges or relaunches the command.
+It also supports pre-token retained entries. No global `/tmp` sweep is performed.
+Escaped process groups are outside managed ownership. Real Windows runtime
+behavior still needs platform E2E verification.
+
+Only the MirrorX managed Billing profile is supported here: its producer writes
+models.json/settings.json, not auth.json, local extensions, or provider state.
+This restriction applies to the command's server-staged `PI_CODING_AGENT_DIR`,
+not the device's `PiDeviceRuntime.configDir`. Extra files, credential caches and
+MCP configuration in the local profile do not reject a command or get copied.
+Any additional staged entry is rejected before launch, regardless of which current
+or future settings key references it. The bridge does not classify Pi package
+sources or interpret resource settings; Pi owns those semantics. Arbitrary Pi
+profiles require a separate resource-transfer contract; they are not cloned.
+Missing settings.json stays absent in the command directory.
+EACCES and ENOSPC are reported immediately; transient filesystem failures retain the
+bounded retry. Materialized files are created mode0600 in a new private directory.
+
+When the supplied default model ID is absent, the bridge also checks the device's
+explicit settings default against the merged catalog. If neither is available,
+preparation fails with a configuration error; it does not silently select an
+arbitrary model. Injected provider `api` takes precedence over the local fallback
+because it describes the Billing endpoint protocol. Provider-level `compat` is
+not a supported Pi field; supported model-level `compat` is merged.
+
+A catalog-declared dash-prefixed model can be passed as `--model -odd-id`;
+the bridge normalizes `-m`, model/provider equals syntax to Pi's native
+`--model value` / `--provider value` form. Repeated options keep the last value;
+arguments after `--` stay unchanged. Informational commands leave
+model/provider option validation to Pi and do not inject defaults.
+Malformed staged settings retain the filename and `invalid JSON` diagnosis without
+including JSON content or credentials.
+
+Stop confirmation has separate platform paths in one completion-state helper.
+An unconfirmed stop emits one reconciliation notice including its failure reason.
+Windows accepts only its own stop-task outcome: a failed/pending stop after root
+exit requires reconciliation and retains configuration, never a POSIX negative-PID
+probe to infer success. POSIX alone performs bounded group observation/reaping.
+`active` owns live execution; `inFlight` continues through output/ACK transfer.
+A late stop during that transfer must not signal a reaped process. Root success
+while owned tools remain alive is not full-command completion; reconciliation
+remains required after the observation deadline. Help/version/list commands do
+not start model execution; ordinary execution receives the validated device model.
+Provider-level compat is stripped from both local and injected input, while
+supported model-level compat from both sources remains merged.
+
+### Embedded desktop runtime
+
+Desktop passes its app-owned Node and Pi launcher via `PiDeviceRuntime.executable`
+for recognized `pi` / `pi.cmd` / `pi.exe` commands, including path forms. No global Pi installation or shell
+interpolation is needed. Other commands, including the existing Codex bridge,
+retain their configured executable. Desktop restores only the current IAM
+subject, newly enrolled companies and configured service (`expectedBaseUrl`).
+A failed authenticated enrollment does not reactivate stale stored companies.
+Transport errors, timeouts, HTTP 408/429 and 5xx responses retry automatically
+with exponential delay from one second up to 30 seconds. Sign-out or a new
+identity cancels the pending retry; successful empty enumeration and permanent
+authentication/configuration failures do not restore old pairings or retry.
+A 200 response with only transient company-registration failures also retries.
+Once any company succeeds, an unsuccessful subset does not restart the whole
+bridge set; the client's bounded per-company retries remain in effect.
+
+`MIRRORX_DEVICE_HOME` optionally selects the credential/journal root. Desktop
+sets this to its profile's system directory; the standalone CLI default remains
+`~/.mirrorx-device`. Keep different services/profiles in separate roots. This
+override does not migrate or erase existing state.
+
+### Application-owned company recovery
+
+`enrollMirrorxDevice` accepts optional `companyIds` and `signal`. Scoped requests
+register only those companies, so recovery cannot rotate healthy companies'
+sessions. Cancellation reaches HTTP requests and short retry delays. Device
+RPC 401/403 terminates the affected loop after draining owned execution and
+releasing its bridge lock; other companies keep running. Network failures retain
+the existing 3s reconnect loop. `onConnectionState` reports actual connection and
+retry/failure transitions, separately from command reconciliation diagnostics.
+
+The embedded lifecycle holds one bridge per company, retries transient failed
+registrations with 1s–30s backoff and refreshes same-identity IAM credentials.
+Its existing HTTP status/reconnect entry includes device health and recovers
+failed companies without stopping healthy ones. Normal application quit aborts
+bridges and pending registration/retries; this is not a persistent daemon. Old
+Employee twin identities, tasks and workspaces are not migrated or adopted, and
+legacy PID/status files do not gate the new device connection.
+
+## WorkBuddy on macOS (experimental)
+
+Install and sign in to WorkBuddy first, then select **WorkBuddy (macOS)** in
+MirrorX Profile → Connect a device. Pair and run this same standalone client:
+
+```sh
+mirrorx-device pair --server https://your-mirrorx.example --kind codebuddy --code YOUR_CODE --workspace "/path/to/workspace"
+mirrorx-device run --kind codebuddy
+```
+
+Requires Node 22.19+ and the server's built-in `codebuddy_local` adapter
+(`@paperclipai/adapter-workbuddy-local`, registered like Codex and Pi).
+WorkBuddy is another executor kind in this same lightweight connector; no
+separate WorkBuddy connector package or external server adapter installation
+is required. The client uses
+WorkBuddy's built-in `/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`;
+a different executable may be selected **locally** with `MIRRORX_WORKBUDDY_CLI`.
+The server cannot select a desktop-auth source directory. Windows desktop-auth
+reuse is refused until native ACL and stop qualification exists. No API-key
+fallback, automatic WorkBuddy installation, or account migration is provided.
+
+Only actual `codebuddy` launches receive a private HOME/config and an opaque
+copy of the OS user's encrypted desktop-auth file. The source is never decrypted,
+logged, uploaded, or written back. A logout marker, symlink, unsafe ownership,
+permissions, or changing file identity refuses startup. Each launch checks CLI
+flags and current auth presence; a previous model success is not permanent login
+proof. Vendor keys, tokens, base URLs, NODE_OPTIONS, and personal configuration
+are excluded by rebuilding the final child environment. Local HTTP_PROXY,
+HTTPS_PROXY, ALL_PROXY and lowercase equivalents are retained and redacted before
+output spooling. Pi/Codex retain their existing environment behavior.
+
+Workspaces containing device state, desktop auth, the selected CLI, or run-private
+configuration are refused. The qualified profile exposes adapter-owned workspace file MCP tools and the current run's exact
+authorized MCP tools. Native Read/Write/Edit/Glob/Grep are disabled after a real probe showed Read can access a workspace-external canary. File operations go through the adapter MCP with path/link and size checks. Bash, Skills, subagents, personal MCP, cron and desktop
+features are unavailable. Every tool call also passes a private `PreToolUse`
+positive gate: only this run's exact MCP names are allowed, including rejection
+of unknown native tools or MCP names. `dontAsk` prevents approval prompts; it
+is insufficient on its own because safe native reads can be auto-approved.
+The explicit native deny list remains defense in depth and keeps these tools
+out of the advertised surface; `--tools` alone does not hide them. Workspaces
+must not overlap device state, the desktop-auth tree, or the WorkBuddy app bundle
+in either direction. Model selection uses CodeBuddy's native account
+default unless the employee explicitly selects a model; this mode does not
+use MirrorX Billing. Usage is recorded when supplied; monetary cost is unknown.
+
+Session transcripts stay in the client state directory, outside the workspace,
+scoped by service/company/employee/binding/real cwd/tool authorization. The
+connector saves a successful native transcript **before** deleting private auth
+and MCP configuration, then restores it before the next spawn. Only the selected
+transcript is saved; no auth or MCP credential files are copied into session
+storage. A transcript containing current MCP/proxy credential values is rejected.
+Both a workspace lock and a session lock reject overlap. An unsettled attempt fences the previous
+checkpoint rather than silently resuming stale state. CodeBuddy 2.137.1 receives
+new/resume prompts as positional arguments because stdin-only resume did not
+process the new prompt in the real contract probe.
+
+WorkBuddy 2.137.1 encodes the launch directory into one native session directory
+component. For long managed task paths, the connector launches in a short,
+command-private directory instead. MCP tools still use the original authorized
+task workspace; session identity and workspace locks keep that original path.
+Only the WorkBuddy executor can request this private launch directory. The
+sandbox still denies neighboring task workspaces. Checkpoints are collected
+from, and restored to, the actual private native-session bucket.
+
+Preparation records private-profile ownership in the command journal before
+acquiring workspace/session locks or reading authentication. Lock publication
+includes its owner atomically. A preparation crash retains this command-scoped
+recovery reference: stop the bridge and use `reclaim-config --kind codebuddy`
+with confirmed-stop evidence before retrying. Managed bindings must also pass
+`--company COMPANY_ID --binding BINDING_ID --command COMMAND_ID --confirm-stopped`
+so reclamation selects and locks the exact binding journal. An unknown binding
+fails rather than falling back to another connection. A retry never overwrites the
+retained reference. If preparation was explicitly cancelled before any business
+process started, the bridge rolls back only that preparation's fence and keeps
+the previous successful checkpoint, so resume does not require `reset-session`.
+
+Cancellation uses the existing owned process-tree contract, not WorkBuddy GUI
+shutdown. After verified shutdown, a CLI that handles the stop signal and exits
+zero is still acknowledged as stopped; it is not required to emit a successful
+provider result or create a success checkpoint. Unknown descendant shutdown
+continues to require reconciliation. Unconfirmed exit or failed transcript persistence retains the running
+journal/profile and requires reconciliation; it is never replayed. CodeBuddy
+profiles with incomplete shutdown/session evidence require explicit `reclaim-config`
+after independently confirming all tools stopped. Reclamation does not turn an
+unsettled native checkpoint into a resumable session.
+
+The protocol readiness check captures help with a private regular file descriptor:
+CodeBuddy 2.137.1 may exit before pipe output drains and omit help tail flags.
+A successful version check alone is insufficient. Only version **2.137.1** is
+qualified; other versions fail before task launch even if their help flags
+match. Qualify the permission contract again before updating this pin.
+See CodeBuddy's [PreToolUse contract](https://www.codebuddy.cn/docs/cli/hooks)
+and [permission-mode semantics](https://www.codebuddy.cn/docs/cli/permission-modes).
+The CLI remains trusted local software; these controls are not an OS sandbox.
+
+A clean process exit requires exactly one matching successful result before a
+checkpoint can be saved. Exactly one matching known error result (including
+`error_during_execution` with `is_error: true`) is a confirmed failed command,
+even when CodeBuddy exits zero. After confirming the process tree stopped, the
+bridge cleans its private launch configuration and acknowledges failure. It does
+not checkpoint or replay that failed native session: the unsettled session fence
+remains. Missing, malformed, unknown or duplicate results still require command
+reconciliation; exit zero alone cannot ACK success. A provider 401 needs normal
+WorkBuddy account reauthentication and is never repaired by relabeling the run.
+
+### Discard a fenced native session
+
+First reconcile the original command in MirrorX and independently confirm its
+tools stopped. Stop this company's bridge. If a private configuration remains,
+run the existing `reclaim-config --kind codebuddy` operation first. Reclaiming
+configuration alone deliberately leaves the native-session fence in place.
+The fenced-session error supplies `SESSION_KEY` and `SESSION_ID`:
+
+```sh
+mirrorx-device reset-session --kind codebuddy --company COMPANY_ID \
+  --session-key SESSION_KEY --session SESSION_ID --confirm-stopped
+```
+
+This explicit reset takes the company bridge and workspace/session locks,
+validates the stored company/identity, and deletes the old checkpoint **before**
+removing the fence. It neither changes the command journal/receipt nor retries
+business work. Resume of the discarded context fails; start a fresh session.
+Existing fenced sessions acquire their recovery identity when preparation is
+retried; do not manually delete state or locks to bypass ownership checks.
+
+New WorkBuddy pairings/IAM enrollments default to the sibling
+`<MIRRORX_DEVICE_HOME>-workspaces/<company>/codebuddy` directory (normally
+`~/.mirrorx-device-workspaces/...`). Pi/Codex defaults stay inside their existing
+workspaces directory. No files are moved. If an older WorkBuddy config selects
+a workspace inside the state/auth tree, pair again with an explicit safe
+`--workspace` and move your project files deliberately; the launch guard will
+not weaken itself to accept the old location.
+
+### Managed desktop workspaces
+
+In MirrorX **运行与集成**, select an online Amaster computer, choose Amaster, Codex or
+WorkBuddy, and name the employee. Additional Amaster employees require the desktop
+carrier to advertise `managedPiEmployees`; older clients show an upgrade requirement. A compatible desktop consumes
+only the signed intent addressed to its authenticated company/profile; no local
+directory picker or second per-employee connection prompt is needed. Login alone
+still connects only the personal twin. Custom project directories retain native confirmation.
+
+The desktop derives its workspace namespace from the canonical service,
+principal, profile, company and enrollment identity. Each employee has its own
+binding/config/journal/lock. The environment provider reuses core execution
+workspace IDs (or the exact task ID) for stable task directories and continuation.
+Managed commands validate ownership and real paths before spawn and use native
+filesystem confinement. Current managed qualification is macOS Seatbelt; other
+platforms fail closed and can use explicitly authorized custom workspaces.
+Existing custom bindings keep their paths and legacy resource lock keys.
+
+Native Pi/Codex session files are indexed by exact references under the binding's
+private state. History lookup validates the login, service, company, employee and
+source Run, and does not scan other employee workspaces or recreate legacy daemon
+markers. Task attachment, tool/MCP and artifact delivery still use the existing
+MirrorX adapter and task APIs. Connectivity remains optional and appears in Pi
+Settings → MirrorX.
+
+Codex cancellation first sends Ctrl-C (`SIGINT`) with a bounded grace period so Codex can interrupt its active turn and stop tool process groups it owns. It then uses the existing termination fallback while the command root is still owned. A forced Codex stop remains unconfirmed and requires reconciliation rather than acknowledging that detached tools have stopped. Pi/WorkBuddy and Windows retain their existing stop paths; a reaped root never authorizes signaling a reused PID.
+
+
+### Desktop sign-in restoration
+
+After logout, Pi retains the original tool binding and workspace but clears its credential. On sign-in it first reconnects Pi, then refreshes only previously authorized desktop tool sessions on the same account, company, profile and generation. No employee or workspace is recreated. The server rejects explicit revocation, profile transfers, active bridges and unsettled execution. Standalone connectors are not enrolled or restarted by this flow. Tool failures appear in Pi Settings → MirrorX and do not block normal Pi conversations.
+
+Local credential clearing precedes the remote sign-out request, including when a committed remote response is lost. Retained stale credentials may recover only from `DEVICE_SESSION_EXPIRED`, `DEVICE_SESSION_ROTATED`, or `DEVICE_SESSION_SIGNED_OUT` through the authenticated Pi session; `DEVICE_REVOKED` remains terminal. An idle bridge disconnect includes its company and exact instance ID so the server can release only that bridge's lease.
+
+
+### Independent Amaster employees
+
+An additional Amaster employee has a distinct intent-derived binding, managed
+workspace, journal and bridge. Automatic IAM registration excludes those bindings
+and always retains the original personal twin as the computer carrier. Only that
+carrier polls enrollment intents or restores other desktop sessions; its bridge
+runs with `computerCarrierOnly`, while managed Amaster bridges select one binding
+and receive the bundled Pi runtime. This prevents duplicate workers after restart.
+
+Managed Pi commands may read only the two desktop-generated runtime launcher
+files in the profile cache, supplied locally by the desktop (never by remote
+command payloads). The containing profile/cache directory remains unreadable;
+these files are read-only under Seatbelt. This supports the owned Pi entrypoint
+without exposing profile credentials or allowing a global runtime installation.
+
+The existing company membership, employee-creation permission, hiring approval,
+profile/generation and filesystem-confinement gates also apply to managed Amaster
+employees. Sign-out/sign-in restores their existing references on the original
+computer, without creating employees or replaying tasks. Moving these employees
+to a replacement computer is not supported by the legacy directory-recovery
+protocol; both server and UI reject that path rather than dropping confinement.
+
+### Review hardening: command secrets, logout, and legacy journals
+
+Managed Seatbelt reads are restricted to the current task, its exact private command configuration, approved launcher files and installed system/runtime roots. Other system temporary directories are not readable, including through `/var` aliases or task symlinks; required system alias metadata, shell selection and public CA files remain accessible. This policy is local to managed device commands, not the platform sandbox.
+
+The task-local `node` launcher resolves to the host process's canonical executable. When Node is installed by a version manager or CI tool cache outside the system roots, only that executable is additionally readable; its parent directories allow metadata lookup but not listing, adjacent-file reads or writes.
+
+Explicit enrollment participates in the desktop lifecycle transition and receives its cancellation signal. Logout waits for it before clearing device credentials. A claim response arriving after cancellation retains only a signed-out binding reference and revokes that response's narrow session; cancellation is checked on both sides of credential persistence.
+
+Before adopting a legacy company or single-tool journal into the identity-scoped path, the bridge checks its saved configuration against the authenticated binding, company, server, user and generation. It persists the migrated journal before replay/reconciliation and leaves the original evidence file in place. A different binding cannot inherit results or configuration cleanup references.
+
+### Local executable discovery
+
+Codex is launched through the canonical path of the selected local executable,
+so Homebrew symlinks do not hide companion binaries such as
+`codex-code-mode-host`. This does not change the selected installation or copy
+authentication from another environment. Managed macOS commands can inspect
+ancestor metadata of existing system read roots (for example `/opt` for
+`/opt/homebrew`) so Python can resolve its runtime; ancestor directory contents
+and neighboring task files remain denied.
+
+A finished journal receipt is retried independently of command polling: the server may have committed a terminal result before the response was lost. This retries output/receipt delivery only; it never relaunches the process. Unacknowledged records remain durable, with at least ten seconds between attempt starts per command, shared by poll replay and background recovery (including the first failed completion). The oldest eligible receipt is selected first so a rejected command cannot starve later receipts during long polling; replay always uses the journal’s original claim.
+
+During a requested drain, an unacknowledged finished journal is reported as
+requiring reconciliation after attempts already in flight settle. Neither
+background recovery nor poll replay starts a new receipt attempt after drain,
+even when multiple previous attempts overlap and continue failing. The bridge
+retains the result and does not claim a clean drain or re-execute the command.
+Normal startup retries durable receipts for Pi, Codex and WorkBuddy; only a
+successful acknowledgement removes the journal entry. Authorization/server
+failures keep it available for a later normal reconnect.

package/dist/codebuddy-auth.d.ts

@@ -0,0 +1,2 @@
+export declare function snapshotWorkbuddyAuth(targetHome: string, sourceHome?: string): void;
+//# sourceMappingURL=codebuddy-auth.d.ts.map

package/dist/codebuddy-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebuddy-auth.d.ts","sourceRoot":"","sources":["../src/codebuddy-auth.ts"],"names":[],"mappings":"AAeA,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,SAAe,QAiDlF"}

package/dist/codebuddy-auth.js

@@ -0,0 +1,80 @@
+/** Opaque desktop-auth copy. Never parses, decrypts, logs, or writes the source. */
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const relativeAuth = path.join("Library", "Application Support", "CodeBuddyExtension", "Data", "Public", "auth", "workbuddy-desktop.info");
+// Directory link counts legitimately change when another local test/project creates a child.
+// File link counts remain part of auth identity; ancestors still require matching dev/inode/owner/mode.
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.uid === b.uid && a.mode === b.mode && (!a.isFile() || a.nlink === b.nlink);
+function present(file) {
+    try {
+        return lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+// sourceHome is supplied only by local host code (os.homedir), never a command payload.
+export function snapshotWorkbuddyAuth(targetHome, sourceHome = os.homedir()) {
+    if (process.platform !== "darwin" || !process.getuid)
+        throw new Error("WorkBuddy desktop authentication is qualified only on macOS");
+    const source = path.join(sourceHome, relativeAuth);
+    const loggedOut = `${source}.logged-out`;
+    if (present(loggedOut))
+        throw new Error("Sign in to WorkBuddy before starting a task");
+    const chain = [];
+    let current = path.parse(source).root;
+    for (const component of ["", ...path.relative(current, source).split(path.sep)]) {
+        current = component ? path.join(current, component) : current;
+        const entry = present(current);
+        const isFile = current === source;
+        if (!entry)
+            throw new Error("WorkBuddy desktop login is missing");
+        if (entry.isSymbolicLink() || (isFile ? !entry.isFile() : !entry.isDirectory())
+            || (entry.uid !== process.getuid() && (isFile || entry.uid !== 0))
+            || ((entry.mode & 0o022) && !(entry.uid === 0 && !isFile && (entry.mode & 0o1000)))) {
+            throw new Error("WorkBuddy authentication path has unsafe ownership, permissions, or links");
+        }
+        if (isFile && (entry.nlink !== 1 || entry.size <= 0 || entry.size > 4 * 1024 * 1024))
+            throw new Error("Invalid WorkBuddy authentication file size");
+        chain.push({ file: current, stat: entry });
+    }
+    const descriptors = [];
+    let bytes;
+    try {
+        for (const { file, stat } of chain) {
+            const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | (file === source ? 0 : constants.O_DIRECTORY));
+            descriptors.push(fd);
+            const before = fstatSync(fd);
+            if (!same(before, stat))
+                throw new Error("WorkBuddy authentication changed during validation");
+            if (file === source) {
+                bytes = readFileSync(fd);
+                const after = fstatSync(fd);
+                if (!same(before, after) || before.size !== after.size || before.mtimeMs !== after.mtimeMs || bytes.length !== before.size) {
+                    throw new Error("WorkBuddy authentication changed during snapshot");
+                }
+            }
+        }
+        for (const { file, stat } of chain) {
+            const after = lstatSync(file);
+            if (after.isSymbolicLink() || !same(stat, after))
+                throw new Error("WorkBuddy authentication path changed during snapshot");
+        }
+        if (present(loggedOut))
+            throw new Error("WorkBuddy logged out during snapshot");
+        if (!bytes)
+            throw new Error("WorkBuddy authentication snapshot is empty");
+        const target = path.join(targetHome, relativeAuth);
+        mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        writeFileSync(target, bytes, { flag: "wx", mode: 0o600 });
+    }
+    finally {
+        bytes?.fill(0);
+        for (const fd of descriptors.reverse())
+            closeSync(fd);
+    }
+}
+//# sourceMappingURL=codebuddy-auth.js.map

package/dist/codebuddy-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebuddy-auth.js","sourceRoot":"","sources":["../src/codebuddy-auth.ts"],"names":[],"mappings":"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"}

package/dist/codebuddy-locks.d.ts

@@ -0,0 +1,12 @@
+import type { ConfigurationReference } from "./configuration-lifetime.js";
+/** Locks fence both native-session mutation and workspace writes, including crash recovery. */
+export declare function acquireCodebuddyLocks(stateRoot: string, keys: string[], recovery?: {
+    directory: string;
+    persist: () => Promise<void>;
+}): Promise<{
+    release: () => Promise<void>;
+    save: (directory: string) => Promise<void>;
+}>;
+/** Invoked only after configuration ownership and stopped evidence have been validated. */
+export declare function reclaimCodebuddyLocks(reference: ConfigurationReference, stateRoot: string): Promise<void>;
+//# sourceMappingURL=codebuddy-locks.d.ts.map

package/dist/codebuddy-locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebuddy-locks.d.ts","sourceRoot":"","sources":["../src/codebuddy-locks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,+FAA+F;AAC/F,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,EAAE;IACxF,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;;sBAqCuB,MAAM;GAI7B;AAED,2FAA2F;AAC3F,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,iBAkB/F"}