@engineeros/connector 1.49.0 → 1.52.0

package/README.md

@@ -2,26 +2,59 @@
 
 The connector uses an authenticated EngineerOS WebSocket for pairing, workspace identity, run lifecycle, and evidence. Coding work can run through any agent in the official ACP registry, a custom ACP v1-compatible command over stdio, or the Forge command line. Direct Codex CLI remains available as the compatibility path.
 
+## Hunt a running app without a repository
+
+Choose **Find bugs in a running app** in EngineerOS, register a preview or staging URL, and copy its command:
+
+```sh
+npx --yes @engineeros/connector@latest hunt-host CODE --url https://your-backend.example --project PROJECT_UUID --agent codex-acp
+```
+
+Use `claude-acp` for Claude. This installs the selected agent, pairs immediately, sets up Playwright and checks a browser
+and agent session. It uses `~/.engineeros/hunt-hosts/PROJECT_UUID`; it never initializes or inspects a repository,
+submits workspace snapshots, or starts a Goal runner. Keep this terminal open.
+
+If prompted, run `codex login`, or run `claude` and `/login`, in another terminal on this machine. The host checks again
+every 30 seconds for 30 minutes, then every five minutes. EngineerOS shows the same sign-in instructions.
+If auto-start was selected, the first public-page hunt starts once readiness passes. Writing is limited to 10 minutes;
+proving failures and reviewing them follow. Continuous hunting stays off, and failures are never retried automatically.
+
+Restart a paired host with:
+
+```sh
+npx --yes @engineeros/connector@latest hunt-host --project PROJECT_UUID
+```
+
+Add test accounts in Bug Hunter Setup to go deeper. **Connect your code** opens the existing Steering connection flow
+and pairs a separate connector in your repository. `hunt-host` refuses `--workspace` and `--onboard`.
+
 ## Independent Goal runner
 
 Connector 1.2.0 hands Goal jobs to a separate local runner. Closing the connector terminal or losing its WebSocket does not stop an executing Goal. Progress and final results use HTTP; undelivered results remain on disk for retry. Windows supervisors and workers use a windowless launcher; Goal runs and agent commands do not open new terminals.
 
-Install from a permanent global installation or repository checkout, then run:
+Install explicitly, or let the first Goal dispatch install and start the runner:
 
 ```text
 engineeros-connector runner install --workspace D:\Puli\work\workspaces\caresched
 engineeros-connector runner status --workspace D:\Puli\work\workspaces\caresched
 ```
 
-The first Goal dispatch also installs/starts the runner when using a permanent executable path. Temporary `npx` cache paths cannot host a persistent service: install the connector globally first. Update the backend for the HTTP claim endpoint before dispatching Goals.
+When started through `npx`, the connector installs that exact version into `~/.engineeros/connector/versions/<version>` with lifecycle scripts disabled, SHA-512 lockfile verification, npm registry signature checks and a version smoke test. Global installations and repository checkouts use their existing entry. A version change reinstalls the service; existing workers keep their code. Registry or verification failures leave Goals queued with a setup remedy. Update the backend for the HTTP claim endpoint before dispatching Goals.
 
 Windows uses Task Scheduler under your current user, restarts after failure, and resumes saved jobs at sign-in following reboot. Linux uses a systemd user service; enable user lingering separately if recovery must start before login. Existing running jobs stay with their current process; resume an interrupted run to hand it to the new service.
 
+On macOS, the runner is a per-user launchd agent in your GUI login session. It starts at login, retains your installer PATH and uses your signed-in coding agent and login Keychain. Expect a **Background Items Added** notice; manage it in **System Settings > General > Login Items**. A disabled runner stays queued until you enable it with `engineeros-connector runner start --workspace PATH`. `doctor` reports disabled, unloaded and failed services; startup output is in `.engineeros/runner/launchd.log`.
+
+macOS can deny a background Node process access to Desktop, Documents, Downloads or iCloud Drive even when your terminal has access. Move the workspace elsewhere, or allow `node` in **Privacy & Security > Files and Folders**. During each Goal, `caffeinate -i -w <worker pid>` prevents idle sleep; it does not prevent lid-close sleep. Inactivity and heartbeat monitoring allow time to resume after sleep. To disable keep-awake for this workspace, run `engineeros-connector runner install --workspace PATH --keep-awake off` (use `on` to restore it). This saves `runner_keep_awake` in the paired connector configuration.
+
+Remove the background service on any platform with `engineeros-connector runner uninstall --workspace PATH`. Queued jobs, checkpoints and results stay on disk and resume after installation. Running workers are independent of the service. Verified releases used by the runner are retained across updates until uninstall.
+
 Files under your project's `.engineeros` directory:
 
 - `runner/inbox/`: durable job dispatch requests.
 - `runner/service.json`: supervisor PID and heartbeat.
 - `runner/service.log`: supervisor startup and cleanup diagnostics.
+- `runner/launchd.log`: macOS output before service logging starts.
 - `runs/<run-id>/job.json`: execution/delivery status, saved assignment, pending result or failure.
 - `runs/<run-id>/state.json`: coding session and implementation/verification checkpoints.
 - `runs/<run-id>/activity.log`: timestamped activity and periodic inactivity status.