serverfs-agent-bridge git:20261020.3112f04A

Immutable. This exact content never changes and is served at /api/v1/blob/7257dd35339446c3.

---
name: serverfs-agent-bridge
description: Enable workdir Agent delegation; operate Bridge lifecycle, Codex/Claude/Qoder runtimes, proxy routing, Jev advice, or task/HITL failures.
---

# Operate ServerFS Agent Bridge

Agent delegation is an explicit optional capability. Preserve the two-process security boundary, per-workdir authorization, provider-native ownership and current-user lifecycle.

## When to use

Use this skill when the user explicitly wants to:

- enable/disable Agent delegation for selected workdirs;
- install/update/verify the Linux host Agent Bridge;
- configure native Windows/macOS Agent policy and Bridge lifecycle;
- allow Codex, Claude or Qoder runtimes;
- configure Agent-specific proxy routing or optional Jev advisory features;
- diagnose missing Agent tools, unavailable runtimes, Bridge IPC/identity errors, task lifecycle/HITL problems or provider parity issues.

## When NOT to use

Do not use this skill to:

- grant filesystem writes unless the user explicitly authorizes the workdir write policy;
- alter provider authentication/default permissions/sandbox policy merely to make a task run;
- upgrade provider CLIs outside the requested ServerFS/Agent operational objective;
- configure OpenAI Tunnel or HTTP Auth except where verifying their independence;
- diagnose an unknown whole-system outage before the Agent boundary is identified (`serverfs-diagnose`).

Jev is advisory only. It is not an Agent runtime, approval authority or fallback executor.

## Preflight

First locate the target ServerFS checkout or deployed installation and establish its version, active configuration and lifecycle owner. In imported/standalone mode, if no authoritative checkout/deployment source is accessible, stop at bounded guidance; do not mutate or infer target commands/settings.

Paths below are relative to the located **ServerFS checkout root**, never to this skill or the Plugin ZIP. Resolve repository paths only after locating that checkout. For an installed deployment without a checkout, use its version-matched deployment documentation, installed CLI help and active configuration; obtain matching sources before a step that needs missing repository material.

1. Identify platform and deployment family.
2. Read current workdir read-only and Agent policy before changing it.
3. Identify enabled runtimes and their actual provider binaries/native environment.
4. Locate provider credentials/private state and ensure they remain outside exposed workdirs and the MCP container.
5. Determine current Bridge/service owner and whether active Agent tasks/writer leases exist before any restart/update.
6. On Linux, measure/verify the real container peer identity; never assume `id -u/-g` is equivalent to the socket peer measurement.
7. Keep Tunnel, Agent and Jev proxy switches independent.

If provider policy or credential ownership is unclear, stop rather than copying interactive shell state wholesale or changing provider defaults.

## Authoritative sources

- `deployment/agent-bridge/README.md`
- `site/src/content/docs/docs/agent-bridge.md`
- `site/src/content/docs/docs/jev-advisors.md`
- `site/src/content/docs/docs/windows-native.md`
- `site/src/content/docs/docs/macos-native.md`
- `serverfs.toml.example`
- `.env.example`
- current `serverfs agent-bridge`, Agent task/runtime tools and Bridge verification behavior.

The Linux deployment guide is the authoritative step-by-step source for peer identity, user-owned paths, provider env, installer and rollback behavior. Do not duplicate its complete variable table here.

## Procedure

1. **Define the authorization boundary first.** Agent delegation is enabled only for selected workdirs/runtimes. A native runtime requiring `workspace-write` must not be enabled on a read-only workdir by silently widening filesystem policy. Record the selected workdir/runtime authorization and explicit write permission before enablement.
2. **Establish the provider-native baseline.** Confirm the selected provider CLI works for the same login user before blaming ServerFS. Preserve provider-owned auth and permission configuration. Proceed after direct CLI availability/version is observed for the same user.
3. **Configure only the required ServerFS policy.** Use Linux `.env` or native TOML as documented; keep provider secrets/private env in their dedicated user-owned boundary. Review the local policy diff and pass the applicable parser/doctor or Compose gate.
4. **Install/configure the Bridge through supported current-user lifecycle.** Do not create system users, root services or administrator services. Confirm status identifies the supported current-user owner.
5. **Verify IPC/identity before Agent tasks.** Prove Bridge status/runtime discovery and container/native connectivity. Proceed only after status, runtime discovery and applicable peer/RPC checks pass.
6. **Verify provider parity.** Compare direct provider version/availability with normalized ServerFS runtime evidence. Treat stale managed provider daemons using the provider's official lifecycle, not arbitrary kill/delete operations. Record direct and Bridge-reported runtime evidence; resolve unexplained differences before task testing.
7. **Exercise a disposable Agent task only after structural checks pass.** Use a safe workdir and verify poll/result/cancel/HITL as required by the user's objective. Record a terminal result and lease release; when cancel/HITL is exercised, verify those outcomes too.
8. **Preserve writer-lease semantics.** Never bypass a legitimate `WORKDIR_BUSY` by deleting locks or launching an uncontrolled parallel writer. Report busy/recovery state and use the documented lifecycle before retrying.

## Platform branches

Load only the matching branch after identifying the deployment and requested mode:

- Linux / Docker + host Bridge: read [linux branch](references/linux.md) before platform/mode-specific changes.
- Windows native: read [windows branch](references/windows.md) before platform/mode-specific changes.
- macOS native: read [macos branch](references/macos.md) before platform/mode-specific changes.

## Safety / stop conditions

Stop when:

- Agent enablement would require widening a workdir from read-only without explicit user approval;
- Linux measured peer identity differs from the current user;
- provider secrets would enter `.env`/TOML/workdir/container contrary to the current documented boundary;
- provider authentication/permission settings would have to be silently changed;
- a Bridge restart/update would interrupt active tasks without authorization;
- an active writer lease exists and someone proposes deleting/bypassing it;
- a stale provider daemon/process cannot be proven and safely handed over through its official lifecycle;
- Agent/Tunnel/Jev proxy settings are being conflated;
- root/Admin ownership is proposed as a fix.

Never manually delete a live control socket, lock or Bridge state as a first-line repair. Use documented lifecycle/rollback mechanisms.

## Verification

At the minimum level appropriate to the task, prove:

- intended workdir Agent mode/runtime allowlist is the effective policy;
- Bridge/service is owned by the current user and IPC identity checks pass;
- selected provider runtimes report the expected availability;
- direct provider and ServerFS-reported runtime versions/availability are consistent enough for the supported provider contract;
- a disposable task can be submitted/polled to terminal state when execution verification is requested;
- cancellation/HITL paths work when they are part of the changed boundary;
- writer lease is acquired/released correctly;
- Jev advice, if enabled, remains advisory and absence/failure does not gain execution authority;
- no provider credential appears in MCP container/config/log/task events.

Linux release/upgrade acceptance should use `verify_host.py --require-runtimes` and prove the container-to-Bridge RPC through the documented path.

## Success criteria

The task is complete when Agent delegation is enabled only where requested, uses the supported current-user Bridge/lifecycle, exposes only the intended runtime set, preserves provider-owned security configuration, and passes structural plus runtime verification appropriate to the change.

## Failure handling

If the Bridge is healthy but a provider runtime is unavailable, diagnose the provider-native lifecycle/environment for the same user; do not alter ServerFS filesystem security to compensate.

If an update fails on Linux, use the documented `deployment/agent-bridge/rollback_app.sh` path rather than manually swapping releases. If a provider managed daemon is stale, use its official update/bootstrap/hand-over flow after proving active work is quiescent.

Report whether failure is policy, IPC identity, Bridge lifecycle, provider availability, task lifecycle, proxy, Jev or writer-lease related. Do not collapse these boundaries into a generic "Agent failed" diagnosis.