@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/services/quota-fetcher/service.js

@@ -0,0 +1,74 @@
+import { createProviderUsageFetchers } from "./manifest.js";
+import { unavailableUsage } from "./usage.js";
+const DEFAULT_PROVIDER_USAGE_CACHE_TTL_MS = 5 * 60 * 1000;
+export class ProviderUsageService {
+    constructor(options) {
+        this.cached = null;
+        this.inFlight = null;
+        this.revision = 0;
+        this.logger = options.logger.child({ module: "provider-usage-service" });
+        const factoryOptions = {
+            logger: this.logger,
+            fetch: options.fetch,
+        };
+        this.rebuildFetchers = options.fetchers
+            ? null
+            : (options.fetcherFactory ??
+                ((providers) => createProviderUsageFetchers(factoryOptions, providers)));
+        this.fetchers = options.fetchers ?? this.rebuildFetchers?.(options.providerConfigs ?? {}) ?? [];
+        this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_PROVIDER_USAGE_CACHE_TTL_MS;
+        this.now = options.now ?? Date.now;
+    }
+    updateProviderConfigs(providers) {
+        if (!this.rebuildFetchers)
+            return;
+        this.fetchers = this.rebuildFetchers(providers);
+        this.revision += 1;
+        this.cached = null;
+        this.inFlight = null;
+    }
+    async listUsage(options) {
+        const nowMs = this.now();
+        if (!options?.forceRefresh &&
+            this.cached &&
+            nowMs - this.cached.fetchedAtMs < this.cacheTtlMs) {
+            return this.cached.result;
+        }
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        const request = this.fetchFreshUsage(nowMs, this.revision);
+        this.inFlight = request;
+        try {
+            return await request;
+        }
+        finally {
+            if (this.inFlight === request) {
+                this.inFlight = null;
+            }
+        }
+    }
+    async fetchFreshUsage(nowMs, revision) {
+        const fetchers = this.fetchers;
+        const settled = await Promise.allSettled(fetchers.map((fetcher) => fetcher.fetchUsage()));
+        const providers = settled.map((result, index) => {
+            const fetcher = fetchers[index];
+            if (result.status === "fulfilled") {
+                return result.value;
+            }
+            this.logger.debug({ err: result.reason, providerId: fetcher.providerId }, "Provider usage fetch failed");
+            return unavailableUsage({
+                providerId: fetcher.providerId,
+                baseProviderId: fetcher.baseProviderId,
+                displayName: fetcher.displayName,
+                error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+            });
+        });
+        const result = { fetchedAt: new Date(nowMs).toISOString(), providers };
+        if (revision === this.revision) {
+            this.cached = { fetchedAtMs: nowMs, result };
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/server/services/quota-fetcher/usage.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { ProviderUsage, ProviderUsageBalance, ProviderUsageTone, ProviderUsageWindow } from "../../server/messages.js";
+import type { ProviderApiFetch } from "./provider.js";
+export declare const ApiNumberSchema: z.ZodCoercedNumber<unknown>;
+export declare const ApiNullableNumberSchema: z.ZodPreprocess<z.ZodNullable<z.ZodCoercedNumber<unknown>>>;
+export declare const ApiOptionalStringSchema: z.ZodPreprocess<z.ZodOptional<z.ZodCoercedString<unknown>>>;
+export declare function fetchProviderApi(fetchApi: ProviderApiFetch, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function unavailableUsage(provider: {
+    providerId: string;
+    baseProviderId?: string;
+    displayName: string;
+    error?: string | null;
+}): ProviderUsage;
+export declare function windowFromUsedPct(input: {
+    id: string;
+    label: string;
+    utilizationPct: number | null | undefined;
+    resetsAt?: string | null;
+    tone?: ProviderUsageWindow["tone"];
+}): ProviderUsageWindow;
+/**
+ * The tone scale for anything measured against a known limit, windows and balances alike.
+ *
+ * Thresholds match `deriveTone` in the app's provider-usage/tone.ts, which is what the
+ * client falls back to when a window arrives without a tone. Healthy is "ok" rather than
+ * "default" because that is what every provider setting a tone has always sent, and it is
+ * what the bars render today below their thresholds.
+ */
+export declare function toneFromUsedPct(usedPct: number | null | undefined): ProviderUsageTone;
+/**
+ * Tone for a balance with no known limit, where a percentage cannot be computed and the
+ * only signal is whether anything is left. Prefer `toneFromUsedPct` when a limit exists:
+ * this one stays "ok" until the balance is completely spent.
+ */
+export declare function balanceToneFromRemaining(remaining: number | null | undefined): ProviderUsageBalance["tone"];
+/** Percentage of a limit consumed, or null when either side is unknown. */
+export declare function usedPctOf(used: number | null | undefined, limit: number | null | undefined): number | null;
+export declare function toIsoStringOrNull(timestampMs: number): string | null;
+//# sourceMappingURL=usage.d.ts.map

package/dist/server/services/quota-fetcher/usage.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+const PROVIDER_HTTP_TIMEOUT_MS = 15000;
+export const ApiNumberSchema = z.coerce.number().finite();
+export const ApiNullableNumberSchema = z.preprocess((value) => (value == null ? null : value), ApiNumberSchema.nullable());
+export const ApiOptionalStringSchema = z.preprocess((value) => (value == null ? undefined : value), z.coerce.string().optional());
+export function fetchProviderApi(fetchApi, input, init = {}) {
+    return fetchApi(input, {
+        ...init,
+        signal: init.signal ?? AbortSignal.timeout(PROVIDER_HTTP_TIMEOUT_MS),
+    });
+}
+export function unavailableUsage(provider) {
+    return {
+        providerId: provider.providerId,
+        ...(provider.baseProviderId ? { baseProviderId: provider.baseProviderId } : {}),
+        displayName: provider.displayName,
+        status: provider.error ? "error" : "unavailable",
+        planLabel: null,
+        windows: [],
+        balances: [],
+        details: [],
+        error: provider.error ?? null,
+    };
+}
+export function windowFromUsedPct(input) {
+    const usedPct = typeof input.utilizationPct === "number" ? input.utilizationPct : null;
+    const window = {
+        id: input.id,
+        label: input.label,
+        usedPct,
+        remainingPct: usedPct === null ? null : Math.max(0, 100 - usedPct),
+        resetsAt: input.resetsAt ?? null,
+    };
+    if (input.tone) {
+        window.tone = input.tone;
+    }
+    return window;
+}
+/**
+ * The tone scale for anything measured against a known limit, windows and balances alike.
+ *
+ * Thresholds match `deriveTone` in the app's provider-usage/tone.ts, which is what the
+ * client falls back to when a window arrives without a tone. Healthy is "ok" rather than
+ * "default" because that is what every provider setting a tone has always sent, and it is
+ * what the bars render today below their thresholds.
+ */
+export function toneFromUsedPct(usedPct) {
+    if (typeof usedPct !== "number")
+        return "default";
+    if (usedPct > 90)
+        return "danger";
+    if (usedPct >= 70)
+        return "warning";
+    return "ok";
+}
+/**
+ * Tone for a balance with no known limit, where a percentage cannot be computed and the
+ * only signal is whether anything is left. Prefer `toneFromUsedPct` when a limit exists:
+ * this one stays "ok" until the balance is completely spent.
+ */
+export function balanceToneFromRemaining(remaining) {
+    if (typeof remaining !== "number")
+        return "default";
+    if (remaining <= 0)
+        return "danger";
+    return "ok";
+}
+/** Percentage of a limit consumed, or null when either side is unknown. */
+export function usedPctOf(used, limit) {
+    if (typeof used !== "number" || typeof limit !== "number" || limit <= 0)
+        return null;
+    return (used / limit) * 100;
+}
+export function toIsoStringOrNull(timestampMs) {
+    const date = new Date(timestampMs);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+}
+//# sourceMappingURL=usage.js.map

package/dist/server/skills/paseo/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: paseo
+description: Paseo reference for managing projects, workspaces, workspace scripts, agents, schedules, and heartbeats.
+---
+
+Paseo is a remote daemon that manages coding agents, terminals. Control it through MCP tools or the CLI.
+
+## Projects
+
+Manage the daemon's project registry through the CLI:
+
+```bash
+paseo project create [path]
+paseo project ls
+paseo project rename <project-id> <name>
+paseo project rename <project-id> --reset
+paseo project delete <project-id>
+```
+
+For a local daemon, `project create` defaults to the current directory and resolves relative paths on the CLI machine. With `--host` or `PASEO_HOST`, always provide a path; the target daemon interprets it on its own machine. Deleting a project archives its active workspaces and removes the project from Paseo without deleting the project directory.
+
+## Workspaces
+
+**`create_workspace`** — create a workspace independently of any agent. Required: `isolation` (`local` or `worktree`). Worktree isolation supports `mode: "branch-off" | "checkout-branch" | "checkout-pr"`: use `branchName`/`baseBranch` for a new branch, `branch` for an existing branch, or `prNumber` plus optional `forge`/`projectPath` for a change request. `worktreeSlug` controls the managed path. Returns the workspace descriptor centered on `workspaceId`.
+
+**`list_workspaces`** — list active workspaces.
+
+**`archive_workspace`** — `{ workspaceId }`. Archives the workspace, its agents, and its terminals. Local directories remain; Paseo removes an owned worktree only after its final active workspace reference is archived.
+
+**`rename_workspace`** — `{ workspaceId, name }`. Rename workspace.
+
+## Workspace scripts
+
+Configured `paseo.json` scripts use the same supervised lifecycle from tools and the CLI.
+
+**`list_workspace_scripts`** — `{ workspaceId }`. Lists configured scripts with lifecycle, service port, proxy URLs, health, exit code, and terminal ID.
+
+**`start_workspace_script`** — `{ workspaceId, scriptName }`. Starts one configured script through Paseo's managed workspace-script launcher and returns its status metadata.
+
+**`stop_workspace_script`** — `{ workspaceId, scriptName }`. Stops a running script through its supervised terminal and returns the stopped status metadata.
+
+The matching CLI surface accepts either an explicit workspace ID or resolves the current directory:
+
+```bash
+paseo script ls [--cwd <path> | --workspace <workspace-id>]
+paseo script start <name> [--cwd <path> | --workspace <workspace-id>]
+paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]
+```
+
+## Agents
+
+**`create_agent`** — required: `title`, `provider` (`claude/opus`, `codex/gpt-5.4`, …), `initialPrompt`. Optional: `workspaceId`, `notifyOnFinish`, `settings`, `labels`. Returns `{ agentId, workspaceId, … }`.
+
+Initial runtime settings live under `settings`: `modeId`, `thinkingOptionId`, and provider-specific `features`. Agent profiles are the preferred source for these values. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }` when creating the agent.
+
+Agent-scoped creation always creates your subagent. Omit `workspaceId` to use your current workspace; pass a workspace returned by `create_workspace` for isolated delegation. Placement never changes parentage.
+
+Detach is an explicit user action in the subagents track, not an agent tool. A cross-workspace child remains your subagent even though it also appears as a normal tab in its workspace.
+
+Agent-scoped `create_agent` defaults `notifyOnFinish` to true. Set it to `false` only for truly fire-and-forget agents.
+
+**`send_agent_prompt`** — `{ agentId, prompt }`. Use for follow-ups to an existing agent. Agent-scoped prompt calls default to `background: true` and `notifyOnFinish: true`; top-level calls default to blocking with no callback. For a synchronous follow-up, pass `background: false` and use the returned result.
+
+**`update_agent`** — `{ agentId, name?, labels?, settings? }`. Use `settings` for runtime changes on an existing agent: `modeId`, `model`, `thinkingOptionId`, and provider-specific `features`. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }`.
+
+**`list_agents`** — filter by `cwd`, `statuses`, `sinceHours`, `includeArchived`.
+
+**`archive_agent`** — `{ agentId }`. Interrupts if running, removes from active list.
+
+## Agent profiles and provider discovery
+
+**`list_profiles`** — named launch bundles configured by the human. Before choosing how to launch a delegated agent, call this tool and read every profile's `notes`. Pick a named profile the user requested, or the profile whose notes best match the work.
+
+There is no `profile` parameter on `create_agent`. Materialize the selected profile into the call:
+
+- combine `provider` and `model` as the `provider/model` value for `create_agent.provider`
+- copy `modeId` to `settings.modeId`
+- copy `thinkingOptionId` to `settings.thinkingOptionId`
+- copy `featureValues` to `settings.features`
+
+Omit absent values. Do not remember a selected profile or infer drift later; a profile is only launch configuration.
+
+If no profile fits, or no profiles are configured, use the provider discovery tools below rather than guessing. Tell the user when you fall back because no configured profile fits.
+
+**`list_providers`** — compact provider availability and modes.
+
+**`list_models`** — full model list for one provider. Use only when you need model IDs or thinking options; the list can be large.
+
+**`inspect_provider`** — compact provider capability and feature inspection. Required: `provider`; pass `cwd` when you are not in an agent-scoped session. Optional: `settings` with draft `model`, `modeId`, `thinkingOptionId`, and `features`.
+
+Only set feature IDs returned by `inspect_provider`. For Codex fast mode, look for `fast_mode` and pass `settings: { features: { "fast_mode": true } }` to `create_agent` or `update_agent`.
+
+## Schedules and heartbeats
+
+**`create_schedule`** — starts a new agent on a cron cadence. Required: `prompt`, `cron`, `provider`. Optional: `timezone`, `name`, `cwd`, `maxRuns`, `expiresIn`. Use when the recurring work should live in fresh agents.
+
+**`create_heartbeat`** — sends you a prompt on a cron cadence. Required: `prompt`, `cron`. Optional: `timezone`, `name`, `maxRuns`, `expiresIn`. Use for reminders, PR/build babysitting, and status checks that should return to this conversation.
+
+**`delete_heartbeat`** stops it. MCP intentionally exposes no heartbeat update tool; delete and recreate when its task or cadence changes.
+
+Schedules have the full list/inspect/update/pause/resume/run-once/log/delete surface. Heartbeats deliberately do not.
+
+## Waiting
+
+Agents take time — 10–30+ minutes is routine. Favor asynchronous workflows.
+
+For agent-scoped `create_agent` and background `send_agent_prompt`, leave `notifyOnFinish` omitted or set it to `true` unless the work is truly fire-and-forget. You will get notified when the target agent finishes, errors, or needs permission. Move on to other work. The notification arrives on its own.
+
+Don't poll `list_agents` or `get_agent_status` to "check on" a running agent. The notification will tell you.
+
+## CLI semantics
+
+The CLI and tools use the same ownership semantics even where their syntax differs:
+
+```bash
+paseo workspace create --isolation worktree --mode branch-off --new-branch fix-x --base main
+paseo workspace create --isolation worktree --mode checkout-branch --branch existing-work
+paseo workspace create --isolation worktree --mode checkout-pr --pr-number 42
+paseo run --provider codex/gpt-5.4 --mode full-access --workspace <workspace-id> "<prompt>"
+paseo run --provider codex/gpt-5.4 --mode full-access --new-workspace worktree --worktree-mode branch-off --new-branch fix-x --base main "<prompt>"
+paseo send <agent-id> "<follow-up>"
+paseo ls
+paseo schedule create --cron "*/15 * * * *" "ping main build"
+paseo heartbeat create --cron "*/15 * * * *" "check the build"
+```
+
+Discover with `paseo --help` and `paseo <cmd> --help`.
+
+For product questions, setup, logs, version problems, or troubleshooting, use the **paseo-help** skill.

package/dist/server/skills/paseo-advisor/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: paseo-advisor
+description: Spin up a single agent as an advisor — second opinion on the current task. Use when the user says "advisor", "second opinion", "what does X think", or wants an outside take without delegating the work itself.
+user-invocable: true
+argument-hint: "[--profile <name>] <question or topic>"
+---
+
+# Paseo Advisor
+
+Single agent. Reads the situation you're in. Gives a judgment. You decide what to do — the advisor doesn't drive the work.
+
+**User's request:** $ARGUMENTS
+
+## Prerequisites
+
+Read the **paseo** skill. Call `list_profiles` before choosing the advisor. Do not create the advisor until you have read the configured profiles and their `notes`.
+
+## Picking the advisor
+
+1. **User named a profile** (`--profile UI Work`) → select it by name.
+2. **Otherwise** choose the profile whose `notes` best fit the question. Match the actual work: design and approach, audit and review, or research and root-cause analysis.
+3. **Contrast helps.** When several profiles fit, prefer a different provider family from your own so the second opinion is genuinely fresh.
+
+Materialize the selected profile into `create_agent` as described by the **paseo** skill. If no profile fits, use Paseo's provider discovery fallback.
+
+## The briefing
+
+The advisor has zero context. Make it self-contained:
+
+- The question, sharply.
+- What you've considered and what you've ruled out.
+- Relevant files by path (don't paste — let the agent read).
+- Explicit ask: "give me a recommendation, with reasoning."
+
+End with the no-edits suffix:
+
+```
+This is analysis only. Do NOT edit, create, or delete any files. Do NOT write code.
+```
+
+## Forwarded skills
+
+If `$ARGUMENTS` contains another skill reference — `/unslop`, `/unslop-risk`, `$unslop`, etc. — the user is asking the advisor to run that skill against the current task. Examples:
+
+- `/paseo-advisor /unslop` → advisor runs `/unslop` on the current diff.
+- `/paseo-advisor /unslop-risk` → advisor does an unslop-risk review.
+- `/paseo-advisor $diagnose this build failure` → advisor invokes `/diagnose`.
+
+Parse the forwarded skill name out of `$ARGUMENTS` (`/<name>` or `$<name>`). In the briefing, tell the advisor explicitly:
+
+```
+Invoke the `<name>` skill against this task. Load it via the Skill tool before doing anything else.
+```
+
+Pass through any remaining arguments after the skill name as the skill's own input. The advisor — not you — runs the skill; you're still just the orchestrator handing it the work.
+
+## Launch and synthesize
+
+Create the advisor agent via Paseo with a `[Advisor] <topic>` title and the briefing as the initial prompt. Wait for it to finish. Read its response. Synthesize for the user — the advisor's verdict + your recommendation.
+
+## Persistent advisor
+
+If the user wants ongoing input ("keep this advisor for the next few decisions"), don't archive after the first reply. Send follow-ups when you need another take. Archive when the user says they're done, or when the topic shifts and a fresh context would serve better.

package/dist/server/skills/paseo-committee/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: paseo-committee
+description: Form a committee of two high-reasoning agents to step back, do root cause analysis, and produce a plan. Use when stuck, looping, tunnel-visioning, or facing a hard planning problem.
+user-invocable: true
+---
+
+# Committee Skill
+
+Two agents from contrasting profiles, fresh context, planning a solution in parallel.
+
+**User's additional context:** $ARGUMENTS
+
+## Prerequisites
+
+Read the **paseo** skill. Call `list_profiles` before choosing committee members. Do not create committee agents until you have read the configured profiles and their `notes`.
+
+Contrast is the point of a committee, so pick profiles from different provider families when possible. Materialize each profile into `create_agent`.
+
+## Composition
+
+Two members with different reasoning styles, selected from configured Agent profiles:
+
+- one whose notes fit planning, research, or root-cause analysis
+- one contrasting high-reasoning profile from another provider family
+
+If the user names profiles, use those. If fewer than two suitable profiles are configured, use Paseo's provider discovery fallback for the missing member and tell the user. Override the selection only when the user explicitly asks for different members.
+
+## Hard rules
+
+- **No edits.** Every prompt to a committee member ends with the no-edits suffix:
+
+  ```
+  This is analysis only. Do NOT edit, create, or delete any files. Do NOT write code.
+  ```
+
+- **Trust the finish notification.** Do not poll, send hurry-ups, or interrupt. Models can reason for 15–30 minutes. You can go idle and Paseo will notify you.
+
+## Workflow
+
+1. Write a problem-level prompt
+2. Create both agents in parallel via Paseo with `[Committee] <task>` titles and the same prompt
+3. Wait for both responses
+4. Resolve disagreements by passing their arguments between each other
+5. Keep going until they converge into a response
+
+Share the consensus with the user. Summarize where the agents diverged and how they resolved it.

package/dist/server/skills/paseo-handoff/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: paseo-handoff
+description: Hand off the current task to another agent with full context. Use when the user says "handoff", "hand off", "hand this to", or wants to pass work to another agent.
+user-invocable: true
+---
+
+# Handoff Skill
+
+Transfer the current task — context, decisions, failed attempts, constraints — to a fresh agent. The receiving agent starts with **zero context**, so the handoff prompt must be a self-contained briefing.
+
+**User's arguments:** $ARGUMENTS
+
+## Prerequisites
+
+Read the **paseo** skill. Call `list_profiles` before choosing the receiving agent. Do not create it until you have read the configured profiles and their `notes`.
+
+## Parsing arguments
+
+1. **Agent profile** — explicit profile name first; otherwise choose the profile whose `notes` best match the work. Materialize it into `create_agent` as described by the **paseo** skill. If no profile fits, use Paseo's provider discovery fallback.
+2. **Isolation** — "in a worktree" / "worktree" → create a workspace with `isolation: "worktree"`, using a short branch name derived from the task.
+3. **Task description** — anything else the user said.
+
+## The handoff prompt
+
+The receiving agent has zero context. Include:
+
+```
+## Task
+[Imperative description.]
+
+## Context
+[Why this task exists, required context.]
+
+## Relevant files
+- `path/to/file.ts` — [what it is and why it matters]
+
+## Current state
+[What's done, what works, what doesn't.]
+
+## What was tried
+- [Approach] — [why it failed or was abandoned]
+
+## Decisions
+- [Decision — rationale]
+
+## Acceptance criteria
+- [ ] [Criterion]
+
+## Constraints
+- [Must-not / must-preserve]
+```
+
+**Preserve task semantics.** Investigate-only → "DO NOT edit files." Fix → "implement the fix." Refactor → "refactor, not rewrite." Carry the user's exact intent.
+
+## Launch
+
+Prepare the handoff in a dedicated workspace:
+
+1. Select the current workspace or call `create_workspace` with the requested isolation.
+2. Call `create_agent` with a `[Handoff] <task>` title, the briefing as initial prompt, and the selected `workspaceId` when explicit placement is needed.
+3. Return the agent and workspace to the user, explaining that it remains in your subagent track until they detach it manually.
+
+Do not encode independence as a create mode and do not invoke CLI or wire-level detach operations. Detach is a user gesture in the subagents track.
+
+Do not wait or poll for the agent to finish.

package/dist/server/skills/paseo-help/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: paseo-help
+description: Answer questions about the Paseo product and app, including setup, configuration, connectivity, providers, workspaces, updates, logs, and troubleshooting. Use when a user inside Paseo asks how Paseo works, how to configure it, or why something is broken; use the paseo skill instead to operate agents and workspaces through MCP or the CLI.
+---
+
+# Paseo Help
+
+You are helping a user understand, configure, or troubleshoot Paseo itself. Answer their question directly, verify the answer against the current public documentation, and include the relevant documentation link. Do not send the user away to read the docs in place of helping them.
+
+**User's question:** $ARGUMENTS
+
+## Use current documentation
+
+Fetch [https://paseo.sh/llms.txt](https://paseo.sh/llms.txt) first. It is the current index of Paseo documentation, with a description and Markdown URL for each page.
+
+Use that index to select the page that owns the user's question, then fetch the linked `.md` page before answering. For troubleshooting, begin with [Common problems](https://paseo.sh/docs/troubleshooting.md) and follow its links when the issue belongs to a more specific page.
+
+Prefer the deployed docs over memory. Answer the user directly, then link the relevant `.md` page as supporting documentation.
+
+## Establish the topology first
+
+Identify the daemon involved before diagnosing versions, paths, providers, logs, updates, or connectivity. Do not infer the daemon from the client: Paseo Desktop can manage its bundled local daemon and connect to other remote daemons at the same time.
+
+Establish two facts:
+
+1. **Where and how the daemon runs**
+   - **Desktop-managed:** Paseo Desktop bundles, starts, and updates a daemon on that computer. No separate daemon install is required.
+   - **Standalone:** the daemon was installed separately, commonly through the npm CLI, and runs independently of the desktop app.
+   - **Docker:** the daemon, its home, provider CLIs, credentials, and code mounts live in the container runtime.
+2. **How the affected client reaches it**
+   - same-machine local connection
+   - relay connection
+   - direct LAN, VPN, or Tailscale connection
+   - daemon-served web UI
+
+Use **Settings → About** to compare the app version with each connected host. For the affected host, open **Settings → your host → Overview → Full status**. On the daemon machine, `paseo daemon status --json` reports facts such as server ID, hostname, version, home, listen address, process owner, log path, and whether the daemon is desktop-managed.
+
+Record which host the user is viewing and which machine or container runs it. A local `paseo daemon status` describes the daemon for that CLI's local `PASEO_HOME`; it may not be the remote host visible in the app.
+
+Apply later checks to the daemon runtime, not automatically to the client device:
+
+- Provider binaries, credentials, `PATH`, workspaces, config, and daemon logs live on the daemon machine or inside its container.
+- App version and app logs live on the client device.
+- A desktop-managed daemon follows the Desktop app lifecycle and update path.
+- A standalone daemon follows its own CLI/npm lifecycle and may use a different `PASEO_HOME` or listen address.
+- A Docker daemon uses container paths, volumes, user permissions, image versions, and container lifecycle commands.
+
+## Diagnose before changing state
+
+After identifying the affected host, compare that daemon's version with the client app version. Ask the user to update both through the correct topology-specific update path. Old versions and app/daemon version skew cause many apparent bugs, and fixes ship frequently. Use the Updates page and the installation-specific docs for current instructions.
+
+Use the smallest relevant read-only checks:
+
+```bash
+paseo --version
+paseo daemon status --json
+paseo provider diagnostic <provider> --json
+```
+
+Use the status-reported home, listen address, and log path for further checks. Probe `http://127.0.0.1:6767/api/health` or read `~/.paseo/daemon.log` only when those values match the affected daemon. Do not restart the daemon, edit config, update software, or expose a network listener without the user's explicit permission. A daemon restart can interrupt the agent doing the diagnosis.
+
+For a missing provider or `command not found`, run `paseo provider diagnostic <provider>` against the affected host, or open **Settings → your host → Providers → provider → Diagnostic**. Compare its resolved binary, daemon `PATH`, and provider version with a brand-new login shell. Shell aliases and functions are not executable paths.
+
+## Logs and local files
+
+Use these defaults on the machine where the daemon or Desktop app actually runs. Do not look for a remote daemon's files on the client device.
+
+- Daemon config: `~/.paseo/config.json`
+- Daemon log: `~/.paseo/daemon.log`
+- Agent state directory: `~/.paseo/agents/`
+- Default managed worktree root: `~/.paseo/worktrees/`
+- macOS desktop log: `~/Library/Logs/Paseo/main.log`
+- Linux desktop log: `~/.config/Paseo/logs/main.log`
+- Windows desktop log: `%APPDATA%\Paseo\logs\main.log`
+
+Substitute the status-reported `PASEO_HOME` for `~/.paseo`. In the official Docker image, the default is `/home/paseo/.paseo`; its host path depends on the volume mount, and container stdout is available through Docker. Desktop app logs describe the Desktop process; daemon logs describe the selected daemon. Read the narrowest useful slice and redact credentials, pairing offers, tokens, passwords, and user code before sharing logs.
+
+If diagnosing the bundled daemon on a computer with Paseo Desktop installed, but `paseo` is not on `PATH`, the bundled CLI is at:
+
+- macOS: `/Applications/Paseo.app/Contents/Resources/bin/paseo`
+- Linux: `<install-dir>/resources/bin/paseo`
+- Windows: `C:\Program Files\Paseo\resources\bin\paseo.cmd`
+
+Offer to fix the PATH or symlink; do not change shell configuration silently.
+
+## Escalate with evidence
+
+If the current docs and diagnostics do not resolve the problem, collect the app and daemon versions, OS, install method, connection method, exact error, minimal reproduction, and a small redacted log excerpt.
+
+- Bugs: [GitHub Issues](https://github.com/getpaseo/paseo/issues)
+- Questions and quick help: [Paseo Discord](https://discord.gg/jz8T2uahpH)
+- Product workflow discussions: [GitHub Discussions](https://github.com/getpaseo/paseo/discussions) or `#product` in Discord