@kybernesis/create 0.6.0 → 0.7.1

package/skills/fde-engagement/references/playbook.md

@@ -1873,6 +1873,45 @@ client with an existing ChatGPT or Claude subscription pays no incremental
 inference cost for the pilot. Say the number out loud in the discovery
 conversation — it changes the shape of the deal.
 
+**Grok, on a SuperGrok or X Premium+ subscription.** Same arrangement, without
+the broker: xAI's Grok Build CLI does a device login and writes a credential
+that is a valid bearer for `https://api.x.ai/v1`. Proven in production on Sid —
+twelve evals, twenty-nine gates, green on the subscription.
+
+```bash
+# on the host, as the unix user the agent runs as
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login                              # device flow → ~/.grok/auth.json
+```
+
+```ts title="agent/agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { grokSubscription } from "@kybernesis/exe";
+
+export default defineAgent({
+  model: grokSubscription({ model: "grok-4.6", createOpenAI }),
+  modelContextWindowTokens: 400_000,
+});
+```
+
+Three things to know before you promise it to a client:
+
+- The credential is **per-machine and per-user**. It lives in a home directory.
+  A different unix user cannot see it; a new host needs its own login.
+- It **expires in six hours** and the CLI refreshes it in place, so the agent
+  must re-read the file per request. `grokSubscription` does this in a `fetch`
+  wrapper. (Do not reach for a Proxy around the model object — the AI SDK's
+  methods depend on their own `this` and every call dies inside the SDK.)
+- **Unattended refresh over days is unverified.** If nobody runs `grok` on that
+  host for a week, it is an open question, and it would present to the client as
+  the agent breaking for no reason.
+
+**The model will lie about which model it is.** Sid, running Grok, stated it was
+"Claude Opus 4.6, Anthropic" and attributed it to an instruction that exists
+nowhere in its context. Verify from the host — the configured model id and the
+credential in use — never by asking the agent. Expect a client to ask it in a
+demo, and have the real answer ready.
+
 ### 11.5 Third-party APIs: broker the credential, pin the version
 
 Do not put a client's API token on the agent host. Put it in an exe.dev
@@ -1974,6 +2013,48 @@ Also: a long-lived channel session caches the compiled agent. After changing
 capabilities, start a **fresh conversation** before deciding the change did not
 work.
 
+**A restart script must do two more things, and both were learned from a
+stranded user.**
+
+*Serialize restarts.* `@kybernesis/manage` fires one 20s after any change, and
+you will also run one by hand. Two overlapping runs both finish killing before
+either starts, and you end up with **two supervisors and two servers writing to
+one durable store** — two executors racing over the same runs. That is not a
+slow agent, it is a corrupt one. Take a `flock` at the top of the script, and
+assert exactly one server process at the bottom.
+
+*Wait for in-flight turns.* eve does **not** resume a step killed mid-flight.
+Restart into a live turn and that turn never emits another event, the session
+never parks, and every later message queues behind a turn that will never
+finish. The user watches a spinner forever, and no further restart fixes it,
+because the session is stranded rather than stuck. Poll
+`.eve/.workflow-data/runs/*.json` for a `turnWorkflow` in `running` state and
+wait for it to clear — with a cap, so a wedged turn cannot block the restart
+that would clear it.
+
+*And build before you restart.* Proving the process started after the BUILD says
+nothing about whether the build reflects the SOURCE. A production agent ran for a
+day on a build ten hours older than its files, reporting "OK: serving the current
+build" every time. Worse, `@kybernesis/manage` calls the restart script after
+writing files — so **every capability installed from Studio reported success and
+changed nothing.** Build when the source has moved, and refuse to restart into a
+build that failed.
+
+*And measure it correctly.* `pgrep -f 'server/index.mjs'` run over ssh matches
+**the shell running the pgrep** — the pattern is in its own command line — so it
+reports two servers when there is one. An entire investigation went into hunting
+a phantom supervisor that a `ps -eo pid,ppid,args` would have dismissed in
+thirty seconds. Same family as `pkill -f` killing its caller. Inside a script
+file it is safe (the script's command line is `bash restart.sh`); typed at a
+shell or sent over ssh it is not. When a process count surprises you, **list the
+matches before believing the number.**
+
+The escape from an already-stranded session is a **session reset**
+(`ClientSession.reset()`, or Reset in Studio's agent settings), which releases
+the durable owner so the next message starts a fresh conversation. Cancelling
+often does not help: the executor that would honour the cancel is the one that
+died.
+
 ### 11.9 Credential checklist — collect ALL of these from the client
 
 Nothing here can be borrowed from another agent or another account.
@@ -2047,8 +2128,14 @@ manage, since it cannot check a grant for a name it does not know.
    rebuilds, so it works on a VM and refuses on a read-only serverless bundle,
    with that reason. Set `restartCommand` in `agent/channels/kyb.ts` or an
    install completes without taking effect.
-4. **For `local`: the relay secret** (`LOCAL_EXEC_AGENT_SECRET`) matching the
-   control plane.
+4. **For `local`: nothing to configure.** Setup is one switch in Studio — the
+   agent's settings, *Work on this computer*. Behind it, Studio mints the
+   agent's credential from the control plane, installs it over the manage
+   channel, and records a standing grant for that machine; the agent restarts
+   once to load it. Never hand anyone a credential to paste into an env file.
+   The admin UI's "mint agent credential (shown once)" button remains for
+   recovery and is not the path: a setup step that asks someone to carry a
+   secret between two screens gets done wrong or skipped.
 
 ### 12.4 What consent looks like for the user
 
@@ -2065,11 +2152,23 @@ colleague knows "build me a demo" from "look at my repo".
 
 ### 12.5 State this plainly to the client
 
-- **Local execution is not yet a governed capability.** The agent authenticates
-  to the relay with a shared secret, so anyone holding it can reach a connected
-  desktop in that org. It must become its own revocable grant, separate from
-  "may talk to this agent". Do not install `local` at a client who would treat
-  that as a surprise.
+- **Two things gate a laptop, and they fail differently.** *Identity* is the
+  agent's signed credential — "the local-execution relay rejected my
+  credentials" means that. *Consent* is a standing per-device grant — "you have
+  not allowed this agent to work on this computer" means that. Neither alone
+  reaches anything. The grant is permanent on purpose: "always allow" means
+  always, from a chat window, a schedule, or a message sent from a phone, and it
+  ends on revoke, device removal, or disabling the agent.
+- **Reaching a desktop is still not its own revocable capability.** "May talk to
+  this agent" and "may run commands on my laptop" remain one decision, taken
+  when the person allows the machine. Say so at a client who would treat it as a
+  surprise.
+- **Installing the credential restarts the agent**, and a turn in flight during
+  that restart is lost for good — eve does not resume a step killed mid-flight.
+  It reads as a spinner that never resolves, often alongside a "credential is
+  unset" error from the process that was replaced. Send a new message, and reset
+  the conversation if the session itself is stranded. §11.8 is why a restart
+  script must wait for in-flight turns.
 - **Reading a file sends it to the model.** Execution is local; the reasoning is
   not. Fine for most work, and a conversation to have before a Studio points at
   a regulated repository.
@@ -2077,6 +2176,129 @@ colleague knows "build me a demo" from "look at my repo".
   means the repository is no longer only yours. Agree who reviews what Studio
   writes — routines land as source files, so a normal review works.
 
+### 12.7 Connectors — the apps library
+
+The Apps tab in Studio is a shelf of services a person connects in one click:
+Gmail, Calendar, Drive, Slack, Notion, Linear, GitHub, Attio, Outlook, HubSpot.
+Connecting one makes its tools appear in that person's next session.
+
+**Setup is one field, and it belongs to the client.** The org's own Composio key
+goes in their control plane at **Settings → Connectors**, set by an owner, the
+same way SSO is. It is never a deployment env var and never ours: each control
+plane belongs to one company, and nobody's people connect their mailboxes under
+another org's account. Direct them to composio.dev → Settings → API Keys.
+
+**What makes it one click** is that Composio has already registered the OAuth
+app for each service. Without a broker, every client has to create a developer
+app per provider — which is exactly the hour lost to Notion on the first
+deployment, version pin and all.
+
+**Two things on every card, because both are load-bearing:**
+
+*Connects as you* versus *for the company*. A user-scoped connection cannot fire
+from a schedule — a routine at 8am has no signed-in person. Anything a briefing
+depends on must be the company's connection.
+
+*An admin must approve*. True for Slack, Notion, and Google Workspace. Say it on
+the card; a client who discovers it at the end of a redirect chain reads the
+product as broken.
+
+**How tools reach the agent.** `@kybernesis/connectors` mounts a dynamic
+resolver in `agent/tools/connectors.ts`. It resolves per session from the
+principal on the turn, asks the control plane what that person has connected,
+and calls back through it to execute. The agent never holds the broker key — it
+proves which agent it is with its own credential, and the control plane decides
+whose account the call runs against.
+
+Resolution is per session, not per turn: a tool set is part of the prompt, and
+rebuilding it every turn re-ingests the conversation at uncached prices. Pass
+`perTurn: true` where people connect things mid-conversation and expect them to
+work immediately.
+
+**Say this to the client.** Their Composio account holds refresh tokens for
+their Google Workspace and Slack — a fourth party alongside the model provider,
+the host, and us. Most will not blink; a regulated one will, and the answer for
+them is `eve-connect`, native eve connections with no broker. That is why every
+card carries a `provider`.
+
+**And watch the bill.** Composio prices per action. An agent in a loop is a very
+different cost profile from a person clicking, and that belongs in the pricing
+conversation before the first invoice, not after.
+
+### 12.8 MCP servers — the client's own tools, local and remote
+
+The MCP tab is the escape hatch from the shelf: anything with an MCP server
+becomes agent tools, whether it runs on the person's laptop or on a URL.
+
+**Local** — a command Studio runs on that machine (`npx -y @acme/mcp`, with env
+vars if the server needs them). Studio keeps it alive, and the deployed agent
+reaches it through the same relay as local execution. This is how a client's
+internal tooling — the CLI nobody will ever expose to the internet — becomes
+something the agent can use, without opening a port.
+
+**Remote** — a URL and optional headers. Studio runs the handshake before
+saving, so a bad URL fails at the moment someone types it rather than in the
+middle of a demo.
+
+Consent is **per server**, and approving one does not approve the next. The
+discovery call (listing what a server offers) is exempt — otherwise a person is
+asked to approve something before they can see what it is.
+
+The things that cost real sessions here:
+
+- **The command in a vendor's README is often the installer**, not the server.
+  Plaud's documented line runs an `install` subcommand and exits; the stdio
+  server is the bare command. If a server "connects" and never answers, check
+  that you are running the server.
+- **A server declares its arguments and you must honour them.** Studio passes
+  the published `inputSchema` through to the model (`@kybernesis/local` ≥0.5.0).
+  Before that it did not, and watching the result is the best argument for the
+  fix: nine consecutive calls guessing the name of an argument the server had
+  documented, steered only by error strings.
+- **Discovery must have a deadline.** These resolvers run before a turn and
+  reach across a network to a laptop that might be shut. Budgeted at 6s with a
+  five-minute cache; without that, one closed lid makes every turn hang.
+
+### 12.9 Rooms — several agents in one conversation
+
+A client with a planner, a designer, and an engineer agent can put all three in
+one room and work with them the way they would with people. The room lives
+entirely in the desktop app: each member keeps its own session with its own
+deployment, and the app is what puts a message in front of all of them. **No
+agent needs to know the feature exists**, which is what makes it work with an
+agent the client wrote themselves.
+
+**Addressing is the routing, and it is worth teaching in one line.** Name a
+member and only they answer. `@everyone` addresses the room. Name nobody and
+the room's lead answers — the first member — who brings the others in. Matching
+is literal and requires the `@`, because an agent called Design must not be
+summoned by the word "design" in an ordinary sentence.
+
+**Hand-offs are how work moves.** An agent's reply reaches another agent only
+when it names them, and whoever is brought in receives what they missed since
+they last spoke. Without that catch-up a hand-off is incoherent: the engineer is
+asked to "build this" having never seen what "this" is.
+
+Say these plainly to a client, because all three will come up:
+
+- **Every hop is a billed turn** on a deployed agent. A three-agent hand-off
+  chain is three turns, and there is a depth cap so a pair that keeps addressing
+  each other cannot run away.
+- **The convention is a prompt, not a protocol.** Each turn carries a line
+  telling the agent it is in a room and how to hand off. A well-behaved agent
+  follows it; nothing enforces it. A misbehaving one is ignored rather than able
+  to start a cascade — agent-to-agent relay has NO policy fallback, precisely so
+  one reply cannot become a reply from everyone.
+- **A relayed message runs under the human's identity.** When the planner hands
+  to the engineer, the engineer acts with that person's authority on another
+  agent's say-so. Among a client's own agents that is usually what they want.
+  It is still a governance decision, and it should be made rather than
+  discovered.
+
+What NOT to promise: emergent self-organisation. The chain works when someone —
+a person or an agent — explicitly hands off. It is a room where people and
+agents talk, not an autonomous workflow engine.
+
 ## 13. Known gaps — state these plainly, do not sell around them
 
 Being straight about these is a feature. Clients have met vendors who were not.
@@ -2094,9 +2316,12 @@ Being straight about these is a feature. Clients have met vendors who were not.
    requester or a `manage`-grant holder may approve — are the planned governance half in
    `@kybernesis/enterprise`.
 
-3. **Eve Studio sign-in is specced, not built.** Employees who do not live in Slack have
-   no polished desktop door yet; HTTP access is token-by-hand via the device flow. The
-   implementation brief is in [[kybernesis-architecture-and-studio-signin]].
+3. **The desktop door is built** — KYBER Studio, signed and notarized, with device-flow
+   sign-in and in-app updates. What is NOT built is a second consent system talking to
+   the first: the control plane holds the standing per-device grant, Studio holds
+   per-effect permissions in a local file, and revoking in one does not revoke the
+   other. An off-boarding story that says "we revoke access centrally" must be qualified
+   at any client that asks the follow-up question.
 
 4. **Off-boarding SLA equals the token TTL** (1h default) for already-minted sessions.
    Suspension is immediate; revocation is not. Tune `IDENTITY_TOKEN_TTL_SECONDS` to the
@@ -2107,9 +2332,20 @@ Being straight about these is a feature. Clients have met vendors who were not.
    a time per session — simultaneous speakers resolve in arrival order, with mid-turn
    messages folded into the next turn best-effort.
 
-6. **Per-user OAuth into personal SaaS and local-file work (the device bridge) are future
-   builds.** Org service accounts with static tokens cover most pilot asks. Subagents in
-   particular *cannot* use per-user OAuth at all — no user principal.
+6. **Per-user OAuth and local-file work are BUILT** — §12.6 and §12.7, both proven end
+   to end. The remaining edge is the one that bites unattended: anything without a
+   signed-in person (a schedule, a subagent) has no user principal, so a user-scoped
+   connection is not available to it. A morning briefing built on someone's personal
+   Gmail connection does not fail loudly — it quietly has no tools. Company-scoped
+   connections are the answer, and that path has not yet been exercised in production.
+
+   Two more, worth saying because a client will meet them:
+
+   - **Tool volume is unmanaged.** Gmail and Calendar alone are 51 tool definitions in
+     every prompt. Real tokens per turn, and measurably worse tool selection as a client
+     connects more. Curation is designed, not shipped — connect what the pilot needs.
+   - **Local MCP servers are per-machine.** A person's second laptop silently has a
+     different set, and nothing in the UI says which machine a server is on.
 
 7. **DM memory is per-workspace, not per-employee, unless you build it.** Splitting DMs
    into one Arcana workspace per person needs a Slack-user-id → workspace-slug map in the

package/skills/kybernesis-packages/SKILL.md

@@ -1,10 +1,10 @@
 ---
-description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), dispatch (agent-to-agent), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
+description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), dispatch (agent-to-agent), connectors (Gmail/Calendar/remote MCP), local (the user's own machine), manage (Studio→agent), exe (off-Vercel hosting), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
 ---
 
 # The Kybernesis packages
 
-Seven packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
+Eleven packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
 `KybernesisAI/platform`. Registry: `https://registry.kybernesis.ai`
 (`eve registry add @kybernesis=https://registry.kybernesis.ai/r/{name}.json`,
 then `eve add @kybernesis/<item>`). Each covers one axis:
@@ -60,6 +60,28 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   0.2.1 lesson: eve resolves remote URLs at BOOT — url() must degrade
   (env → discovery-if-credentialed → fallbackUrl), never throw on a missing
   credential, or the whole agent (and its evals) fails to boot.
+- **connectors** — the user's SaaS accounts, brokered. `connectorTools()` is a
+  dynamic resolver: at turn start it asks the control plane which services THIS
+  principal has connected and returns those tools. Composio is the broker; the
+  API key is per-org, held in the control plane (never an env var, never a
+  client's key in our account). Tools are named `<toolkit>_<action>`. Also
+  exports `toolInputSchema` (broker JSON Schema → zod) and a minimal MCP client
+  for `mcp-direct` servers that speaks BOTH JSON and text/event-stream.
+- **local** — the user's own machine, through KYBER Studio. `localShellTool`,
+  `localRead/List/Write/Edit/SearchTool`, plus `localMcpTools()` for MCP servers
+  running on that machine, relayed. Every effect is consented in Studio; the
+  agent never holds a shell. `LOCAL_INSTRUCTIONS` explains the arrangement to
+  the model — mount it or the agent will offer to do things it cannot do.
+- **manage** — the other direction: `manageChannel()` lets Studio install
+  capabilities and write schedules onto a running agent, and `routineTools()`
+  turns "every morning at 8, brief me" into a real schedule file. This is how a
+  routine gets created from chat without anyone touching the repo.
+- **exe** — running off Vercel. `exeModel()` for exe.dev's LLM integration,
+  `grokSubscription()` / `readGrokCredential()` for a SuperGrok or X Premium+
+  login (`grok login` → `~/.grok/auth.json`, a valid bearer for api.x.ai —
+  same shape as eve's `experimental_chatgpt()`), `hostPreflight()`, Photon
+  iMessage credentials, and a `/preview` tool. Subpaths: `/slack`, `/photon`,
+  `/sandbox`, `/preview`. See the `self-hosting` skill.
 - **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing,
   engineer? })` = smoke + 5 memory + routing per dept + optional vision-loop
   eval. Judge model ≠ model under test. Hermetic runs force all workspaces to
@@ -91,6 +113,36 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   company-general wording (dept-flavored prompts delegate and hide tool
   calls), no security vocabulary ("canary" triggers refusals), long routing
   timeouts. Do not "clean up" the odd-looking patterns.
+- **A per-turn dynamic resolver needs a deadline.** `connectorTools()` and
+  `localMcpTools()` run before every turn and reach across a network. Without a
+  budget (6s) and a cache (60s connectors, 5min local discovery) one unreachable
+  laptop makes every turn hang — the agent looks broken and nothing in the log
+  says why.
+- **Composio: one request per toolkit.** Repeating `toolkit_slug` in a single
+  `/api/v3/tools` call returns an EMPTY list, so connecting a second service
+  silently emptied the first. The logo is at `meta.logo`, not `logo`. A 200 can
+  still carry `successful: false` — check the body, not the status.
+- **The broker's entity is the agent's REGISTERED name**, not its UUID.
+  `<agent>:<userId>`. Studio knows agents by id; normalize before you ask the
+  broker, or a connected account looks unconnected.
+- **MCP requires the handshake.** `initialize` AND `notifications/initialized`
+  before `tools/list`, or the server never answers. Spawn through a LOGIN shell
+  (a bare spawn misses the user's PATH and node) and always bind
+  `child.on("error")` — without it a failed spawn is an unhandled rejection
+  that takes the process, not a error message.
+- **Translate the MCP/broker inputSchema — never pass an open object.** A tool
+  with no declared arguments makes the model guess: nine calls to find a
+  `file_id` the server had documented all along. `mcpInputSchema` (local) and
+  `toolInputSchema` (connectors) do this; keep them permissive where the server
+  says nothing.
+- **Never wrap a model object in a Proxy.** The AI SDK's model methods depend on
+  their own `this`; intercepting them detaches it and every call dies inside the
+  SDK on a missing internal. To swap a credential, wrap `fetch` instead — and
+  re-read the credential per request: a Grok login expires in six hours and the
+  CLI refreshes it in place.
+- **Credentials are never a user's problem.** No client ever puts a key in a
+  `.env` — broker keys live per-org in the control plane, encrypted at rest, set
+  through an admin screen. A design that ends in "paste this token" is wrong.
 - **npm**: only the `kybernesis` account creates new packages in the scope;
   publishes need the human's browser auth; new versions take 1–3 min to
   propagate to anonymous reads.

package/skills/self-hosting/SKILL.md

@@ -25,7 +25,7 @@ kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer
 
 | Capability | On Vercel | Self-hosted replacement |
 | --- | --- | --- |
-| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT subscription** |
+| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT / Grok subscription** |
 | Slack/Photon/Linear credentials | Vercel Connect | **Portable/static credentials the client issues** |
 | Sandbox | `vercel()` hosted | `docker()` on the host |
 | File delivery | Vercel Blob | Blob **or** `DELIVER_DIR` + `DELIVER_BASE_URL` |
@@ -38,6 +38,44 @@ Vercel MCP connection, Linear, everything. Each becomes a static credential
 someone must issue and rotate. `kyb doctor` fails loudly if a `@vercel/connect`
 import survives into a self-hosted agent.
 
+## Running on the client's own subscription
+
+A client who already pays for ChatGPT Plus/Pro or SuperGrok / X Premium+ can
+run the agent on it instead of on metered API billing. Both work the same way:
+a CLI performs a device login on the host, writes a credential to the home
+directory, and that credential is a valid bearer for an OpenAI-compatible
+endpoint. eve ships `experimental_chatgpt()` for the first;
+`@kybernesis/exe` ships `grokSubscription()` for the second.
+
+```bash
+# on the host, as the user the agent runs as
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login          # device flow → ~/.grok/auth.json
+```
+
+```ts title="agent/agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { grokSubscription } from "@kybernesis/exe";
+
+export default defineAgent({
+  model: grokSubscription({ model: "grok-4.6", createOpenAI }),
+  modelContextWindowTokens: 400_000,
+});
+```
+
+What this arrangement costs you, and it is worth saying to the client:
+
+- **It is per-machine and per-user.** The login belongs to the host's home
+  directory. Moving the agent means logging in again; running it as a different
+  unix user means it cannot see the credential at all.
+- **The token expires in hours** (Grok: six) and the CLI refreshes it in place.
+  Read it per request, never once at boot, or the agent works all afternoon and
+  starts failing authentication at dinner for no reason a user can see.
+- **Nobody has proven unattended refresh over days.** If no one runs `grok` on
+  that host, whether the refresh keeps happening is an open question — and it
+  presents as the agent "breaking".
+- **Ask the vendor's terms question before a client demo**, not after.
+
 ## The failure modes, each of which cost a real session
 
 - **Docker ships disabled on some images.** exe.dev's exeuntu runs
@@ -144,3 +182,25 @@ yesterday's agent. Assert the process started AFTER the build it should serve
 (`scripts/eve-server.sh` and the restart pattern in `@kybernesis/exe` do this).
 Related: a long-lived channel session caches the compiled agent, so start a
 fresh conversation after changing capabilities.
+
+A restart script also has to **serialize** (`flock`, released by the child with
+`9>&-`) and **wait for in-flight turns** — eve does not resume a step killed
+mid-flight, and restarting into a live turn strands the session behind a turn
+that will never finish.
+
+Run restarts **detached** from your ssh connection —
+`setsid nohup bash restart.sh >/tmp/r.log 2>&1 </dev/null &` — or a dropped
+connection SIGHUPs the script halfway through and leaves exactly the mess it
+exists to prevent.
+
+**Build before you restart.** Proving the process started after the build says
+nothing about whether the build reflects the source — an agent served a build ten
+hours older than its files while reporting success. It also breaks installs:
+`@kybernesis/manage` writes files and then calls the restart script.
+
+**And measure it correctly.** `pgrep -f 'server/index.mjs'` typed over ssh
+matches the shell running it: the pattern is in that shell's own command line,
+so it reports two servers when there is one. A whole investigation went into a
+phantom "second server" that `ps -eo pid,ppid,args` would have dismissed
+immediately. Inside a script file it is safe; typed at a shell it is not. List
+the matches before you believe the count.