mobile-agent-orchestrator 0.0.1 → 0.2.0

package/lib/prompt.mjs

@@ -0,0 +1,250 @@
+import { resolveUniqueDestinations, targets as writableTargets } from "./hosts.mjs";
+
+/**
+ * Skill directory name written under each destination. Kept in sync with `SKILL_DIRECTORY` in
+ * lib/hosts.mjs (not exported there).
+ */
+const SKILL_DIRECTORY = "mobile-agent-orchestrator";
+
+/** Exact install suggestion rendered for Pi, which is detect-only and never a write target. */
+const PI_INSTALL_COMMAND = "pi install npm:mobile-agent-orchestrator";
+
+/** Destination hints shown next to the scope choices. */
+const SCOPE_HINTS = {
+  user: "~/.agents/skills and ~/.claude/skills",
+  project: "<cwd>/.agents/skills and <cwd>/.claude/skills",
+};
+
+/**
+ * Default destination renderer: groups via the real dedup logic in lib/hosts.mjs using display
+ * label roots ("~" / "<cwd>"), then renders portable forward-slash labels. This module never
+ * touches the filesystem, so the label roots are never resolved as real paths by the caller.
+ */
+function defaultDescribeDestinations(selectedTargets, scope) {
+  const base = scope === "user" ? "~" : "<cwd>";
+  const groups = resolveUniqueDestinations(selectedTargets, scope, { home: "/~", cwd: "/<cwd>" });
+  return groups.map((group) => {
+    const segments = group.destination.split(/[\\/]+/);
+    const directory = segments.includes(".claude") ? ".claude/skills" : ".agents/skills";
+    return `${base}/${directory}/${SKILL_DIRECTORY} (${group.targets.join(", ")})`;
+  });
+}
+
+/**
+ * Minimal line reader over an injected readable stream. Answers are never echoed: only the
+ * prompt strings are written to `output`, and input is consumed silently. A trailing line
+ * without a newline is delivered once at end-of-input (mirroring node:readline); every read
+ * after end-of-input resolves to `null`, which callers treat as cancellation.
+ */
+function createLineReader(input) {
+  let buffer = "";
+  let ended = false;
+  let pending = null;
+
+  const settle = (line) => {
+    const reader = pending;
+    pending = null;
+    reader.resolve(line);
+  };
+
+  const flush = () => {
+    if (!pending) return;
+    const newlineIndex = buffer.indexOf("\n");
+    if (newlineIndex !== -1) {
+      const line = buffer.slice(0, newlineIndex).replace(/\r$/, "");
+      buffer = buffer.slice(newlineIndex + 1);
+      settle(line);
+    } else if (ended) {
+      const line = buffer.length > 0 ? buffer.replace(/\r$/, "") : null;
+      buffer = "";
+      settle(line);
+    }
+  };
+
+  const onData = (chunk) => {
+    buffer += chunk.toString();
+    flush();
+  };
+  const onEnd = () => {
+    ended = true;
+    flush();
+  };
+  const onError = () => {
+    ended = true;
+    flush();
+  };
+
+  input.on("data", onData);
+  input.on("end", onEnd);
+  input.on("error", onError);
+
+  return {
+    readLine() {
+      if (pending) throw new Error("Concurrent readLine calls are not supported.");
+      return new Promise((resolve) => {
+        pending = { resolve };
+        flush();
+      });
+    },
+    /**
+     * Detach from the input stream: remove every listener this reader attached, settle any
+     * pending read (as cancellation, i.e. `null`), and stop pumping the stream. Callers must
+     * invoke this on every exit path; otherwise listeners left on a terminal-backed stdin keep
+     * the process alive after the flow completes.
+     */
+    dispose() {
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("error", onError);
+      if (pending) settle(null);
+      if (typeof input.pause === "function") input.pause();
+      // Unref-style cleanup only fires on real handle-backed streams (e.g. process.stdin);
+      // in-memory fixtures such as PassThrough/Readable have no unref and are unaffected.
+      if (typeof input.unref === "function") input.unref();
+    },
+  };
+}
+
+/**
+ * Split hosts into the rendered list lines and the ordered selectable target ids. Pi is rendered
+ * as an informational line with the supported install command and is never selectable. Unknown
+ * host ids are ignored (the prompt module is a pass-through over detection results).
+ */
+function renderHostList(hosts) {
+  const knownTargets = new Set(writableTargets);
+  const lines = [];
+  const selectable = [];
+  for (const host of hosts) {
+    if (host.id === "pi") {
+      lines.push(`  pi - detect-only; install with: ${PI_INSTALL_COMMAND}`);
+      continue;
+    }
+    if (!knownTargets.has(host.id)) continue;
+    const number = selectable.length + 1;
+    selectable.push(host.id);
+    const status = host.detected
+      ? `detected${host.evidence ? ` (${host.evidence})` : ""}`
+      : "not detected";
+    lines.push(`  [${number}] ${host.id} - ${status}`);
+  }
+  return { lines, selectable };
+}
+
+/**
+ * Parse a multi-select answer. Accepts the alias "a"/"all" (case-insensitive) for every
+ * selectable target, or comma-separated numbers. Duplicates collapse; the result is normalized
+ * to the canonical selectable order. Returns null when any token is invalid (no partial
+ * acceptance of garbage).
+ */
+function parseSelection(line, selectable) {
+  const normalized = line.trim().toLowerCase();
+  if (normalized === "a" || normalized === "all") return [...selectable];
+  if (normalized.length === 0) return null;
+  const chosen = new Set();
+  for (const token of normalized.split(",")) {
+    if (!/^\d+$/.test(token.trim())) return null;
+    const number = Number(token.trim());
+    if (number < 1 || number > selectable.length) return null;
+    chosen.add(selectable[number - 1]);
+  }
+  return selectable.filter((id) => chosen.has(id));
+}
+
+/** Parse a scope answer ("1"/"user" or "2"/"project", case-insensitive); null when invalid. */
+function parseScope(line) {
+  const normalized = line.trim().toLowerCase();
+  if (normalized === "1" || normalized === "user") return "user";
+  if (normalized === "2" || normalized === "project") return "project";
+  return null;
+}
+
+/**
+ * Deterministic interactive selection flow with fully injected streams. Renders the detected
+ * hosts, asks for targets, scope, and confirmation, and returns `{ targets, scope }` on
+ * confirmation or `null` on cancellation (end-of-input at any prompt, or any non-confirm answer
+ * at the confirmation step). Reads no filesystem state beyond its arguments and performs no
+ * writes; the caller owns all filesystem effects. The input stream is always released before
+ * the returned promise settles: every exit path disposes the line reader (removing its
+ * listeners and stopping the stream) so an open terminal-backed stdin cannot keep the process
+ * alive.
+ *
+ * @param {{
+ *   hosts: Array<{ id: string, detected: boolean, evidence: string }>,
+ *   input: import("node:stream").Readable,
+ *   output: import("node:stream").Writable,
+ *   describeDestinations?: (selectedTargets: string[], scope: string) => string[],
+ * }} options
+ * @returns {Promise<{ targets: string[], scope: string } | null>}
+ */
+export async function selectInstallPlan({
+  hosts,
+  input,
+  output,
+  describeDestinations = defaultDescribeDestinations,
+}) {
+  if (!Array.isArray(hosts)) {
+    throw new TypeError("selectInstallPlan requires a hosts array from detectHosts().");
+  }
+  if (!input || typeof input.on !== "function") {
+    throw new TypeError("selectInstallPlan requires an injectable input stream.");
+  }
+  if (!output || typeof output.write !== "function") {
+    throw new TypeError("selectInstallPlan requires an injectable output stream.");
+  }
+
+  output.write("Detected coding-agent CLIs:\n");
+  const { lines, selectable } = renderHostList(hosts);
+  for (const line of lines) output.write(`${line}\n`);
+  if (selectable.length === 0) {
+    output.write("No installable coding-agent targets are supported.\n");
+    return null;
+  }
+
+  const reader = createLineReader(input);
+
+  try {
+    let selected = null;
+    while (selected === null) {
+      output.write(
+        `Select targets to install (comma-separated numbers 1-${selectable.length}, or "a" for all): `,
+      );
+      const answer = await reader.readLine();
+      if (answer === null) return null;
+      selected = parseSelection(answer, selectable);
+      if (selected === null) {
+        output.write(
+          `Invalid selection. Enter comma-separated numbers between 1 and ${selectable.length}, or "a" for all.\n`,
+        );
+      }
+    }
+
+    output.write("\nSelect scope:\n");
+    output.write(`  [1] user - installs to ${SCOPE_HINTS.user}\n`);
+    output.write(`  [2] project - installs to ${SCOPE_HINTS.project}\n`);
+    let scope = null;
+    while (scope === null) {
+      output.write("Select scope (1/2): ");
+      const answer = await reader.readLine();
+      if (answer === null) return null;
+      scope = parseScope(answer);
+      if (scope === null) {
+        output.write('Invalid scope. Enter "1" (user) or "2" (project).\n');
+      }
+    }
+
+    output.write("\nInstall plan:\n");
+    output.write(`  scope: ${scope}\n`);
+    output.write("  destinations:\n");
+    for (const line of describeDestinations(selected, scope)) {
+      output.write(`    ${line}\n`);
+    }
+    output.write("Proceed? [y/N] ");
+    const confirmation = await reader.readLine();
+    if (confirmation === null) return null;
+    if (!/^(?:y|yes)$/i.test(confirmation.trim())) return null;
+    return { targets: selected, scope };
+  } finally {
+    // Every exit path (confirmation, cancellation, EOF, thrown error) must release the input.
+    reader.dispose();
+  }
+}

package/package.json

@@ -1,17 +1,45 @@
 {
   "name": "mobile-agent-orchestrator",
-  "version": "0.0.1",
-  "description": "Placeholder to reserve the package name. The real package ships with v0.2.0 via GitHub Actions trusted publishing (egdev6/mobile-agent-orchestrator).",
+  "version": "0.2.0",
+  "description": "A guided Agent Skill for a private, recoverable mobile AI-agent environment.",
   "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "author": "egdev6",
   "repository": {
     "type": "git",
-    "url": "https://github.com/egdev6/mobile-agent-orchestrator"
+    "url": "git+https://github.com/egdev6/mobile-agent-orchestrator.git"
   },
-  "keywords": ["mobile-agent-orchestrator"],
-  "files": ["README.md"],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+  "homepage": "https://github.com/egdev6/mobile-agent-orchestrator",
+  "bugs": {
+    "url": "https://github.com/egdev6/mobile-agent-orchestrator/issues"
+  },
+  "bin": {
+    "mobile-agent-orchestrator": "bin/mobile-agent-orchestrator.mjs"
+  },
+  "files": [
+    "skills/",
+    "bin/",
+    "lib/"
+  ],
+  "scripts": {
+    "validate": "node scripts/validate-package.mjs",
+    "pack:check": "npm pack --dry-run --json",
+    "test": "npm run validate && node --test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "mobile-agent",
+    "tailscale",
+    "mosh"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
   }
 }

package/skills/mobile-agent-orchestrator/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: mobile-agent-orchestrator
+description: "Trigger: mobile agent setup, mobile orchestrator, Moshi, Mosh, Tailscale, remote mobile agent. Guide a human through a safe, host-aware mobile AI-agent installation."
+license: MIT
+metadata:
+  author: egdev6
+  version: "0.2.0"
+---
+
+## Activation Contract
+
+Use for human-supervised installation of a mobile AI-agent environment and its host-supported lifecycle or checkpoint path. This is an Agent Skill, not an MCP server. Support only macOS native or Windows 11 with WSL2 (Windows lifecycle, WSL Linux execution). Detect state read-only before change. On Windows native without WSL, stop and guide WSL2; never offer degraded native Windows. Do not assume that the invoking CLI provides Pi's persistence or lifecycle behavior.
+
+## Hard Rules
+
+Never request or persist private keys, pairing tokens, sign-in URLs, QR contents, or credentials. Use device-local pairing or hidden terminal input; QR data is temporary secret material. Never open public SSH or router ports. For full Mosh, run Tailscale exactly once: on macOS or WSL, never Windows and WSL together. Disable Tailscale SSH with Moshi/OpenSSH key auth. Inspect remote installers before execution or prefer signed package managers.
+
+Ask one question only when detection leaves a real decision or authorization. Obtain explicit approval before elevated installs, firewall/auth changes, cloud pairing, scheduled tasks, reboot, or destructive rollback. Configure firewall restrictions before enabling services, preserve local recovery, and validate SSH syntax before restart. Do not claim live processes, Herdr/tmux, or systemd survive physical reboot. Use only observed, host-specific checkpoint or resume evidence; Pi JSONL resume behavior is a Pi-specific capability and must not be generalized.
+
+## Decision Gates
+
+| Detected condition | Required action |
+| --- | --- |
+| Unsupported platform or missing WSL2 | Stop with the supported-path guidance. |
+| Existing service, key, firewall, or Tailscale state | Present read-only evidence and ask whether to preserve, repair, or stop. |
+| Installation, pairing, hardening, task, or reboot needed | Explain impact, rollback, and request the single required approval. |
+| Key choice | Ask Easy Pair versus manual Ed25519; harden only after a tested key. |
+| Moshi setup | Ask minimal versus full privacy consent, then integrations and notifications separately. |
+
+## Execution Steps
+
+1. Follow the platform matrix and record only non-sensitive state.
+2. Establish permissions, rollback, local recovery, and network exposure boundaries.
+3. Install and verify OpenSSH, Tailscale, mobile clients, Moshi, `moshi-hook`, Mosh, and Herdr or tmux using the guided reference.
+4. Test key authentication before optional strict SSH hardening; keep Tailscale SSH off.
+5. Configure the approved lifecycle path, privacy level, integrations, notifications, and the host-supported checkpoint/resume procedure. On Pi, this may be the supported local JSONL procedure; do not invent an equivalent for another CLI.
+6. Run disconnect and approved reboot recovery verification. Mark cold-boot behavior as pending whenever observed evidence is unavailable.
+
+## Output Contract
+
+Report platform, detected state, approvals granted or declined, mutations performed, non-sensitive verification evidence, rollback path, and pending recovery evidence. State exactly why a step stopped. Never report a reboot or service-survival claim without observed evidence.
+
+## References
+
+- [Platform matrix](references/platform-matrix.md)
+- [Guided install](references/guided-install.md)
+- [Verification and recovery](references/verification-and-recovery.md)
+- [Agent hosts](references/agent-hosts.md)

package/skills/mobile-agent-orchestrator/references/agent-hosts.md

@@ -0,0 +1,45 @@
+# Agent hosts reference
+
+Compatibility claims in this file are limited to what current official host documentation states. Behavior that official documentation does not confirm is marked **Unverified** and must be observed locally before being relied on. Skill locations do not imply lifecycle guarantees: session persistence and resume behavior are host-specific.
+
+This skill is one canonical Agent Skill directory (`SKILL.md` plus on-demand references). Every host below can discover the same skill content through its own documented locations; no host-specific behavior is inferred from compatibility alone.
+
+## Host skill locations
+
+| Host | Project scope | User scope | Source |
+| --- | --- | --- | --- |
+| Pi | `.pi/skills/`; Agent Skills root `.agents/skills/` (project discovery walks ancestors up to the repository root). The `skills/` directory or `pi.skills` array in `package.json` is package discovery for `pi install`, not a general project skill root | `~/.pi/agent/skills/` (default agent directory) and `~/.agents/skills/`; additional directories via the `skills` setting in `settings.json` | Pi documentation; `pi install npm:...|git:...|./local` for package installs |
+| Claude Code | `.claude/skills/<name>/SKILL.md` | `~/.claude/skills/<name>/SKILL.md` | Claude Code docs, "Skills" |
+| Codex CLI | `.agents/skills/` at the launch directory, parent directories, and the repository root | `$HOME/.agents/skills/` | Codex docs, "Agent Skills" |
+| Gemini CLI | `.gemini/skills/` with `.agents/skills/` as an interoperable alias | `~/.gemini/skills/` with `~/.agents/skills/` as an interoperable alias | Gemini CLI docs, "Agent Skills" |
+| OpenCode | `.opencode/skills/`, `.claude/skills/`, `.agents/skills/` | `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` | OpenCode docs, "Skills" |
+
+All five hosts implement the open [Agent Skills specification](https://agentskills.io/specification): one directory per skill containing a `SKILL.md` with YAML frontmatter (`name`, `description` required). Within this repository, Pi package discovery stays on the `pi.skills: ./skills` manifest and must not be changed; other hosts copy or link the same `skills/mobile-agent-orchestrator/` directory into one of the documented roots above.
+
+### Host-specific notes
+
+- **Pi.** Project `.agents/skills/` discovery walks from the working directory through ancestors and stops at the repository root. Personal package installs are recorded in `~/.pi/agent/settings.json`; project package installs in `.pi/settings.json` after project trust. Pi session persistence is JSONL under `~/.pi/agent/sessions/`, with `--continue`, `--resume`, and `/fork`. **This JSONL resume behavior is Pi-specific and must not be generalized to any other host.**
+- **Claude Code.** Project skills load from `.claude/skills/` in the launch directory and every parent up to the repository root; nested skills activate when Claude works on files in their subtree. Symlinked skill folders are read from the symlink target. Personal skills in `~/.claude/skills/` do not load in Cowork or cloud sessions. Transcript-based resume uses `claude --continue` / `claude --resume`.
+- **Codex CLI.** Codex scans `.agents/skills` from the launch directory up to the repository root and reads `$HOME/.agents/skills` for user scope; it follows symlinked skill folders. Skills sharing a name are not merged; both appear in selectors. Session resume uses `codex resume`.
+- **Gemini CLI.** User skills load from `~/.gemini/skills/` or the `~/.agents/skills/` alias; workspace skills from `.gemini/skills/` or the `.agents/skills/` alias. Within a tier, the `.agents/skills/` alias takes precedence. Session resume uses `gemini --resume` or the `/resume` session browser.
+- **OpenCode.** Project-local paths are discovered by walking up from the working directory to the git worktree root across `.opencode/skills/`, `.claude/skills/`, and `.agents/skills/`; global paths load from the three user roots above. Session resume uses `--continue` (last session) or `--session <id>`; `--fork` branches a resumed session and must be combined with one of those (for example `--continue --fork`).
+
+## Session persistence boundary
+
+Session resume is a property of the invoking CLI, not of the skill. The mechanisms above (Pi JSONL, Claude Code transcripts, `codex resume`, Gemini CLI session browser, OpenCode `--continue`/`--session`) recover **agent conversation state** only.
+
+**Herdr** is an agent-aware multiplexer: it keeps agent panes running on the host across mobile-client disconnects and network drops and tracks per-pane agent state (blocked, working, done). Like tmux, it does not preserve live processes across a physical reboot. **Agent conversation recovery after a disconnect or reboot is a separate, CLI-owned capability** and must be verified with the evidence rules in the [verification and recovery reference](verification-and-recovery.md): mark cold-boot behavior as pending whenever observed evidence is unavailable.
+
+Whether Herdr integrates with each CLI's resume flow beyond pane survival is **Unverified**; consult current official Herdr and Moshi documentation and observe local behavior before claiming it.
+
+## Sources (official documentation, accessed 2026-09-30)
+
+- Pi: Agent Skills and package discovery — Pi coding agent documentation v0.99.1 (`docs/skills.md`, `docs/packages.md`); session format and resume — `docs/session-format.md`, `docs/sessions.md`.
+- Claude Code: Skills — https://code.claude.com/docs/en/skills; sessions and resume — https://code.claude.com/docs/en/sessions.
+- Codex: Agent Skills — https://developers.openai.com/codex/skills; CLI reference (`codex resume`) — https://developers.openai.com/codex/cli/reference.
+- Gemini CLI: Agent Skills — https://geminicli.com/docs/cli/skills/; session management — https://geminicli.com/docs/cli/session-management/.
+- OpenCode: Skills — https://opencode.ai/docs/skills/; CLI flags — https://opencode.ai/docs/cli/.
+- Agent Skills specification — https://agentskills.io/specification.
+- Moshi/Herdr integration — https://getmoshi.app/docs/herdr.
+
+Claims not listed under an official source above remain **Unverified** and require local observation before use.

package/skills/mobile-agent-orchestrator/references/guided-install.md

@@ -0,0 +1,89 @@
+# Guided install
+
+Proceed in order. Lines labelled **Read-only** discover state. Lines labelled **Mutation** require the stated approval immediately before execution. Do not combine independent approvals or ask about a decision already resolved by detection.
+
+## 1. Network and OpenSSH baseline
+
+**Read-only:** identify installed tools and listeners without exposing configuration secrets.
+
+```bash
+command -v ssh sshd tailscale mosh tmux
+```
+
+Then run exactly one matching read-only listener check:
+
+```bash
+# Linux or WSL.
+ss -lnt
+```
+
+```bash
+# macOS; lsof is stock and needs no additional package.
+lsof -nP -iTCP -sTCP:LISTEN
+```
+
+If OpenSSH server installation is needed, explain the signed package-manager source, required elevation, service effect, rollback package/service action, and local recovery path. Ask for approval, then use the current platform package documentation rather than an uninspected remote installer. Do not enable a listener until its firewall rule is constrained to the private overlay interface or equivalent private source range. Never add router forwarding or a public-IP rule.
+
+Before any SSH restart, validate the generated configuration with the platform's documented syntax check, retain the current connected session, and test a second connection. A failed validation or missing recovery path stops the flow.
+
+## 2. Tailscale placement and mobile clients
+
+**Read-only:** confirm whether Tailscale is installed, signed in, running, and whether its SSH feature is enabled.
+
+```bash
+tailscale status
+tailscale netcheck
+```
+
+If unavailable, prefer the current signed vendor package path. Inspect any downloaded installer before execution. Ask approval before sign-in, pairing, or changing network state. For full Mosh, choose exactly one placement: macOS on the native target, or WSL on the Windows route. Detect and resolve a concurrent Windows-and-WSL placement before proceeding.
+
+After the overlay connection works, disable Tailscale SSH for the Moshi/OpenSSH key-auth route and verify the resulting state. Install and sign in to the official Tailscale Android or iOS app only with consent. Device authentication, URLs, and QR codes remain on the device; treat a QR code as a temporary secret and never transcribe it.
+
+## 3. Key choice and SSH hardening
+
+Ask one question: **Easy Pair or manual Ed25519 key?** Describe the available local pairing mechanism only if it is detected; otherwise select manual key setup.
+
+For manual setup, generate and keep the private key on the approved client device. The public-key command is safe to show; its output is not to be copied into chat:
+
+```bash
+# Mutation after approval; choose a device-local path and passphrase prompt.
+ssh-keygen -t ed25519 -a 64 -f <private-key-path> -C "mobile-agent"
+
+# Read-only test after public-key installation by an out-of-chat method.
+ssh -o BatchMode=yes -o PreferredAuthentications=publickey <account>@<private-overlay-name> true
+```
+
+Do not disable password or interactive authentication until this test succeeds from the intended mobile route and a local recovery path exists. Then ask a separate approval for strict hardening. Apply only documented OpenSSH settings, validate syntax before reload, reload rather than blindly restart when supported, and retest the key connection before closing the existing session.
+
+## 4. Moshi, `moshi-hook`, Mosh, and terminal host
+
+Use current official Moshi and `moshi-hook` documentation. First detect whether each component exists and whether the maintainer supplies a signed package-manager release. Do not execute an opaque curl-pipe-shell installer; inspect a downloaded script before execution. Ask for installation approval separately from cloud pairing approval.
+
+Ask one privacy question: **minimal or full Moshi consent?** Minimal enables only the pairing and session capability necessary for the chosen route. Full additionally enables only the current official features the human explicitly accepts. Present data handling and revocation evidence from current official documentation before either choice.
+
+Ask separately which detected integrations to enable and whether notifications are wanted. Offer only discovered integrations plus **none**; do not invent providers. Ask before granting each integration permission or sending a test notification.
+
+Install Mosh from a signed package source after approval and use the private-overlay name for connection testing:
+
+```bash
+# Read-only: confirm local clients and server availability.
+mosh --version
+tmux -V
+
+# Interactive test; does not place a key or token in chat.
+mosh --ssh="ssh -o PreferredAuthentications=publickey" <account>@<private-overlay-name>
+```
+
+Choose Herdr when installed and supported by current documentation; otherwise use tmux. A typical tmux session command is:
+
+```bash
+tmux new-session -As mobile-agent
+```
+
+Neither Herdr nor tmux preserves live processes across physical reboot. Use a persisted checkpoint or resume mechanism only when the invoking host documents and the human verifies it; Pi JSONL sessions may resume from disk under Pi's supported behavior, with no equivalent assumed elsewhere.
+
+## 5. Lifecycle, checkpoints, and notifications
+
+On the Windows route, follow the approved WSL systemd, linger, and Windows keepalive sequence in the platform matrix. On macOS, require current official lifecycle evidence before creating a persistent service. Never state that the service will survive reboot until it has passed the recovery verification.
+
+Ask whether to enable session checkpoints only after the chosen session host is working. Configure only the invoking host's supported checkpoint format and local storage; do not claim that another CLI can resume Pi JSONL sessions. All live processes die on reboot. For Pi, record the supported JSONL session resume command or UI route without recording session contents. Enable approved notifications last and verify with a non-sensitive test event.

package/skills/mobile-agent-orchestrator/references/platform-matrix.md

@@ -0,0 +1,73 @@
+# Platform matrix
+
+Use these checks before any mutation. Record only non-sensitive results. Ask no question if the next safe action is already determined.
+
+## Stable targets
+
+| Detection | Route | Lifecycle boundary |
+| --- | --- | --- |
+| `Darwin` | macOS native | macOS owns lifecycle and execution. |
+| Windows host explicitly confirmed as Windows 11 with a working WSL2 distribution | Windows 11 + WSL2 | Windows owns startup; WSL owns Linux services and agent execution. |
+| Windows native without WSL2 | Stop | Guide WSL2 installation; do not configure a native-Windows substitute. |
+| Other platform or unclear state | Stop | Explain that no stable target was detected. |
+
+## Read-only preflight
+
+Run only the checks relevant to the current shell:
+
+```bash
+# Read-only: identify the Unix execution environment.
+uname -s
+uname -r
+
+# Read-only: macOS version when Darwin was detected.
+sw_vers
+
+# Read-only: identify a WSL Linux environment.
+grep -Ei 'microsoft|wsl' /proc/sys/kernel/osrelease
+
+# Read-only: run from Windows PowerShell. Stop unless Caption explicitly says Windows 11.
+$os = Get-CimInstance -ClassName Win32_OperatingSystem
+$os | Select-Object Caption, Version, BuildNumber
+if ($os.Caption -notmatch '\bWindows 11\b') { throw "Windows 11 is required; stop this route." }
+
+# Read-only: run from Windows PowerShell or Command Prompt after the Windows 11 gate passes.
+wsl --status
+wsl --version
+wsl --list --verbose
+```
+
+On Windows, continue only when the Windows version gate explicitly reports Windows 11, WSL version 2, and a selected distribution. Stop rather than infer Windows 11 from WSL or partial signals. If WSL2 is absent, explain that the human must approve the current Microsoft-documented WSL2 installation path and any restart it requires.
+
+## Placement decisions
+
+### macOS native
+
+Use macOS as the single execution target for OpenSSH, Tailscale, Mosh, and the session host. Before proposing a lifecycle daemon, firewall change, or persistent-login setting, obtain current official Apple documentation and collect local evidence. This draft intentionally supplies no exact macOS firewall or lifecycle command because those commands must be verified for the installed macOS release.
+
+### Windows 11 + WSL2
+
+Windows is the lifecycle host; the selected WSL2 distribution is the Linux execution target. For the full-Mosh route, Tailscale must run in WSL only. If the Windows Tailscale client is active, present the conflict and require approval to stop or remove that placement before enabling WSL Tailscale. Never run both concurrently for this route.
+
+Ask separately for approval before each of these mutations:
+
+1. Enabling WSL systemd by editing the distribution configuration and restarting WSL.
+2. Creating a Windows startup scheduled task that invokes the selected distribution's approved keepalive/service-start action.
+3. Enabling user linger in WSL so approved user services can start without an interactive login.
+
+Use current Microsoft and distribution documentation to construct the exact scheduled-task and systemd commands. Verify each with read-only checks such as:
+
+```bash
+# Read-only: from WSL after systemd is enabled.
+systemctl is-system-running
+loginctl show-user "$USER" -p Linger
+
+# Read-only: from Windows after the task is created.
+schtasks /query /tn "<task-name>" /fo LIST /v
+```
+
+Linger and a startup task can start configured services after boot; they do not preserve running agent processes across a physical reboot. A host-specific persisted checkpoint may resume only when that host documents and the human observes the behavior. Pi JSONL resume is specific to Pi and must not be claimed for other CLIs.
+
+## Permission and rollback gate
+
+Before the first change, identify the invoking user, privilege boundary, current SSH access path, installed service state, and how to undo each proposed mutation. Keep an already-working local console or separate authenticated session available before touching firewall or SSH authentication. If that recovery path cannot be demonstrated, stop rather than making the change.

package/skills/mobile-agent-orchestrator/references/verification-and-recovery.md

@@ -0,0 +1,64 @@
+# Verification and recovery
+
+Collect non-sensitive evidence after every approved mutation. A command failing because a component is absent is a finding, not permission to install or change it.
+
+## Verification sequence
+
+1. **Private network:** confirm the selected target is present on the overlay and no public port or router forwarding was created.
+2. **SSH:** test public-key authentication in a second session before closing the recovery session. Confirm Tailscale SSH remains disabled for this route.
+3. **Mosh:** establish a mobile-route session, briefly disconnect the client network, reconnect, and record whether Mosh reconnects as expected.
+4. **Host:** confirm Herdr or tmux behavior, checkpoint creation, selected integration authorization, and notification delivery without recording contents.
+5. **Lifecycle:** only after explicit reboot approval, test the documented start and the invoking host's documented checkpoint/resume path. Pi JSONL resume is tested only when Pi is the host.
+
+Useful read-only checks:
+
+```bash
+# Overlay evidence.
+tailscale status
+tailscale netcheck
+```
+
+Run exactly one matching read-only listener check:
+
+```bash
+# Linux or WSL.
+ss -lnt
+```
+
+```bash
+# macOS; lsof is stock and needs no additional package.
+lsof -nP -iTCP -sTCP:LISTEN
+```
+
+```bash
+# SSH configuration and non-interactive key-auth test.
+sshd -T
+ssh -o BatchMode=yes -o PreferredAuthentications=publickey <account>@<private-overlay-name> true
+
+# Service and user-linger evidence on a systemd Linux target.
+systemctl --user --no-pager status <service-name>
+loginctl show-user "$USER" -p Linger
+```
+
+Interpret listener output with the firewall and overlay policy; a listening port is not by itself evidence of public exposure. Confirm that no public address, router forwarding rule, or broad firewall exception was introduced. If current platform tooling cannot prove this, stop and request local network evidence rather than assuming safety.
+
+## Recovery decision tree
+
+| Failure | Safe response |
+| --- | --- |
+| Key test fails after hardening | Keep the existing session open; restore the last known-good authentication setting through the local recovery path; validate before reload. |
+| SSH syntax validation fails | Do not reload or restart; correct or restore the staged configuration while the existing session remains available. |
+| Tailscale appears on both Windows and WSL | Stop the full-Mosh route; preserve one reachable path; request approval to remove or stop one placement. |
+| Mosh does not reconnect | Keep SSH recovery available; inspect overlay and SSH evidence first; do not expose a public port as a workaround. |
+| Keepalive, linger, or lifecycle fails | Collect service/task status and current official documentation; do not claim persistence. |
+| Reboot loses a live terminal process | Treat as expected; restart required processes through the approved lifecycle path and resume only a host-supported persisted checkpoint. Pi JSONL resume is Pi-specific. |
+
+## Reboot gate
+
+Before reboot, ask explicit approval and state that all live processes will die. Verify a local recovery path, the key-auth path, rollback instructions, and the Windows task or macOS lifecycle evidence first. After reboot, check the actual startup state, re-establish private-overlay SSH and Mosh, then resume a persisted checkpoint only if the invoking host supports it and the path is available. For Pi, this may be the local JSONL session path.
+
+**Draft evidence status:** cold-boot and post-reboot behavior remain pending until a human observes and records this sequence on the selected supported target. Do not mark the installation reboot-verified before that evidence exists.
+
+## Rollback
+
+Rollback only the approved mutation that caused the failure: disable the newly created service or task, restore the saved SSH configuration, remove the narrow firewall rule if it was newly added, or sign out/remove the newly added client according to current vendor documentation. Do not delete keys, sessions, or unrelated configuration as a generic rollback step. Any destructive rollback requires a fresh explicit approval.