home-hosted 0.7.11 → 0.7.13

package/AGENTS.md

@@ -23,7 +23,9 @@ seed entry, or a path that names one.
 
 ```sh
 pnpm run up|down|restart|status    # detached; `down` asks /_hh/shutdown, signals are the fallback
+                                   # `restart <id>` restarts one server via /_hh, panel stays up
 pnpm run start                     # up --foreground (systemd, docker, a foreground shell)
+pnpm exec tsx src/cli.ts logs      # the panel's own console output (--lines, --follow, --json)
 pnpm dev                           # tsx-watch panel :6000 + the stock UI's Vite :6001 (proxies /api), state in .dev-state/
 pnpm dev --ui noc-console          # the same, for another UI; --port/--ui-port override
 pnpm run build                     # dist/cli.js + the stock UI (uis/stock/dist)
@@ -53,6 +55,19 @@ UI and every UI zip, lets changelogen write the changelog, bump `package.json`,
 trusted publishing (OIDC, no token). npm only offers a trusted publisher for a package that already
 exists, so the first release has to be published by hand.
 
+Four workflows, and the split is deliberate:
+
+| workflow | runs on | what it proves |
+| --- | --- | --- |
+| `quickcheck.yml` / `test.yml` | every push and PR | lint, types, the whole suite with coverage — Linux only |
+| `cross-platform.yml` | the release gate, or by hand | the same suite on macOS and Windows |
+| `release.yml` | dispatched with a version | the platform gate, then tag, publish, release assets |
+
+The platform gate is not a per-push job on purpose: it is the expensive half, and it is what makes a
+platform-specific break fail before shipping rather than on someone's machine. It also runs on a
+`dry-run`, because that is exactly what a rehearsal needs to exercise. Every job carries a
+`timeout-minutes`, so a wedged runner is reported instead of sitting out GitHub's 6-hour default.
+
 ### Which version to dispatch
 
 Below 1.0 the **minor is the breaking channel**: a fix or a non-breaking feature is a **patch**

package/README.md

@@ -340,10 +340,12 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | --- | --- |
 | `home-hosted up` | start the panel detached, and keep it alive in the background |
 | `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
-| `home-hosted restart` | `down`, then `up` |
+| `home-hosted restart` | `down`, then `up` — or `restart <id>` to restart one server, leaving the panel up |
 | `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
 | `home-hosted start <id>` | start one server in the default workspace — and anything it `dependsOn` (`--workspace <id>`) |
 | `home-hosted stop <id>` | stop one server, nothing else (`--workspace <id>`) |
+| `home-hosted restart <id>` | restart one server, nothing else (`--workspace <id>`) — the same as the panel's per-server Restart |
+| `home-hosted logs` | read the panel's own console output — the file `up` redirects it into (`--lines`, `--follow`, `--json`) |
 | `home-hosted set-password` | set the panel password without opening a browser |
 | `home-hosted set-token` | set the API token scripts and agents use (`--generate`, `--clear`) |
 | `home-hosted migrate` | relocate a pre-workspaces state directory and stamp every config for this release (`--dry-run`, `--yes`) |
@@ -358,11 +360,13 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 `home-hosted <command> --help` prints what that command takes.
 
 ```text
-up, restart       -c/--config -p/--port --host --open --no-autostart --foreground --print-config
+up                -c/--config -p/--port --host --open --no-autostart --foreground --print-config
 
 down              (no flags)
 status            --json
+logs              --lines <n> --follow --json
 start, stop       <id> [-w/--workspace <id>]   (both need the panel up)
+restart           [<id>] [-w/--workspace <id>]  (no id: the panel; with one: that server)
 init              --dir --name --pm --no-install -y/--yes
 set-password      --clear
 set-token         --generate --clear
@@ -375,7 +379,8 @@ every command     --home <dir> --project <dir>       (or $HHOSTED_HOME, $HHOSTED
 env vars          HHOSTED_PASSWORD, HHOSTED_MIGRATE=allow, HHOSTED_TOKEN, GITHUB_TOKEN or GH_TOKEN
 ```
 
-`up` and `restart` share the same flags: `restart` is `down`, then `up` with exactly what it was given.
+`up` and `restart` share the same flags: bare `restart` is `down`, then `up` with exactly what it was
+given. Given a server id — `restart web` — it restarts only that entry, and the panel keeps running.
 `-c/--config` is the **default workspace's** servers file (`<state>/.hh/default/servers.config.json`),
 for a launcher that pins one; a workspace picked in the UI keeps its own. `start`/`stop` omit
 `--workspace` to act in the panel's default workspace.
@@ -507,6 +512,24 @@ specific:
 
 ## ❓ FAQ
 
+<details>
+<summary><b>The panel is up but something is wrong — where do I look?</b></summary>
+
+`home-hosted logs` prints the panel's own console output, which is where it reports what it is
+doing and anything it could not finish:
+
+```bash
+home-hosted logs              # the last 50 lines
+home-hosted logs --follow     # keep printing, like tail -f
+home-hosted logs --lines all  # the whole thing, including the rotation
+```
+
+It is the same file `status` names, and reading it needs no session or API token — a panel that
+is answering badly is exactly when you cannot get one. `up` prints the tail automatically when
+the panel fails to start.
+
+</details>
+
 <details>
 <summary><b>Is it a systemd replacement?</b></summary>