@peakflo/agent-harness 0.2.11-rc.3 → 0.2.11-rc.5

package/README.md

@@ -54,7 +54,8 @@ Optional flags include `--health-port <port>`, `--runtime <desktop|self-hosted>`
 
 ## Connect your own agent in one command
 
-The Welcome window in Spaces shows one command for Codex, Claude Code, or
+Agents → "Connect your own agent" in Spaces (and the Welcome window during
+onboarding) shows one command for Codex, Claude Code, or
 Cursor, for example:
 
 ```sh
@@ -129,7 +130,8 @@ New service files start with `--service --stored-credential`. Older service
 files with only `--stored-credential` still work after an upgrade. Run
 `service repair` to update the file. The runner reads its saved credential
 from the workspace. If that credential is missing, expired, or
-rejected, start the runner once in a terminal to sign in again. The service
+rejected, open Agents → "Connect your own agent" in Spaces (or "Reconnect" on
+that machine) to get a new command, and run it on the machine. The service
 file and the service settings contain no enrolment token or runner credential.
 It stops after an invalid option, a refused harness version, an unusable
 credential, or a local port conflict. Linux waits 30 seconds before it retries

package/dist/adapters/pi-adapter.js

@@ -22,6 +22,7 @@ const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const model_gateway_1 = require("./model-gateway");
 const vendor_environment_1 = require("./vendor-environment");
+const browser_takeover_1 = require("../runtime/browser-takeover");
 const cold_start_steps_1 = require("../runtime/cold-start-steps");
 const dev_server_guard_1 = require("../runtime/dev-server-guard");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
@@ -167,7 +168,13 @@ function buildPiMcpConfigDocument(servers, onRename) {
                 // The managed integrations gateway can wait for a cold pfMCP
                 // instance. Its own upstream deadline is 270 seconds, so Pi must
                 // wait long enough to receive the gateway's result or clear error.
-                ...(name === 'integrations' ? { requestTimeoutMs: 300_000 } : {})
+                ...(name === 'integrations' ? { requestTimeoutMs: 300_000 } : {}),
+                // A browser call is HELD by the loopback proxy while a person
+                // controls the chat browser, for as long as they need. Pi's
+                // default 60 s timeout would fail the call mid-takeover.
+                ...(name === browser_takeover_1.BROWSER_SERVER_NAME
+                    ? { requestTimeoutMs: browser_takeover_1.BROWSER_MCP_TIMEOUT_MS }
+                    : {})
             }
         ];
     }));

package/dist/capabilities.d.ts

@@ -30,8 +30,11 @@ import { RunnerCapabilities } from './types';
  *
  * - `spaceFiles`: syncs `space-files/` (read-only) and serves
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
+ * - `browserTakeover`: holds a `browser` MCP call while a person controls the
+ *   chat browser (409 + `x-pf-browser-takeover`) and gives Pi a 24 h timeout
+ *   for that server. The API leases the `browser` server only with this.
  */
-export declare const HARNESS_FEATURES: readonly ["spaceFiles"];
+export declare const HARNESS_FEATURES: readonly ["spaceFiles", "browserTakeover"];
 /** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
 export declare function supportsPiSteering(version: string | null): boolean;
 export interface ProbeResult {

package/dist/capabilities.js

@@ -33,6 +33,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const browser_takeover_1 = require("./runtime/browser-takeover");
 const version_1 = require("./version");
 const PROBE_TIMEOUT_MS = 10_000;
 /**
@@ -41,8 +42,14 @@ const PROBE_TIMEOUT_MS = 10_000;
  *
  * - `spaceFiles`: syncs `space-files/` (read-only) and serves
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
+ * - `browserTakeover`: holds a `browser` MCP call while a person controls the
+ *   chat browser (409 + `x-pf-browser-takeover`) and gives Pi a 24 h timeout
+ *   for that server. The API leases the `browser` server only with this.
  */
-exports.HARNESS_FEATURES = ['spaceFiles'];
+exports.HARNESS_FEATURES = [
+    'spaceFiles',
+    browser_takeover_1.BROWSER_HARNESS_FEATURE
+];
 /** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
 function supportsPiSteering(version) {
     if (!version)

package/dist/cli.js

@@ -46,7 +46,8 @@ const USAGE = `pf-agent-harness — headless Peakflo coding-agent harness
 
 Usage:
   pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]
-                                one command from the Welcome window: approve
+                                one command from Agents → "Connect your own
+                                agent" in Spaces (or the Welcome window): approve
                                 this computer in the browser, connect the agent
                                 as your personal agent, run it in the background
   pf-agent-harness start [options]

package/dist/connect/connect.d.ts

@@ -1,7 +1,8 @@
 /**
  * `pf-agent-harness connect <vendor> --connection <id> [--control-plane <url>]`
  *
- * ONE COMMAND, copied from the Welcome window, that:
+ * ONE COMMAND, copied from Agents → "Connect your own agent" (or the
+ * Welcome window), that:
  *   1. checks the vendor CLI is installed and signed in;
  *   2. asks the signed-in user to approve this computer in the browser
  *      (loopback + PKCE + `state`; see workflow-api `byo-connect.ts`);
@@ -34,7 +35,7 @@ export interface ConnectArgs {
     appUrl?: string;
     openBrowser: boolean;
 }
-export declare const CONNECT_USAGE = "Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]\n\nCopy this command from the Welcome window in Spaces. It approves this computer\nin your browser, connects the agent as your personal agent, and keeps it\nrunning in the background.";
+export declare const CONNECT_USAGE = "Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]\n\nCopy this command from Agents \u2192 \"Connect your own agent\" in Spaces (or\n\"Reconnect\" on your machine there). It approves this computer\nin your browser, connects the agent as your personal agent, and keeps it\nrunning in the background.";
 export declare function parseConnectArgs(argv: string[], env?: NodeJS.ProcessEnv): ConnectArgs;
 /** The machine name the approval page shows. Must match the API's rule. */
 export declare function machineName(raw: string): string;

package/dist/connect/connect.js

@@ -2,7 +2,8 @@
 /**
  * `pf-agent-harness connect <vendor> --connection <id> [--control-plane <url>]`
  *
- * ONE COMMAND, copied from the Welcome window, that:
+ * ONE COMMAND, copied from Agents → "Connect your own agent" (or the
+ * Welcome window), that:
  *   1. checks the vendor CLI is installed and signed in;
  *   2. asks the signed-in user to approve this computer in the browser
  *      (loopback + PKCE + `state`; see workflow-api `byo-connect.ts`);
@@ -74,7 +75,8 @@ exports.VENDOR_SETUP = {
 };
 exports.CONNECT_USAGE = `Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]
 
-Copy this command from the Welcome window in Spaces. It approves this computer
+Copy this command from Agents → "Connect your own agent" in Spaces (or
+"Reconnect" on your machine there). It approves this computer
 in your browser, connects the agent as your personal agent, and keeps it
 running in the background.`;
 function flag(argv, name) {
@@ -124,7 +126,7 @@ function parseConnectArgs(argv, env = {}) {
     // `--token` is refused on purpose: this command never takes a secret.
     const connection = flag(argv, 'connection');
     if (!connection || !UUID.test(connection))
-        throw new ConnectError(`Copy the command from the Welcome window: it includes --connection <id>.\n\n${exports.CONNECT_USAGE}`);
+        throw new ConnectError(`Copy the command from Agents → "Connect your own agent" in Spaces: it includes --connection <id>.\n\n${exports.CONNECT_USAGE}`);
     const appUrl = flag(argv, 'app-url') ?? env.PF_APP_URL;
     return {
         vendor,
@@ -205,7 +207,7 @@ async function runConnect(args, deps) {
     const setup = exports.VENDOR_SETUP[vendor];
     const log = deps.log;
     if (deps.platform !== 'darwin' && deps.platform !== 'linux')
-        throw new ConnectError('connect needs macOS or Linux. On Windows, use "Ask my agent to do it" in the Welcome window.');
+        throw new ConnectError('connect needs macOS or Linux. On Windows, open Agents → "Connect your own agent" in Spaces and use "Ask my agent to do it instead".');
     const machine = machineName(deps.hostname());
     log(`Connecting ${setup.label} on ${machine}…`);
     /* 1. The vendor CLI must be installed and signed in. */
@@ -265,7 +267,7 @@ async function runConnect(args, deps) {
         exchange.json.vendor !== vendor)
         throw new ConnectError(typeof exchange.json.error === 'string'
             ? printable(exchange.json.error)
-            : `The approval could not be used (${exchange.status}). Get a new command from the Welcome window.`);
+            : `The approval could not be used (${exchange.status}). Open Agents → "Connect your own agent" in Spaces (or "Reconnect" on this machine) to get a new command.`);
     const company = typeof exchange.json.companyName === 'string'
         ? exchange.json.companyName
         : 'your company';
@@ -301,7 +303,7 @@ async function runConnect(args, deps) {
     if (!healthy)
         log(`! The service has not answered yet (it may still be starting, or a local port was taken). Check it with: npx @peakflo/agent-harness service status --vendor ${vendor}`);
     log('');
-    log(`✓ ${setup.label} is connected to ${company} on ${machine}. Return to the Welcome window.`);
+    log(`✓ ${setup.label} is connected to ${company} on ${machine}. Return to Spaces.`);
 }
 /* -------------------------------------------------------------------------- */
 /* Real dependencies                                                           */

package/dist/github-proxy.d.ts

@@ -1,7 +1,8 @@
-import { type Server } from 'node:http';
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { type RequestOptions as HttpsRequestOptions } from 'node:https';
 import { type Socket } from 'node:net';
 import type { GitHubProxyCertificates } from './github-proxy-certificates';
+import { type PeerUidResolver } from './runtime/loopback-peer';
 import type { LeasedGitHubCredential } from './types';
 export interface GitHubProxySession {
     sessionId: string;
@@ -15,6 +16,12 @@ export interface GitHubProxyOptions {
     logger?: Pick<Console, 'warn'>;
     connectDirect?: (hostname: string, port: number) => Socket;
     resolveUpstream?: (hostname: string) => Partial<HttpsRequestOptions>;
+    /**
+     * Injected in tests. Defaults to the /proc/net/tcp lookup. A chat browser
+     * uid gets its CONNECT socket closed at once, and a plain HTTP request 403
+     * (see `refuseBrowserPeer`). Unknown uids are unchanged (fail open).
+     */
+    peerUid?: PeerUidResolver;
 }
 export interface ReceivePackCommand {
     oldOid: string;
@@ -27,7 +34,19 @@ export declare class GitHubTlsProxy {
     private readonly listener;
     private readonly options;
     private readonly tunneled;
+    /**
+     * Chat browsers run as their own uids (20000-29999) with --no-sandbox; a
+     * compromised renderer must not get a GitHub tunnel carrying a session's
+     * credential. Looked up once per accepted connection.
+     */
+    private readonly peerGuard;
     constructor(listener: Server, options: GitHubProxyOptions);
+    /**
+     * For the listener's plain-HTTP handler (which the owner of the listener
+     * installs): answers a browser peer 403 `{"error":"forbidden"}` and returns
+     * true; otherwise returns false and the caller answers as before.
+     */
+    refuseBrowserPeer(request: IncomingMessage, response: ServerResponse): boolean;
     private refused;
     private logRefusal;
     private connect;

package/dist/github-proxy.js

@@ -9,6 +9,7 @@ const node_https_1 = require("node:https");
 const node_net_1 = require("node:net");
 const node_tls_1 = require("node:tls");
 const child_stream_guards_1 = require("./runtime/child-stream-guards");
+const loopback_peer_1 = require("./runtime/loopback-peer");
 const INTERCEPTED_HOSTS = new Set(['github.com', 'api.github.com']);
 const PASS_THROUGH_HOSTS = new Set([
     'objects.githubusercontent.com',
@@ -263,9 +264,17 @@ class GitHubTlsProxy {
     tunneled = (0, node_http_1.createServer)((request, response) => {
         void this.handle(request, response);
     });
+    /**
+     * Chat browsers run as their own uids (20000-29999) with --no-sandbox; a
+     * compromised renderer must not get a GitHub tunnel carrying a session's
+     * credential. Looked up once per accepted connection.
+     */
+    peerGuard;
     constructor(listener, options) {
         this.listener = listener;
         this.options = options;
+        this.peerGuard = new loopback_peer_1.BrowserPeerGuard(options.peerUid);
+        this.peerGuard.attach(listener);
         listener.on('connect', (request, socket, head) => {
             // A refused CONNECT commonly makes the client reset the TCP connection
             // after it receives our 403. Without an error listener Node promotes that
@@ -273,9 +282,22 @@ class GitHubTlsProxy {
             // harness. Install the guard before the first await/write in connect(),
             // including for targets outside the GitHub allowlist.
             (0, child_stream_guards_1.guardStream)(socket, 'GitHubProxy/connect');
+            if (this.peerGuard.isBrowser(socket)) {
+                // No response at all: nothing about the proxy is told to a browser.
+                socket.destroy();
+                return;
+            }
             void this.connect(request, socket, head);
         });
     }
+    /**
+     * For the listener's plain-HTTP handler (which the owner of the listener
+     * installs): answers a browser peer 403 `{"error":"forbidden"}` and returns
+     * true; otherwise returns false and the caller answers as before.
+     */
+    refuseBrowserPeer(request, response) {
+        return this.peerGuard.refuse(request.socket, response);
+    }
     refused(sessionId, kind, path, response, reason) {
         this.logRefusal(sessionId, kind, path);
         reply(response, 403, reason);

package/dist/github-workspace.d.ts

@@ -1,5 +1,6 @@
 import { type RequestListener, type Server } from 'node:http';
 import type { WorkspaceProvider, WorkspaceRequest } from './ports';
+import type { PeerUidResolver } from './runtime/loopback-peer';
 import type { LeasedGitHubCredential } from './types';
 export interface GitHubWorkspaceOptions {
     root: string;
@@ -7,6 +8,8 @@ export interface GitHubWorkspaceOptions {
     createServer?: (handler: RequestListener) => Server;
     logger?: Pick<Console, 'warn'>;
     directUrls?: string[];
+    /** Injected in tests: the proxy's peer-uid lookup. See `GitHubTlsProxy`. */
+    peerUid?: PeerUidResolver;
 }
 /** Bare clone plus one worktree per session, adapted from 20x. */
 export declare class GitHubWorkspaceProvider implements WorkspaceProvider {

package/dist/github-workspace.js

@@ -248,14 +248,19 @@ class GitHubWorkspaceProvider {
         }
     }
     async startServer() {
-        const server = (this.options.createServer ?? node_http_1.createServer)((_request, response) => {
+        // Assigned below, before the server listens, so every request sees it.
+        let tlsProxy = null;
+        const server = (this.options.createServer ?? node_http_1.createServer)((request, response) => {
+            if (tlsProxy?.refuseBrowserPeer(request, response))
+                return;
             response.writeHead(400, { 'content-type': 'text/plain' });
             response.end('This endpoint is an HTTPS CONNECT proxy.\n');
         });
         const certificates = await (0, github_proxy_certificates_1.createGitHubProxyCertificates)(this.options.root);
         this.caCertificatePath = certificates.caCertificatePath;
-        new github_proxy_1.GitHubTlsProxy(server, {
+        tlsProxy = new github_proxy_1.GitHubTlsProxy(server, {
             certificates,
+            peerUid: this.options.peerUid,
             logger: this.options.logger,
             isDirectHostAllowed: (hostname) => this.directHosts.has(hostname),
             findSession: (sentinel) => [...this.sessions.values()].find((entry) => entry.sentinel === sentinel)

package/dist/harness.d.ts

@@ -164,6 +164,11 @@ export declare class Harness {
     private readonly health;
     private readonly proxy;
     /** One loopback host for every session this process runs (P9 knowledge tools). */
+    /**
+     * PF_KNOWLEDGE_PORT / PF_MCP_PROXY_PORT: fixed loopback ports, set by
+     * pf-bootstrap in a sandbox so the chat browser's Landlock rule can deny
+     * them by number. Unset (desktop) = ephemeral, as before.
+     */
     private readonly knowledgeHost;
     private readonly store;
     /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
@@ -269,6 +274,14 @@ export declare class Harness {
     /** Same idea, for the INDEPENDENT sandbox-tools pin (gh, node deps, ...). */
     private pendingSandboxToolsVersion;
     constructor(options: HarnessOptions, deps?: HarnessDeps);
+    /**
+     * BROWSER TAKEOVER, proxy → runner. The loopback proxy is holding (or has
+     * stopped holding) a `browser` call because a person controls the chat
+     * browser. The gateway URL names the session; its runner counts the hold as
+     * an intentional pause. No live runner → refuse, so the call is not parked
+     * for a turn that is gone.
+     */
+    private onBrowserPause;
     /** The actual bound health port. Used by tests to prove the socket closed. */
     getHealthPort(): number | null;
     snapshot(): HealthReport;

package/dist/harness.js

@@ -17,6 +17,7 @@ const harness_discovery_1 = require("./harness-discovery");
 const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
+const browser_takeover_1 = require("./runtime/browser-takeover");
 const knowledge_tools_1 = require("./runtime/knowledge-tools");
 const lease_renewal_1 = require("./runtime/lease-renewal");
 const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
@@ -115,7 +116,7 @@ exports.VersionRefusedError = VersionRefusedError;
 /** A service cannot re-enrol without a new one-time token from a user. */
 class StoredCredentialUnavailableError extends Error {
     constructor() {
-        super('No usable stored runner credential. Start the runner in a terminal to sign in again.');
+        super('No usable stored runner credential. For your own agent, open Agents in Spaces and use "Reconnect" on this machine (or "Connect your own agent") to get a new command, then run it here. For a self-hosted runner, start it once in a terminal to sign in again.');
         this.name = 'StoredCredentialUnavailableError';
     }
 }
@@ -172,7 +173,15 @@ class Harness {
     health;
     proxy;
     /** One loopback host for every session this process runs (P9 knowledge tools). */
-    knowledgeHost = new knowledge_tools_1.KnowledgeToolHost({ logger: console });
+    /**
+     * PF_KNOWLEDGE_PORT / PF_MCP_PROXY_PORT: fixed loopback ports, set by
+     * pf-bootstrap in a sandbox so the chat browser's Landlock rule can deny
+     * them by number. Unset (desktop) = ephemeral, as before.
+     */
+    knowledgeHost = new knowledge_tools_1.KnowledgeToolHost({
+        logger: console,
+        port: (0, mcp_auth_proxy_1.loopbackPortFromEnv)(process.env.PF_KNOWLEDGE_PORT)
+    });
     store;
     /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
     conversation;
@@ -324,9 +333,31 @@ class Harness {
             deps.credentialStore ??
                 (0, credential_store_1.createCredentialStore)(options.runtime, options.workspaceRoot);
         this.proxy = new mcp_auth_proxy_1.McpAuthProxy({
+            port: (0, mcp_auth_proxy_1.loopbackPortFromEnv)(process.env.PF_MCP_PROXY_PORT),
             tokens: this.tokens,
-            notifier: this.notifier
+            notifier: this.notifier,
+            onBrowserPause: (targetUrl, event) => this.onBrowserPause(targetUrl, event)
+        });
+    }
+    /**
+     * BROWSER TAKEOVER, proxy → runner. The loopback proxy is holding (or has
+     * stopped holding) a `browser` call because a person controls the chat
+     * browser. The gateway URL names the session; its runner counts the hold as
+     * an intentional pause. No live runner → refuse, so the call is not parked
+     * for a turn that is gone.
+     */
+    onBrowserPause(targetUrl, event) {
+        const sessionId = (0, browser_takeover_1.sessionIdFromGatewayUrl)(targetUrl);
+        const runner = sessionId ? this.runners.get(sessionId) : undefined;
+        if (!sessionId || !runner)
+            return event.state !== 'start';
+        const accepted = runner.setBrowserPaused(sessionId, event.state === 'start');
+        log('Browser takeover hold', {
+            sessionId,
+            state: event.state,
+            ...(event.state === 'end' ? { reason: event.reason } : { accepted })
         });
+        return accepted;
     }
     /** The actual bound health port. Used by tests to prove the socket closed. */
     getHealthPort() {
@@ -1794,6 +1825,9 @@ class Harness {
          * passed for the wrong reason.
          */
         const modelGateway = new model_gateway_1.SessionModelGateway();
+        // Two independent reasons to renew urgently; neither may clear the other.
+        let approvalWaiting = false;
+        let browserPaused = false;
         const runner = new session_runner_1.SessionRunner({
             mcpCheckState: this.mcpCheckState,
             getAdapter: (backend) => {
@@ -1841,6 +1875,13 @@ class Harness {
              * hard to poll the control plane for the answer. Nothing else in the
              * process knows a permission is outstanding.
              */
+            onBrowserPauseChange: (id, paused) => {
+                // Same tight renewal cadence as an approval, so a handback command
+                // (or abort) rides back quickly. Lease renewal keeps running either way.
+                browserPaused = paused;
+                renewal.setUrgent(paused || approvalWaiting);
+                log('Browser pause changed', { sessionId: id, paused });
+            },
             onApprovalStateChange: (id, waiting) => {
                 /*
                  * NO SET IS KEPT HERE. An earlier version also maintained an
@@ -1852,7 +1893,8 @@ class Harness {
                 // Event-driven, not polled: the cadence changes at the instant the
                 // prompt opens, so the first tight renewal happens ~2s later rather
                 // than up to a minute later.
-                renewal.setUrgent(waiting);
+                approvalWaiting = waiting;
+                renewal.setUrgent(waiting || browserPaused);
                 log('Approval state changed', { sessionId: id, waiting });
             },
             ingest: (id, parts, turn, final, modelMessages) => this.client
@@ -1928,6 +1970,11 @@ class Harness {
             }
             // Revoke ONLY this session's tokens. A process-wide revoke here blanked
             // the credential of every concurrent turn still running.
+            // A browser call held for a person cannot outlive its turn.
+            for (const url of mcpTargetUrls) {
+                if ((0, browser_takeover_1.isBrowserTargetUrl)(url))
+                    this.proxy.cancelBrowserHolds(url);
+            }
             this.tokens.revokeTargets(mcpTargetUrls);
             modelGateway.revoke();
             githubWorkspace.clearCredential?.(sessionId);

package/dist/health.d.ts

@@ -1,3 +1,4 @@
+import type { Socket } from 'node:net';
 import { HealthReport } from './types';
 /**
  * Health check for pf-bootstrap and for the Daytona liveness probe.
@@ -6,6 +7,17 @@ import { HealthReport } from './types';
  * from outside the sandbox, and session users get no useful secret from it —
  * the report deliberately carries no token.
  *
+ * BROWSER USERS GET NOTHING. A chat's Chromium runs as its own uid (20000-
+ * 29999) with --no-sandbox and uses the sandbox network directly (no egress
+ * proxy, no firewall), so a page or a compromised renderer could connect here
+ * and learn the tenant id, runner id, versions and heartbeat errors. On Linux each
+ * request's peer uid is looked up in /proc/net/tcp{,6}; a browser uid gets a
+ * bare 403. The guard FAILS OPEN when the uid cannot be determined (non-Linux,
+ * /proc unreadable, no matching row): the probe and pf-bootstrap run as root
+ * or pfharness, the report holds no secret, and failing closed would turn a
+ * /proc hiccup into a dead liveness probe. Only a CONFIRMED browser uid is
+ * refused.
+ *
  * STOP MUST ACTUALLY CLOSE, and this is the reason `boundPort` and the socket
  * tracking below exist. `server.close()` stops ACCEPTING connections but leaves
  * any keep-alive connection open, and an open connection keeps the Node event
@@ -18,6 +30,8 @@ import { HealthReport } from './types';
 export declare class HealthServer {
     private readonly port;
     private readonly report;
+    /** Injected by tests; defaults to the /proc/net/tcp lookup. */
+    private readonly lookupPeerUid;
     private server;
     /**
      * The port the server actually bound to, RETAINED after `stop()`.
@@ -29,7 +43,9 @@ export declare class HealthServer {
     private bound;
     /** Live connections, tracked so `stop()` can destroy them. */
     private readonly sockets;
-    constructor(port: number, report: () => HealthReport);
+    constructor(port: number, report: () => HealthReport, 
+    /** Injected by tests; defaults to the /proc/net/tcp lookup. */
+    lookupPeerUid?: (socket: Socket) => number | null);
     /** The actual bound port, or null before `start()`. Survives `stop()`. */
     get boundPort(): number | null;
     start(): Promise<void>;
@@ -41,5 +57,7 @@ export declare class HealthServer {
      * process exits, without weakening enrolment or running two ready harnesses.
      */
     private listenOnce;
+    /** A lookup that throws counts as "unknown" — fail open, see the class doc. */
+    private safePeerUid;
     stop(): Promise<void>;
 }

package/dist/health.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HealthServer = void 0;
 const node_http_1 = require("node:http");
+const loopback_peer_1 = require("./runtime/loopback-peer");
 const BIND_RETRY_INTERVAL_MS = 100;
 const BIND_RETRY_TIMEOUT_MS = 10_000;
 /**
@@ -11,6 +12,17 @@ const BIND_RETRY_TIMEOUT_MS = 10_000;
  * from outside the sandbox, and session users get no useful secret from it —
  * the report deliberately carries no token.
  *
+ * BROWSER USERS GET NOTHING. A chat's Chromium runs as its own uid (20000-
+ * 29999) with --no-sandbox and uses the sandbox network directly (no egress
+ * proxy, no firewall), so a page or a compromised renderer could connect here
+ * and learn the tenant id, runner id, versions and heartbeat errors. On Linux each
+ * request's peer uid is looked up in /proc/net/tcp{,6}; a browser uid gets a
+ * bare 403. The guard FAILS OPEN when the uid cannot be determined (non-Linux,
+ * /proc unreadable, no matching row): the probe and pf-bootstrap run as root
+ * or pfharness, the report holds no secret, and failing closed would turn a
+ * /proc hiccup into a dead liveness probe. Only a CONFIRMED browser uid is
+ * refused.
+ *
  * STOP MUST ACTUALLY CLOSE, and this is the reason `boundPort` and the socket
  * tracking below exist. `server.close()` stops ACCEPTING connections but leaves
  * any keep-alive connection open, and an open connection keeps the Node event
@@ -23,6 +35,7 @@ const BIND_RETRY_TIMEOUT_MS = 10_000;
 class HealthServer {
     port;
     report;
+    lookupPeerUid;
     server = null;
     /**
      * The port the server actually bound to, RETAINED after `stop()`.
@@ -34,9 +47,12 @@ class HealthServer {
     bound = null;
     /** Live connections, tracked so `stop()` can destroy them. */
     sockets = new Set();
-    constructor(port, report) {
+    constructor(port, report, 
+    /** Injected by tests; defaults to the /proc/net/tcp lookup. */
+    lookupPeerUid = (socket) => (0, loopback_peer_1.peerUid)(socket)) {
         this.port = port;
         this.report = report;
+        this.lookupPeerUid = lookupPeerUid;
     }
     /** The actual bound port, or null before `start()`. Survives `stop()`. */
     get boundPort() {
@@ -73,6 +89,11 @@ class HealthServer {
                     res.end(JSON.stringify({ error: 'Not found' }));
                     return;
                 }
+                if ((0, loopback_peer_1.isBrowserUid)(this.safePeerUid(req.socket))) {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'forbidden' }));
+                    return;
+                }
                 const body = this.report();
                 // 'starting' is not yet healthy, so a probe waits rather than
                 // declaring the sandbox ready too early.
@@ -96,6 +117,15 @@ class HealthServer {
             });
         });
     }
+    /** A lookup that throws counts as "unknown" — fail open, see the class doc. */
+    safePeerUid(socket) {
+        try {
+            return this.lookupPeerUid(socket);
+        }
+        catch {
+            return null;
+        }
+    }
     async stop() {
         const server = this.server;
         if (!server) {

package/dist/runtime/browser-takeover.d.ts

@@ -0,0 +1,32 @@
+/**
+ * BROWSER TAKEOVER — the harness half of the sandbox-browser wire.
+ *
+ * COPIED, NOT IMPORTED. The source of truth is the core contract
+ * `packages/core/src/services/coding-agents/browser-protocol.ts`. This package
+ * is published to npm on its own and must not depend on `@pf-workflo/core`, so
+ * the few values the harness needs are repeated here.
+ * `__tests__/browser-takeover-contract.test.ts` reads the core source text and
+ * fails if any of them drift.
+ */
+/** Built-in gateway server id; the gateway URL ends with `/<this id>`. */
+export declare const BROWSER_BUILTIN_SERVER_ID = "pf-browser";
+/** The MCP server name the agent's backend sees. */
+export declare const BROWSER_SERVER_NAME = "browser";
+/** 409 + this header = a person holds the browser; hold the agent's call. */
+export declare const BROWSER_TAKEOVER_HEADER = "x-pf-browser-takeover";
+/** Sent on re-tries during a hold; the gateway then waits up to 20 s. */
+export declare const BROWSER_AWAIT_HANDBACK_HEADER = "x-pf-browser-await-handback";
+export declare const BROWSER_TAKEOVER_STATUS = 409;
+/** How long the gateway holds one await-handback request. */
+export declare const BROWSER_AWAIT_HANDBACK_HOLD_MS = 20000;
+/** Pi's MCP request timeout for the `browser` server (24 h). */
+export declare const BROWSER_MCP_TIMEOUT_MS: number;
+/** Advertised in `capabilities.features`; the API leases `browser` only then. */
+export declare const BROWSER_HARNESS_FEATURE = "browserTakeover";
+/** True for a gateway target URL of the built-in browser server. */
+export declare function isBrowserTargetUrl(targetUrl: string): boolean;
+/**
+ * The session id in a gateway URL `.../api/mcp/agent/<sessionId>/<serverId>`,
+ * or null when the URL has another shape.
+ */
+export declare function sessionIdFromGatewayUrl(targetUrl: string): string | null;