@sunshinelife83/hearth 1.0.0

package/docs/gotchas.md

@@ -0,0 +1,294 @@
+# Troubleshooting Gotchas
+
+This page collects the setup issues users are most likely to hit.
+
+## `hearth` Command Not Found
+
+Use `npx`:
+
+```bash
+npx @sunshinelife83/hearth init
+npx @sunshinelife83/hearth serve
+```
+
+If you installed globally, confirm npm's global bin directory is on `PATH`.
+
+## Unsupported Node Version
+
+Hearth requires Node `>=22.19 <27`.
+
+Check:
+
+```bash
+node --version
+```
+
+Install Node 22 LTS with your preferred version manager such as `nvm`, `fnm`, or
+`mise`.
+
+## `better-sqlite3` Could Not Load
+
+This usually means native dependencies were installed under a different Node
+runtime.
+
+Try:
+
+```bash
+npm rebuild better-sqlite3
+```
+
+Then run:
+
+```bash
+npx @sunshinelife83/hearth doctor
+```
+
+Release starts run a native dependency check before launching.
+
+## Public URL Includes `/mcp`
+
+Use the origin for setup:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Use the MCP endpoint in the client:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+If you saved the wrong value:
+
+```bash
+npx @sunshinelife83/hearth config set publicBaseUrl https://your-tunnel-host.example.com
+```
+
+## Reverse Proxy `/mcp` Returns 404
+Proxy the whole Hearth server from the root of your tunnel or reverse proxy.
+
+Do not mount only `/mcp`: some proxies strip a configured mount path before
+proxying to the local service, so a public `/mcp` request can otherwise arrive
+at Hearth as `/`. Hearth also needs OAuth routes outside `/mcp`, so serving
+the whole local origin is the correct setup.
+
+## Tunnel URL Changed
+
+Temporary tunnels often change URLs between runs.
+
+Update the configured URL:
+
+```bash
+npx @sunshinelife83/hearth config set publicBaseUrl https://new-tunnel.example.com
+```
+
+For a stable URL:
+
+```bash
+npx @sunshinelife83/hearth config set publicBaseUrl https://hearth.example.com
+```
+
+## Host Header Or 403 Problems
+
+Hearth derives allowed hosts from the configured public URL.
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth doctor
+```
+
+Confirm the public URL hostname appears in allowed hosts. If you changed tunnel
+URLs, update `publicBaseUrl`.
+
+For intentional local debugging only, set `server.allowedHosts` to `["*"]` in
+`~/.hearth/config.jsonc`.
+
+## OAuth Redirect Host Rejected
+
+By default, Hearth allows redirects for:
+
+```text
+chatgpt.com (and subdomains)
+claude.ai (and subdomains)
+anthropic.com (and subdomains)
+localhost
+127.0.0.1
+```
+
+If another MCP client uses a different redirect host, add it to
+`oauth.allowedRedirectHosts` in `~/.hearth/config.jsonc`. Subdomains of a
+listed host are accepted automatically.
+
+## Owner Password Not Accepted
+
+Make sure you are entering the Owner password from:
+
+```text
+~/.hearth/auth.json
+```
+
+To regenerate setup:
+
+```bash
+npx @sunshinelife83/hearth init --force
+  (`--force` now rotates the Owner password and prints the new value in ChatGPT setups; existing access tokens stay valid until they expire — revoke them via the OAuth revocation endpoint if needed)
+```
+
+## Unknown `workspaceId`
+
+`workspaceId` values are session identifiers. If the server restarts and the
+client receives an unknown workspace error, call `open_workspace` again for that
+project.
+
+Workspace session metadata is persisted. ChatGPT may provide optional
+conversation metadata that lets Hearth resume the same checkout workspace for
+the same project in that conversation; repeated opens reuse the `workspaceId`
+and do not repeat context already provided for that reused checkout. Worktree
+mode always creates a new isolated workspace with its own complete context.
+Hosts without supported conversation metadata receive a normal new workspace.
+In all cases, continue passing the `workspaceId` returned by `open_workspace` to
+later tools. Other MCP hosts use this explicit workspace workflow as well.
+
+To review work, call `show_changes` once after the final related file change. It
+shows the combined changes and advances the review point automatically.
+
+## Data Retention
+
+Hearth does not currently prune workspace sessions, conversation bindings,
+or review refs. A future product retention policy will define safe cleanup for
+these records; no automatic deletion is performed today.
+
+## MCP Workspace Path Rejected
+
+The path passed to `open_workspace` must be inside one of the allowed roots
+configured during ChatGPT setup. Direct `hearth agents` commands instead use
+the current local project and are not gated by MCP allowed roots.
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth config get
+```
+
+Then either open a project under an allowed root or rerun setup:
+
+```bash
+npx @sunshinelife83/hearth init --force
+```
+
+## Worktree Mode Fails
+
+Worktree mode requires:
+
+- Git installed
+- the path is inside a Git repository
+- the repository has at least one commit
+- the requested `baseRef` resolves to a commit
+
+For a new repository, create the first commit or use checkout mode.
+
+Uncommitted source checkout changes are not copied into the managed worktree.
+Commit, stash, or ask the model to work in checkout mode if those changes are
+needed.
+
+## Windows Shell Commands Fail
+
+Hearth shell execution requires Bash. Native PowerShell and `cmd.exe` command
+execution are not supported yet.
+
+Install Git for Windows and use Git Bash, or use WSL, MSYS2, or Cygwin Bash.
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth doctor
+```
+
+Confirm Bash is detected.
+
+## Skills Do Not Appear
+
+Skills are enabled by default. Confirm `skills.enabled` is `true` in
+`~/.hearth/config.jsonc`.
+
+Hearth looks in standard Agent Skills locations:
+
+- `~/.agents/skills`
+- project `.agents/skills`
+- `~/.hearth/skills`
+
+It also checks compatibility and custom paths:
+
+- the bundled `subagents` skill when Subagents are enabled, unless `~/.hearth/skills/subagents/SKILL.md` exists
+- `skills.agentDir/skills`, defaulting to `~/.codex/skills`
+- additional paths from `skills.paths`
+
+When Subagents are enabled, Hearth loads agent profiles from
+`~/.hearth/agents/*.md` and project `.hearth/agents/*.md`, then exposes a
+compact profile catalog through `open_workspace`. The bundled
+`subagents` skill keeps the model-facing workflow to
+`hearth agents targets`, `hearth agents ls`, `hearth agents run`,
+`hearth agents continue`, and `hearth agents show`.
+Those commands automatically manage the internal local agent daemon; `hearth
+serve` is not a prerequisite.
+`hearth agents ls` lists existing subagent sessions, not profile
+definitions.
+
+For a Coding Agent, run the installation command printed by
+`hearth init`:
+
+```bash
+npx skills add Waishnav/hearth --skill subagents --global
+```
+
+The Skills CLI handles agent discovery and installation. Hearth setup does
+not copy files into agent skill directories.
+
+Packaged agent profile examples under `examples/agents/` are starter templates.
+Copy or adapt them into one of the active profile directories before use.
+
+Legacy project paths such as `.pi/skills` can be added to `skills.paths` when needed.
+
+If a skill appears in `open_workspace`, the model should read that skill's
+`SKILL.md` before following it. Hearth permits reads within advertised skill
+directories without tracking whether `SKILL.md` was read first.
+
+## Review Card Does Not Appear
+
+Hearth attaches widget UI only to `open_workspace` and `show_changes`.
+Ordinary reads, edits, and commands intentionally render as normal tool results
+to avoid one iframe per call. Plain MCP clients may ignore ChatGPT Apps widget
+metadata and only show text results; `show_changes` remains available there.
+
+If both cards are missing in ChatGPT, confirm that `ui.enabled` is not `false`
+in `~/.hearth/config.jsonc` and reconnect the MCP server.
+
+Historical `show_changes` cards use the `reviewRef` in their structured result
+to recover the exact Git-backed review when a host reloads the app without its
+original result metadata. `open_workspace` can rebuild its card directly from
+its structured result.
+
+## OpenCode Backend Fails With "Unexpected Server Error"
+
+If every opencode turn fails with `PROVIDER_EXECUTION_ERROR: ... Unexpected
+server error` while `opencode run` in a terminal works, the opencode server's
+local database (`~/.local/share/opencode/opencode.db`) is in a broken state:
+sessions created through the API land outside the table that message inserts
+reference, so every prompt and agent-switch is rejected. Hearth cannot repair
+another program's database.
+
+Confirm it without touching your data:
+
+```bash
+mkdir -p /tmp/oc-fresh-data && XDG_DATA_HOME=/tmp/oc-fresh-data opencode serve --hostname=127.0.0.1 --port=18927 &
+# dispatch one opencode turn through Hearth with XDG_DATA_HOME set for the daemon,
+# or simply: if a fresh data dir works, the old database is the cause.
+```
+
+Remedies: back up then reset the opencode database (you lose TUI session
+history), or use the `codex` backend, which is unaffected. Hearth-side, every
+opencode runtime now gets its own server port (no shared-4096 collisions),
+redundant agent switches are skipped, and provider failures carry the
+underlying cause text instead of a bare "execution failed".

package/docs/local-agent-daemon.md

@@ -0,0 +1,101 @@
+# Local agent daemon
+
+Local agent execution is owned by an on-demand `hearth-agentd` process, not
+by the MCP server and not by an individual CLI invocation. The daemon is an
+internal implementation detail: the normal workflow remains:
+
+```text
+hearth agents run/continue/show/ls
+          │
+          ▼
+    hearth-agentd
+          │
+          ├── LocalAgentManager
+          ├── LocalAgentStore
+          ├── LocalAgentRuntimePool
+          └── provider runtimes
+```
+
+The CLI starts the daemon automatically when an agent command needs it. The
+MCP server can use the same local client when an MCP operation needs agent
+functionality, but `hearth serve` is not required for local-agent execution.
+The daemon is scoped to one Hearth `stateDir`, so one SQLite store and one
+runtime owner serve all clients using that configuration.
+
+Communication uses a private Unix domain socket on Linux/macOS or a named pipe
+on Windows. The endpoint is not exposed through the public MCP HTTP port.
+Provider session identifiers and logical agent records are durable; live
+provider runtimes are disposable and may be recreated after a daemon restart.
+Expected subagent failures cross the daemon boundary as structured error codes,
+not message-string conventions. Agent records in `error` state retain the safe
+message plus `errorCode` and `errorRetryable` fields so callers can distinguish
+provider cancellation, provider availability, workspace conflicts, daemon
+timeouts, and similar recovery categories after a background turn completes.
+Internal provider causes are kept out of the daemon payload and persisted JSON.
+
+The implementation treats `better-result` as the application-failure boundary,
+not as a replacement for every exception. Expected target, scope, provider,
+store, and daemon failures return typed Results. Sequential fallible setup uses
+`Result.gen` when it makes the success path clearer, small Result-to-Result
+transformations use `map`/`andThen`, and error policy at serialization or IPC
+boundaries uses exhaustive tagged-error matching. Programmer defects and broken
+invariants remain exceptions; cleanup and shutdown also stay best-effort so a
+secondary release failure cannot replace the primary agent failure.
+
+The daemon state directory contains the socket or pipe identity, an atomic
+lock, a PID marker, and diagnostic logs. A second client cannot start another
+daemon for the same state directory. Stale lock and socket files are recovered
+only after the recorded PID is no longer alive.
+
+The daemon is started on demand and may exit after its active turns, clients,
+and warm runtime idle periods have ended. Users do not need to manage it during
+normal operation. Diagnostic commands are available for startup, process, and
+cleanup problems:
+
+```bash
+hearth agents daemon status
+hearth agents daemon stop
+hearth agents daemon logs
+```
+
+Agent commands accept `--json` when a machine-readable response is needed.
+They emit one compact JSON value. `run` and `continue` return only the logical
+agent ID and status, `ls` returns session summaries, and `show` returns the
+response or structured failure for one agent. Internal workspace paths,
+provider session IDs, timestamps, and prior responses are not included in list
+or receipt output. Immediate failures are emitted as
+`{ error: { code, message, retryable, ... } }` with a non-zero exit code.
+Successful `daemon status` and `daemon stop` output the daemon status object,
+and successful `daemon logs` output is `{ "logs": "<text>" }`.
+
+Agent identity is explicit at the client boundary. `agents run` starts a new
+logical agent from a profile or provider; `agents continue <id>` continues an
+existing logical agent. Provider session IDs are never accepted as logical
+agent IDs, and the daemon does not resolve ambiguous prefixes.
+
+Shutdown gives active turns a bounded graceful window. If that window expires,
+the process exits with active records left durable; the next daemon startup
+reconciles stale `starting` and `running` records to `error` without discarding
+their `providerSessionId` or `latestResponse`.
+
+## Hearth additions (protocol v4)
+
+The daemon protocol moved to version 4 with full agent lifecycle methods,
+exposed to MCP clients through the `agent_*` tools:
+
+| Method | Purpose |
+|---|---|
+| `agent.pause` `{ id, scope, force? }` | Pause an agent. Instant between turns; with `force` the running turn is interrupted by closing its runtime. Status becomes `paused`. |
+| `agent.resume` `{ id, scope, prompt?, overrides? }` | Start a new turn on the durable provider session from `paused` (also `idle`/`error`). |
+| `agent.stop` `{ id, scope, force? }` | Stop an agent; `force` interrupts a running turn. Terminal status `stopped`. |
+| `agent.cancel` (client-side) | `stop` with `force: true`. |
+
+`agent.get` responses now include `latestOutput` — the bounded tail (64 KB) of
+the in-flight turn's incremental assistant output, streamed from providers
+that support it (ACP agents, Codex, Claude). Pi and OpenCode report output
+only when the turn completes (provider limitation, documented in
+docs/adr/hearth-x-implementation-adrs.md, ADR-017).
+
+Cancellation closes the agent's runtime immediately (`agent_cancelled` close
+reason); a turn that completes successfully after a stop/pause request never
+restores `idle` — the requested terminal status wins.

package/docs/security.md

@@ -0,0 +1,197 @@
+# Security Model
+
+Hearth exposes local coding capabilities over MCP. Treat it as remote access
+to your development machine.
+
+The security model is simple:
+
+- you choose a narrow filesystem allowlist
+- the MCP endpoint requires OAuth approval with your Owner password
+- Host headers are allowlisted from the configured public URL
+- every coding action happens through explicit MCP tool calls
+
+## Filesystem Allowlist
+
+Hearth only opens workspaces under configured roots.
+
+Good examples:
+
+```text
+~/work
+~/personal/open-source
+```
+
+Avoid broad roots:
+
+```text
+~
+/
+C:\
+```
+
+The narrower the root, the easier it is to reason about what the MCP client can
+reach.
+
+## Owner Password
+
+`hearth init` generates an Owner password and stores it in:
+
+```text
+~/.hearth/auth.json
+```
+
+When an MCP client connects, Hearth shows an approval page. Enter the Owner
+password only when you intentionally want that client to access this server.
+
+For env-driven deployments, set a long random value:
+
+```bash
+HEARTH_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)"
+```
+
+## Public URL And Host Allowlist
+
+Hearth needs `server.publicBaseUrl` in `config.jsonc` so MCP clients can
+discover OAuth metadata and connect to the correct resource.
+
+The value should be the origin only:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Do not include `/mcp` in `server.publicBaseUrl`.
+
+By default, Hearth derives allowed Host headers from the local host and public
+URL. Put `"*"` in `server.allowedHosts` only for intentional local debugging.
+
+## Machine Identity Is Diagnostic, Not A Security Boundary
+
+`hearth id` prints a stable random label (`hearth-xxxx`) stored in the state
+directory (`machine.json`). It helps the owner recognize which PC a banner,
+dashboard, approval page, `/healthz` response, or log line came from.
+
+It does not authenticate the machine: copying the state directory copies the
+identity, so it cannot prove which physical PC answered, cannot prevent URL
+reuse across PCs, and cannot stop cloning. Keep one public URL per PC as
+operational hygiene, and rely on the Owner password plus OAuth tokens — not
+the label — for access decisions.
+
+Future direction: a per-device keypair whose private key never leaves the PC
+(`0600` in the state directory) and whose public fingerprint is shown in
+`hearth id`, `/healthz`, the dashboard, and approvals, so audit entries can
+bind to an unclonable key.
+
+## Tunnels
+
+Hearth does not manage tunnels. Your tunnel or reverse proxy should point to:
+
+```text
+http://127.0.0.1:7176
+```
+
+Prefer adding an identity-aware proxy in front of public tunnels. Hearth
+OAuth still protects the MCP endpoint, but the tunnel URL should not be
+treated as a secret.
+
+## Shell Access
+
+The shell tool is powerful by design. It is meant for tests, builds, git, and
+package scripts.
+
+Filesystem path containment applies to Hearth file tools. Shell commands run
+as local commands and can do what your user account can do. This is why the MCP
+client must be trusted and the Owner password must stay private.
+
+## Worktrees
+
+Managed worktrees reduce accidental edits to your active checkout, but they are
+not a security boundary. They are a workflow boundary for isolated coding
+sessions.
+
+## Native File Download
+
+Native file download is an opt-in, one-shot transfer into an already-open
+workspace. `download_artifact` accepts the MCP host's native file value, the
+`workspaceId` returned by `open_workspace`, and an unused relative destination
+path. It returns only the workspace-relative path and does not create a
+persistent artifact service or reusable artifact ID.
+
+Hearth accepts only the documented native-file object and trusted OpenAI
+download hosts and redirects. Arbitrary URL strings, local source paths,
+credentials, malformed references, and unknown object fields are rejected.
+
+Absolute paths, traversal, symlinked parents, and existing destinations also
+fail closed. Downloads stream under the configured per-file limit and are
+published without overwrite as owner-only files. Hearth does not extract or
+execute transferred content.
+
+## Logs
+
+By default, Hearth logs requests and tool calls. Shell command previews are
+disabled unless `logging.shellCommands` is `true`.
+
+Do not enable shell command logging if commands may contain secrets.
+
+Artifact tool logs contain bounded workspace ID, validated hostname,
+workspace-relative output path, byte count, hash, duration, and status metadata.
+`download_artifact` does not log the opaque file value. Raw content, connector
+references, native file IDs, bearer credentials, presigned URLs, host paths,
+temporary paths, and base64 chunks are never included in tool logs or tool
+results.
+
+## Command policy and environment filtering (Hearth)
+Model-invoked shell tools (`exec_command`, `bash`) pass through a policy gate
+before any process spawns:
+
+- **Tier 0** — inspection (`git status`, `ls`, `grep`, ...): allowed in every mode.
+- **Tier 1** — ordinary workspace work (builds, tests, local edits): allowed above readonly.
+- **Tier 2** — outside-effect commands (network fetches, package installs, recursive
+  deletes, `git push`, permission changes, cloud CLIs): denied in readonly, require an
+  explicit `approvedByUser` claim in `supervised` mode (after the user approves in the
+  conversation; the claim is audited), and run freely in `autonomous` mode after a
+  best-effort git snapshot.
+- **Tier 3** — always blocked with no approval path: privilege escalation (`sudo`, `su`),
+  system/power management, service managers, cron, piping remote scripts into a shell,
+  SSH remote execution, and shell-profile tampering.
+
+Set the mode with `execution.mode` in `config.jsonc` (`readonly`, `supervised` — the
+default — or `autonomous`). Every decision is logged as a `policy_decision` event.
+
+Commands executed by model-invoked shell tools inherit a conservative environment
+allowlist instead of the full user environment, so model-run commands cannot read
+API keys or cloud credentials from the environment (escape hatches:
+`execution.envAllowAll`, `execution.envAllowlist`). Provider CLIs started by the
+subagent layer keep the full environment by design and are constrained by the
+allowed-roots enforcement described in
+docs/adr/hearth-x-implementation-adrs.md (ADR-014/015).
+
+Workspace snapshots (`create_snapshot`, `list_snapshots`, `rollback_snapshot`) capture
+the working tree as git refs under `refs/hearth/snapshots/...`; rollback restores
+content without touching HEAD and is subject to the same tier-2 policy.
+
+The OAuth consent page is CSRF-protected (HMAC bound to the authorization request,
+`frame-ancestors 'none'`), and the auth endpoints are rate limited (`/authorize`,
+`/register`, `/token`, plus a dedicated failure counter for the owner password).
+Enable `server.trustProxy` when running behind a tunnel so rate-limit keys use the
+real client IP.
+
+## OS sandbox (platform honesty)
+
+Autonomous shell execution and verification gates are wrapped in an OS sandbox
+when an adapter is available. The sandbox is a hardening layer on top of the
+policy engine, never the only boundary.
+
+| Platform | Adapter | What it actually provides |
+|---|---|---|
+| Linux | bubblewrap (`bwrap`) | Read-only root bind, workspace + `/tmp` writable, optional `--unshare-net`. Real filesystem containment. |
+| macOS | `sandbox-exec` (seatbelt) | Profile denying writes outside the workspace and temp dirs. Approximate; not a strict container. |
+| Windows | none | No equivalent exists here. Containers are the recommended hardening path. |
+
+Fail-closed default: `execution.requireSandboxForAutonomous` defaults to
+`true`, so autonomous tier-2 commands are **denied** (with instructions) when
+no adapter is available — notably on Windows — instead of running silently
+unsandboxed. Opt out explicitly (`execution.requireSandboxForAutonomous:
+false`, globally or per workspace profile) only when you accept unsandboxed
+autonomy. Per-workspace `sandbox: "auto" | "none"` and `sandboxNetwork:
+"allow" | "deny"` override the global setting for one workspace only.