Update Docs

kernel/share/agent-workspace/README-agent.md

@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
 3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
 4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
 
-Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd; stock **`bare-www-*`** pairs with **`bare-os-www`** on **`~/.www`**), and **`hdms`** (Hyperdrive mounts and invite/pair).
+Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (managed **`state.json`**, **`seed`**/**`key`**, stock **`bare-www-*`** / **`bare-ssh-*`**), and **`hdms`** (Hyperdrive mounts and invite/pair).
 
 After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
 

kernel/share/agent-workspace/skills/bare-os-super-developer/SKILL.md

@@ -33,7 +33,7 @@ Think in layers the stock OS already uses:
 
 | Layer | Mechanism | Notes |
 | --- | --- | --- |
-| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG (stock example: **`bare-os-www`** before **`bare-holesail`** for **`bare-www-*`** tunnels); pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
+| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG (stock: **`bare-os-www`** before **`bare-holesail`** so **`bare-www-*`** reaches loopback HTTP; **`bare-openssh`** + login stack ensure **`bare-ssh-*`** in **`~/.holesail/state.json`**); pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
 | **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
 | **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
 | **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |

kernel/share/agent-workspace/skills/holesail/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: bare-os-holesail
 version: 1.0.0
-description: Holesail P2P tunnels in Bare OS — managed state, initd unit bare-holesail, env toggles, and ctx.bare.holesail for /bin scripts.
+description: Holesail P2P tunnels in Bare OS — managed state (seed/key), initd bare-holesail, stock bare-www-* and bare-ssh-* rows, env toggles, ctx.bare.holesail for /bin scripts.
 tags: [holesail, p2p, tunnel, initd, bare-modules]
 requires: [read_man_page, read_file, read_proc_file]
 ---
@@ -10,23 +10,31 @@ requires: [read_man_page, read_file, read_proc_file]
 
 ## When to use
 
-Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail`** CLI, **`bare-holesail`** initd, **`BARE_OS_HOLESAIL_*`** environment variables, **`ctx.bare.holesail`** from drive bundles, or licensing (**upstream `holesail` is AGPL-3.0**).
+Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail`** CLI, **`bare-holesail`** initd, **`BARE_OS_HOLESAIL_*`** environment variables, **`ctx.bare.holesail`** from drive bundles, **`~/.holesail/state.json`** persistence (**`seed`** / **`key`**), or licensing (**upstream `holesail` is AGPL-3.0**).
 
 ## Mental model
 
-1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
+1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance), **`bare-holesail-managed.js`** ( **`state.json`** rows, **`ensure`**, **`SyncPersistedServerKey`** ), **`holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**), **`bare-os-www-holesail.js`**, **`bare-os-ssh-holesail.js`**.
 2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
 3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
-4. **`bare-os-www`** (**`packages/bare-os-booter/lib/bare-os-www-initd.js`**) serves **`~/.www`** on **`127.0.0.1:8088`** by default. **`bare-holesail`** starts **after** it in the initd DAG so the stock managed entry **`bare-www-<port>`** (**`server: true`**, **`host: 127.0.0.1`**, **`port`** from **`BARE_OS_WWW_PORT`**) can reach the HTTP listener. Opt out of auto-merge with **`BARE_OS_WWW_HOLESAIL=0`**. Handbook: **`handbook/04-the-booter-runtime.md`** § **bare-os-www** and § **bare-holesail**.
+4. **Stock auto-rows** — **`bare-www-<port>`** after **`bare-os-www`** listens (**`BARE_OS_WWW_HOLESAIL=0`** disables merge). **`bare-ssh-<port>`** after **`bare-openssh`** listens (**`BARE_OS_SSH_HOLESAIL=0`** disables). **`bare-user-session-stack`** re-ensures SSH tunnel after **`bare-holesail`** starts if sshd was already listening.
+
+## Managed state (`state.json`)
+
+- **Default path** — **`BARE_OS_HOLESAIL_STATE`** unset → **`~/.holesail/state.json`** (logical, under **`$HOME`**). Override env for a different logical path.
+- **Legacy merge** — If the primary file is empty/missing: **`/.bare/holesail/state.json`**, **`/.bare/holesail/guest/state.json`**, **`/home/guest/.holesail/state.json`** are merged once.
+- **`seed`** — Stable ctor secret: **64-char hex**, or valid **z32** suffix (migrated from legacy **`hs://…`**-only rows). Never replace **`seed`** with only the URL suffix written as ctor input.
+- **`key`** — Full shareable **`hs://…`** URL; written/updated after **`ready()`** (**`bareHolesailManagedSyncPersistedServerKey`**). **`holesail list`** shows live URL when tunnel runs.
+- **Daemon** — First **`startManagedConnectionsFromDisk`** pass starts all rows; **yield** one tick; **second pass** uses **`onlyNew`** so **`bare-os-www`** / **`bare-openssh`** can append rows without tearing down tunnels already started.
 
 ## Managed vs single-tunnel mode
 
-- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Persisted tunnel list in **`BARE_OS_HOLESAIL_STATE`** (default **`/.bare/holesail/state.json`** — personal drive root, **shared** guest ↔ unlocked; not per-**`$HOME`** **`~/.holesail`**). On unit start, each **enabled** entry gets its own **`holesail`** instance. **Server** rows without **`key`** receive the minted **`hs://…`** string in **`state.json`** after **`ready()`** (**`bare-holesail-managed.js`**). Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, plus **`path`** (prints resolved state path) and **`help`**.
-- **Single tunnel** — Set **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, and in client mode **`BARE_OS_HOLESAIL_KEY=…`**. Optional: **`BARE_OS_HOLESAIL_SECURE`**, **`PORT`**, **`HOST`**, **`UDP`**, **`LOG`**.
+- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, **`path`**, **`help`**.
+- **Single tunnel** — **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, and in client mode **`BARE_OS_HOLESAIL_KEY=…`**. Optional: **`BARE_OS_HOLESAIL_SECURE`**, **`PORT`**, **`HOST`**, **`UDP`**, **`LOG`**.
 
 ## Early booter (“kernel-path”) instance
 
-Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror env vars (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume with other subsystems.
+Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror env vars. Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume.
 
 ## Operator CLI quick reference
 
@@ -35,13 +43,13 @@ From **`holesail-cli.js`** help text:
 - **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
 - **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
 
-Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
+Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`**.
 
 ## Debugging and safety
 
 - **`BARE_OS_HOLESAIL_DEBUG=1`** — extra console lines (**URLs only**; keys are not logged in full).
 - Do **not** paste full connection secrets into chat or commit logs; redact **`hs://`** payloads when summarizing.
-- **`read_man_page holesail`** (after a coreutils/man build) for in-image synopsis; **`handbook/04-the-booter-runtime.md`** § **bare-holesail** is the prose source of truth for this repo.
+- **`read_man_page holesail`** (after a coreutils/man build); **`handbook/04-the-booter-runtime.md`** § **bare-holesail**, § **bare-os-www**, § **bare-openssh** — prose source of truth.
 
 ## Execution steps (for the agent)