git:20261020.3112f04 to git:20261023.0697ed9

8 added, 1 removed. Audit B to B.

---

name: serverfs-diagnose

description: Investigate an unknown ServerFS failure or check deployment health; identify the failing boundary before authorized repair.

---

# Diagnose ServerFS

Use a read-first evidence ladder. Do not repair while the failing boundary is still unknown.

## When to use

Use this skill when the user reports that ServerFS is unavailable, unhealthy, misconfigured, disconnected, returning errors, exposing the wrong capability surface, or behaving differently after a restart/upgrade, and the cause is not already established.

Also use it for a bounded health check or to prove the current deployment state before another operational change.

## When NOT to use

Do not use this as the main workflow when the requested change is already explicit:

- first installation: use `serverfs-install`;

- ordinary configuration mutation: use `serverfs-configure`;

- planned upgrade: use `serverfs-upgrade`;

- known Tunnel work: use `serverfs-tunnel`;

- known HTTP API Key/OAuth work: use `serverfs-auth`;

- known Agent Bridge/runtime/Jev work: use `serverfs-agent-bridge`.

Do not use diagnosis as permission to change configuration, restart services, delete state, reinstall packages or rotate credentials unless the user requested remediation and the cause is established.

## 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 the target host and platform: Linux, supported Windows native, or supported macOS native.

2. Identify the deployment family and how ServerFS is currently owned:

- Linux Docker Compose;

- Windows current-user native lifecycle;

- macOS current-user ServiceManagement lifecycle;

- bounded manual/direct diagnostic invocation.

3. Locate the authoritative configuration without printing secrets:

- Linux: existing `.env` plus the exact Compose files used;

- native: `serverfs.toml` plus the narrow `.env` used by the managed lifecycle.

4. Record the observed failure and timestamp. Separate facts from hypotheses.

5. Do not infer a remote/live state from a different machine or platform.

## Authoritative sources

Read the smallest relevant current sources before drawing conclusions:

- `site/src/content/docs/docs/getting-started.md`

- `site/src/content/docs/docs/windows-native.md`

- `site/src/content/docs/docs/macos-native.md`

- `site/src/content/docs/docs/tunnel-diagnostics.md`

- `site/src/content/docs/docs/host-observability.md`

- `deployment/windows/README.md`

- `deployment/macos/README.md`

- `deployment/agent-bridge/README.md`

- the target installation's `serverfs --version`, `serverfs doctor`, service status and current config parser behavior.

Historical `dev_plan_v*.md` files are evidence of past releases, not current-state instructions.

## Procedure

1. **Prove the deployment identity.** Capture ServerFS version, platform, deployment owner and the exact configuration file/Compose shape in use. Do not expose credential values. Proceed when version, owner and active config are evidenced on the target host.

2. **Run the least invasive product health surface first.** Prefer `serverfs doctor` for native deployments and configuration-aware checks. On Linux, render the exact Compose shape before assuming runtime failure. Record the exit status and redacted error or successful result before selecting the next check.

3. **Check ownership/lifecycle.** Determine whether the intended current-user service/container is actually the owner. Look for duplicate/manual processes only through supported status/process evidence; do not kill by executable name. Proceed when the runtime owner is proven or report ownership as the blocker.

4. **Check the narrow failing boundary.** Examples:

- filesystem/workdir: parser/doctor + target root accessibility;

- generic HTTP: MCP container state, Host/Origin policy and exact published endpoint;

- Tunnel: route to `serverfs-tunnel` and use its layered health evidence;

- API Key/OAuth: route to `serverfs-auth` after confirming the configured mode;

- Agent tools/runtime: route to `serverfs-agent-bridge` after confirming Agent policy and Bridge status.

+ - For Agent problems, follow the **Correlated Agent Diagnostics (v0.22+ / feature-detect)** section in `skills/serverfs-agent-bridge/SKILL.md`: check the installed version or `serverfs diagnostics --help` (or equivalent capability listing) first. Only when advertised, use `serverfs diagnostics snapshot --format json` and `serverfs diagnostics task <task-id> --format json`. These are not v0.21 guarantees; fall back to the version-supported Agent status/runtime surfaces when absent.

5. **Bound logs and redact.** Read only the recent logs needed to explain the failure. Never dump `.env`, provider environment, keys, bearer tokens or unrestricted logs. Retain only redacted evidence tied to the observed symptom.

6. **Form one evidence-backed diagnosis.** If evidence supports multiple causes, state what would distinguish them before changing anything. Finish this step with a supported cause or a specific read-only check that distinguishes the remaining hypotheses.

7. **Remediate only when authorized.** Apply the smallest correction using the subsystem's dedicated skill, then repeat the original failing check. Report the repeated check’s observed result; unresolved or unexecuted checks remain explicit blockers.

## Platform branches

### Linux / Docker Compose

Start with the exact Compose files the deployment uses. Common read-only checks include:

```bash

docker compose config --quiet

docker compose ps

```

For an Agent-enabled deployment, include `-f compose.agent.yml`; for generic HTTP include `-f compose.http.yml`; for OAuth include `-f compose.oauth.yml`. Do not validate a different Compose shape from the one actually deployed.

Inspect bounded logs only for the affected service. A container being `Up` is not proof that Tunnel control-plane or MCP response delivery is healthy.

### Windows native

Run the ServerFS executable from the stable current-user connector environment and use the real config:

```powershell

& $serverfs doctor --config serverfs.toml

& $serverfs service status

+ & $serverfs service status --format common-json

+ # Or: --format common-human

```

- The intended persistent owner is the current-user Task Scheduler lifecycle. Do not substitute SCM/LocalSystem, Administrator execution, a repository `.venv`, or the legacy manual launcher as a repair shortcut.

+ The opt-in v0.21 `common-json`/`common-human` formats provide a bounded, sanitized status projection. They omit sensitive identifiers and use `unknown`/`not-checked` when a fact is unavailable; they do not replace `doctor` or its configuration-aware checks. The default status output remains unchanged. The intended persistent owner is the current-user Task Scheduler lifecycle. Do not substitute SCM/LocalSystem, Administrator execution, a repository `.venv`, or the legacy manual launcher as a repair shortcut.

### macOS native

Use the supported native CLI surfaces:

```bash

serverfs doctor --config serverfs.toml

serverfs service status

+ serverfs service status --format common-json

+ # Or: serverfs service status --format common-human

```

If status reports that background-item approval is required, that is a user-controlled macOS state. Use `serverfs service open-settings` only when remediation is requested; do not bypass approval with raw launchd/root mechanisms.

## Safety / stop conditions

Stop and report evidence instead of continuing when:

- the platform/deployment family cannot be established;

- the current configuration source is unknown;

- a proposed repair requires root/Administrator or changes the established ownership model;

- the target contains unknown local/source modifications that would be overwritten;

- a secret would need to be printed or moved into a workdir to proceed;

- the failure belongs to an optional subsystem whose user intent is unclear;

- `doctor`, config parsing or Compose rendering fails after a proposed change;

- a process/service identity cannot be proven safely.

Never delete auth state, Agent state, credentials, locks, sockets or service registrations merely because they look stale. Use the subsystem's documented recovery path.

## Verification

Verification must repeat the evidence that originally failed and add the narrow product-level health proof appropriate to the platform.

Minimum examples:

- configuration parses/renders successfully;

- `serverfs doctor` exits successfully where applicable;

- intended managed service/container owns the runtime;

- the failing subsystem reports healthy/expected state;

- no unintended optional subsystem was enabled or disabled.

For Tunnel, Auth or Agent problems, use the dedicated skill's verification contract rather than treating a generic process-up state as sufficient.

## Success criteria

Diagnosis is complete when:

- the failing boundary is identified with observable evidence;

- facts and hypotheses are clearly separated;

- any remediation performed is minimal and authorized;

- the original failure is re-tested and resolved, or the remaining blocker is explicitly demonstrated;

- no credential, operator configuration or platform ownership boundary was weakened.

## Failure handling

If the cause remains unresolved, report:

1. exact checks executed and their outcomes;

2. the smallest remaining set of plausible causes;

3. the next read-only discriminator for each cause;

4. checks not executed and why.

Do not claim a fix from source inspection alone, and do not continue with random configuration changes after repeated equivalent failures.