+
+
+
+
+Step 1 of 4 · Check
+Checking this computer
+Looking for Node.js, pnpm, Pi and Gentle Shell. Nothing changes until you confirm a plan.
+ + +Gentle Shell
+ +Step 1 of 4 · Check
+Looking for Node.js, pnpm, Pi and Gentle Shell. Nothing changes until you confirm a plan.
+ + + elements, never markup. */
+function rich(doc, value) {
+ return text(value).split("`").map((part, index) => (index % 2 === 1 ? el(doc, "code", {}, part) : doc.createTextNode(part)));
+}
+
+function panel(doc, { stage, eyebrow, title, lead, tone }, ...children) {
+ const heading = el(doc, "h1", { id: "view-title", tabindex: "-1" }, title);
+ const node = el(doc, "section", { class: `panel${tone ? ` panel-${tone}` : ""}`, "aria-labelledby": "view-title", "data-stage": stage,
+ "data-tone": tone },
+ el(doc, "p", { class: "eyebrow" }, eyebrow),
+ heading,
+ lead ? el(doc, "p", { class: "lead" }, rich(doc, lead)) : null,
+ ...children);
+ headingOf.set(node, heading);
+ return node;
+}
+
+function actionButton(doc, label, variant, onClick) {
+ const node = el(doc, "button", { type: "button", class: `button button-${variant}` }, label);
+ node.addEventListener("click", (event) => {
+ event?.preventDefault?.();
+ onClick(node);
+ });
+ return node;
+}
+
+/** Stage list; `stopped` marks the install stage when it ended blocked or failed. */
+export function renderStages(doc, current, { stopped = false } = {}) {
+ const index = stages.findIndex(([id]) => id === current);
+ return stages.map(([id, label], position) => {
+ let state = position < index ? "done" : position === index ? "current" : "upcoming";
+ if (stopped && id === "install") state = "issue";
+ const glyph = { done: "✓", issue: "!" }[state] ?? String(position + 1);
+ const note = { done: " (completed)", issue: " (stopped)" }[state];
+ return el(doc, "li", { class: `stage stage-${state}`, "aria-current": state === "current" ? "step" : null },
+ el(doc, "span", { class: "stage-dot", "aria-hidden": "true" }, glyph),
+ el(doc, "span", { class: "stage-label" }, label),
+ note ? el(doc, "span", { class: "sr-only" }, note) : null);
+ });
+}
+
+export function renderLoading(doc) {
+ return panel(doc, { stage: "check", eyebrow: "Step 1 of 4 · Check", title: "Checking this computer",
+ lead: "Looking for Node.js, pnpm, Pi and Gentle Shell. Nothing changes until you confirm a plan." },
+ el(doc, "div", { class: "loader", "aria-hidden": "true" }, el(doc, "span"), el(doc, "span"), el(doc, "span")));
+}
+
+function disclosureCard(doc, item) {
+ return el(doc, "article", { class: `card disclosure${item.changes ? " disclosure-changes" : ""}` },
+ el(doc, "div", { class: "card-head" },
+ el(doc, "h2", { class: "card-title" }, item.title),
+ el(doc, "span", { class: `pill ${item.changes ? "pill-accent" : "pill-muted"}` },
+ el(doc, "span", { "aria-hidden": "true" }, item.changes ? "● " : "○ "), item.state)),
+ el(doc, "p", {}, rich(doc, item.text)),
+ item.detail ? el(doc, "p", { class: "detail" }, el(doc, "code", {}, item.detail)) : null);
+}
+
+/** Review screen. handlers: install({ consent, checkbox, button }), reload(), close(). */
+export function renderPlan(doc, model, handlers) {
+ const close = actionButton(doc, "Close installer", "ghost", () => handlers.close());
+ if (model.kind === "blocked") {
+ return panel(doc, { stage: "review", eyebrow: "Step 2 of 4 · Review", title: "Something needs attention first",
+ lead: "Nothing was changed. Resolve these items, then check again.", tone: "warning" },
+ el(doc, "ul", { class: "blockers", role: "list" }, model.blockers.map((blocker) => el(doc, "li", { class: "alert alert-warning" },
+ el(doc, "h2", { class: "alert-title" }, el(doc, "span", { "aria-hidden": "true" }, "! "), blocker.toolLabel),
+ el(doc, "p", {}, rich(doc, blocker.guidance)),
+ el(doc, "p", { class: "meta" }, "Code: ", el(doc, "code", {}, blocker.code))))),
+ el(doc, "div", { class: "actions" }, actionButton(doc, "Check again", "primary", () => handlers.reload()), close));
+ }
+ if (model.kind === "nothing") {
+ return panel(doc, { stage: "review", eyebrow: "Step 2 of 4 · Review", title: "Gentle Shell is already set up",
+ lead: "This computer already has everything the wizard installs." },
+ el(doc, "p", {}, rich(doc, "Run `gentle-shell` in a terminal. To upgrade, run `gentle-shell update`.")),
+ el(doc, "div", { class: "actions" }, close));
+ }
+ const recovery = model.kind === "recovery";
+ const checkbox = el(doc, "input", { type: "checkbox", id: "consent", class: "consent-input", "aria-describedby": "consent-hint" });
+ const install = actionButton(doc, recovery ? "Complete setup" : "Install Gentle Shell", "primary", (button) =>
+ handlers.install({ consent: checkbox.checked === true, checkbox, button }));
+ checkbox.addEventListener("change", () => {
+ if (checkbox.checked) checkbox.removeAttribute("aria-invalid");
+ handlers.consentChanged?.(checkbox.checked === true);
+ });
+ const heading = recovery
+ ? { title: "Finish setting up Gentle Shell",
+ lead: "Gentle Shell is already installed; this completes setup. Nothing is reinstalled, and nothing changes until you confirm." }
+ : { title: "Review the installation plan",
+ lead: "Nothing changes until you confirm. This is exactly what the installer will do on this computer." };
+ return panel(doc, { stage: "review", eyebrow: "Step 2 of 4 · Review", ...heading },
+ el(doc, "section", { class: "block", "aria-labelledby": "changes-title" },
+ el(doc, "h2", { id: "changes-title", class: "section-title" }, "What changes on this computer"),
+ el(doc, "div", { class: "grid" }, model.disclosures.map((item) => disclosureCard(doc, item)))),
+ el(doc, "section", { class: "block", "aria-labelledby": "steps-title" },
+ el(doc, "h2", { id: "steps-title", class: "section-title" }, recovery ? "Setup steps" : "Installation steps"),
+ el(doc, "ol", { class: "plan-steps" }, model.actions.map((action) => el(doc, "li", {},
+ el(doc, "span", { class: "plan-step-text" }, rich(doc, action.description)))))),
+ el(doc, "div", { class: "consent" },
+ checkbox,
+ el(doc, "div", {},
+ el(doc, "label", { for: "consent", class: "consent-label" }, "I reviewed this plan and agree to these changes on this computer."),
+ el(doc, "p", { id: "consent-hint", class: "hint" }, "The installer runs only the steps listed above. Existing installations are not replaced."))),
+ el(doc, "div", { class: "actions" }, install, close));
+}
+
+function logLine(doc, entry) {
+ const status = text(entry.status) || "unknown";
+ return el(doc, "li", { class: `log-line log-${status}` },
+ el(doc, "span", { class: "log-seq" }, String(entry.seq).padStart(3, "0")),
+ el(doc, "span", { class: "log-status" }, status),
+ el(doc, "span", { class: "log-step" }, text(entry.step)),
+ entry.reason ? el(doc, "span", { class: "log-reason" }, text(entry.reason)) : null);
+}
+
+function logPanel(doc, entries) {
+ const lines = el(doc, "ol", { class: "log-lines" });
+ const empty = el(doc, "p", { class: "log-empty" }, "Waiting for the first step…");
+ const node = el(doc, "section", { class: "log", "aria-labelledby": "log-title" },
+ el(doc, "div", { class: "log-head" },
+ el(doc, "span", { class: "log-dots", "aria-hidden": "true" }, el(doc, "span"), el(doc, "span"), el(doc, "span")),
+ el(doc, "h2", { id: "log-title", class: "log-title" }, "Installer log")),
+ el(doc, "div", { class: "log-body", tabindex: "0", role: "region", "aria-label": "Installer log lines" }, empty, lines));
+ const update = (all) => {
+ lines.replaceChildren(...all.map((entry) => logLine(doc, entry)));
+ if (all.length > 0) empty.setAttribute("hidden", "");
+ else empty.removeAttribute("hidden");
+ };
+ update(entries);
+ return { node, update };
+}
+
+const stepIcons = Object.freeze({ done: "✓", failed: "✕", blocked: "!", running: "", pending: "", skipped: "–", unknown: "?" });
+function stepRow(doc, item) {
+ return el(doc, "li", { class: `step step-${item.status}`, "aria-current": item.status === "running" ? "step" : null },
+ el(doc, "span", { class: "step-icon", "aria-hidden": "true" }, stepIcons[item.status]),
+ el(doc, "span", { class: "step-label" }, item.label),
+ el(doc, "span", { class: "step-status" }, item.statusText));
+}
+
+/** Progress screen with in-place updates, so focus stays on the heading. */
+export function renderProgress(doc) {
+ const bar = el(doc, "progress", { id: "install-progress", max: "1", value: "0", "aria-describedby": "progress-count" });
+ const count = el(doc, "span", { id: "progress-count", class: "progress-count" }, "Starting…");
+ const steps = el(doc, "ol", { class: "steps" });
+ const log = logPanel(doc, []);
+ const node = panel(doc, { stage: "install", eyebrow: "Step 3 of 4 · Install", title: "Installing Gentle Shell",
+ lead: "This can take a few minutes. Keep this tab and the terminal open." },
+ el(doc, "div", { class: "progress" },
+ el(doc, "div", { class: "progress-head" }, el(doc, "label", { for: "install-progress", class: "progress-label" }, "Progress"), count),
+ bar),
+ el(doc, "div", { class: "progress-body" },
+ el(doc, "section", { class: "block", "aria-labelledby": "progress-steps-title" },
+ el(doc, "h2", { id: "progress-steps-title", class: "section-title" }, "Steps"), steps),
+ log.node));
+ const update = (model, entries) => {
+ bar.setAttribute("max", String(Math.max(model.total, 1)));
+ bar.setAttribute("value", String(model.done));
+ count.textContent = model.total > 0 ? `${model.done} of ${model.total} steps` : "Starting…";
+ steps.replaceChildren(...model.items.map((item) => stepRow(doc, item)));
+ log.update(entries);
+ };
+ return { node, update };
+}
+
+/** Final screen. handlers: close(), copy?(text) -> Promise. */
+export function renderOutcome(doc, model, handlers, entries = []) {
+ const children = [
+ el(doc, "div", { class: `alert alert-${model.tone}` },
+ el(doc, "p", { class: "alert-title" }, el(doc, "span", { "aria-hidden": "true" }, model.tone === "success" ? "✓ " : model.tone === "warning" ? "! " : "✕ "),
+ model.badge),
+ el(doc, "p", {}, rich(doc, model.guidance))),
+ ];
+ if (model.command) {
+ const command = el(doc, "code", { class: "command-text" }, model.command);
+ const copy = handlers.copy
+ ? actionButton(doc, "Copy", "ghost", async (button) => {
+ const copied = await handlers.copy(model.command);
+ button.textContent = copied ? "Copied" : "Copy failed";
+ })
+ : null;
+ children.push(el(doc, "section", { class: "block", "aria-labelledby": "next-title" },
+ el(doc, "h2", { id: "next-title", class: "section-title" }, "Next"),
+ el(doc, "ol", { class: "next-steps" }, model.next.map((line) => el(doc, "li", {}, el(doc, "span", { class: "plan-step-text" }, rich(doc, line))))),
+ el(doc, "div", { class: "command" }, el(doc, "span", { class: "command-prompt", "aria-hidden": "true" }, "$"), command, copy)));
+ } else {
+ children.push(el(doc, "section", { class: "block", "aria-labelledby": "next-title" },
+ el(doc, "h2", { id: "next-title", class: "section-title" }, "What to do next"),
+ el(doc, "ol", { class: "next-steps" }, model.next.map((line) => el(doc, "li", {}, el(doc, "span", { class: "plan-step-text" }, rich(doc, line)))))));
+ }
+ if (model.notes.length > 0) children.push(el(doc, "ul", { class: "notes" }, model.notes.map((note) => el(doc, "li", {}, note))));
+ const facts = [];
+ if (model.failedStep) facts.push(el(doc, "li", {}, "Failed step: ", el(doc, "code", {}, model.failedStep.id)));
+ if (model.reason) facts.push(el(doc, "li", {}, "Reason: ", el(doc, "code", {}, model.reason)));
+ if (facts.length > 0) children.push(el(doc, "ul", { class: "facts" }, facts));
+ // Untrusted process output: one plain text node, never `rich` code spans.
+ if (model.detail) {
+ children.push(el(doc, "section", { class: "block", "aria-labelledby": "setup-detail-title" },
+ el(doc, "h2", { id: "setup-detail-title", class: "section-title" }, `Last error from ${model.detailCommand}`),
+ el(doc, "p", { class: "detail" }, el(doc, "code", {}, model.detail))));
+ }
+ if (model.completed.length > 0) {
+ children.push(el(doc, "details", { class: "completed" },
+ // A blocked run only passed read-only checks before it stopped.
+ el(doc, "summary", {}, `${model.outcome === "blocked" ? "Checks that passed" : "Completed steps"} (${model.completed.length})`),
+ el(doc, "ul", {}, model.completed.map((item) => el(doc, "li", {}, el(doc, "span", { "aria-hidden": "true" }, "✓ "), item.label)))));
+ }
+ if (entries.length > 0) {
+ const log = logPanel(doc, entries);
+ children.push(el(doc, "details", { class: "completed" }, el(doc, "summary", {}, `Installer log (${entries.length} entries)`), log.node));
+ }
+ children.push(el(doc, "div", { class: "actions" }, actionButton(doc, "Close installer", model.tone === "success" ? "primary" : "secondary",
+ () => handlers.close())));
+ return panel(doc, { stage: "done", eyebrow: "Step 4 of 4 · Done", title: model.title, lead: model.lead, tone: model.tone }, ...children);
+}
+
+export function renderClosed(doc, outcome) {
+ const installed = outcome?.outcome === "ready" || outcome?.outcome === "terminal-action-required";
+ return panel(doc, { stage: "done", eyebrow: "Finished", title: "Installer closed",
+ lead: installed
+ ? "You can close this tab. Run `gentle-shell` in a terminal to start."
+ : "You can close this tab. The terminal shows the same result, and nothing else will run." });
+}
+
+export function renderSession(doc) {
+ return panel(doc, { stage: "check", eyebrow: "Session ended", title: "This session has ended",
+ lead: "The installer link works once, in the browser that opened it, and stops when the installer closes. Run the installer again from your terminal to get a new link." });
+}
+
+// ---------------------------------------------------------------------------
+// Controller
+// ---------------------------------------------------------------------------
+
+function isProgress(body) {
+ return body !== null && typeof body === "object" && Array.isArray(body.entries);
+}
+const sessionEnded = (status) => status === 401 || status === 403;
+const noAnswer = "The installer did not answer. Check that the terminal is still running it, then try again.";
+
+/**
+ * createWizard({ document, fetch, setTimeout, clearTimeout, clipboard? })
+ * Expects #view, #stages, #alert (role=alert) and #status (role=status).
+ */
+export function createWizard({ document: doc, fetch: request, setTimeout: later, clearTimeout: cancel, clipboard = null }) {
+ const roots = {
+ view: doc.getElementById("view"),
+ stages: doc.getElementById("stages"),
+ alert: doc.getElementById("alert"),
+ status: doc.getElementById("status"),
+ };
+ const state = { plan: null, steps: [], entries: [], lastSeq: 0, poll: initialPoll(), timer: null, outcome: null, busy: false,
+ progress: null, running: false };
+
+ async function api(path, { method = "GET", body } = {}) {
+ const init = { method, headers: { ...API_HEADERS }, credentials: "same-origin", cache: "no-store" };
+ if (body !== undefined) {
+ init.headers["Content-Type"] = "application/json";
+ init.body = JSON.stringify(body);
+ }
+ const response = await request(path, init);
+ let data = null;
+ try {
+ data = await response.json();
+ } catch {
+ data = null;
+ }
+ return { status: response.status, body: data };
+ }
+
+ function announce(message) {
+ if (roots.status) roots.status.textContent = message;
+ }
+ function clearError() {
+ roots.alert?.replaceChildren();
+ }
+ function showError(message, retry = null, { tone = "error", title = "Problem" } = {}) {
+ const retryButton = retry ? actionButton(doc, "Try again", "secondary", () => {
+ clearError();
+ retry();
+ }) : null;
+ roots.alert?.replaceChildren(el(doc, "div", { class: `alert alert-${tone}` },
+ el(doc, "p", { class: "alert-title" }, el(doc, "span", { "aria-hidden": "true" }, tone === "error" ? "✕ " : "! "), title),
+ el(doc, "p", {}, message),
+ retryButton ? el(doc, "div", { class: "actions" }, retryButton) : null));
+ }
+ function stopPolling() {
+ if (state.timer !== null) cancel(state.timer);
+ state.timer = null;
+ }
+ function show(node, { focus = true } = {}) {
+ const stage = node.getAttribute("data-stage");
+ const stopped = stage === "done" && ["warning", "error"].includes(node.getAttribute("data-tone"));
+ roots.stages?.replaceChildren(...renderStages(doc, stage, { stopped }));
+ roots.view.replaceChildren(node);
+ if (focus) headingOf.get(node)?.focus();
+ }
+ function ingest(entries) {
+ const fresh = list(entries).filter((entry) => Number.isInteger(entry?.seq) && entry.seq > state.lastSeq);
+ for (const entry of fresh) state.lastSeq = Math.max(state.lastSeq, entry.seq);
+ state.entries = [...state.entries, ...fresh].slice(-LOG_LIMIT);
+ return fresh;
+ }
+
+ async function resume() {
+ clearError();
+ let result;
+ try {
+ result = await api("/api/progress?after=0");
+ } catch {
+ showError(noAnswer, resume);
+ return;
+ }
+ if (sessionEnded(result.status)) return showSession();
+ if (result.status !== 200 || !isProgress(result.body)) {
+ showError(noAnswer, resume);
+ return;
+ }
+ ingest(result.body.entries);
+ if (result.body.outcome) return showOutcome(result.body.outcome);
+ if (result.body.running === true) return showProgress();
+ return loadPlan();
+ }
+
+ async function loadPlan(notice = "") {
+ clearError();
+ let result;
+ try {
+ result = await api("/api/plan");
+ } catch {
+ showError(noAnswer, () => loadPlan(notice));
+ return;
+ }
+ if (sessionEnded(result.status)) return showSession();
+ if (result.status === 409 && result.body?.error === "install-running") return showProgress();
+ if (result.status !== 200 || result.body === null || typeof result.body !== "object") {
+ showError("The installer could not check this computer. Check the terminal for details, then try again.", () => loadPlan(notice));
+ return;
+ }
+ state.plan = planModel(result.body);
+ state.steps = state.plan.steps;
+ show(renderPlan(doc, state.plan, { install, reload: () => loadPlan(), close, consentChanged: (checked) => { if (checked) clearError(); } }));
+ if (notice) showError(notice, null, { tone: "warning", title: "Plan updated" });
+ }
+
+ async function install({ consent, checkbox, button }) {
+ if (state.busy) return;
+ const body = installBody(state.plan?.planId, consent);
+ if (body === null) {
+ showError("Check the box to confirm that you reviewed the plan. Nothing was installed.");
+ checkbox.setAttribute("aria-invalid", "true");
+ checkbox.focus();
+ return;
+ }
+ clearError();
+ state.busy = true;
+ button.disabled = true;
+ let result;
+ try {
+ result = await api("/api/install", { method: "POST", body });
+ } catch {
+ // The request may have reached the host before the connection broke: check
+ // once, and follow a running or finished installation instead of offering a retry.
+ const current = await currentProgress();
+ state.busy = false;
+ if (current?.outcome) return showOutcome(current.outcome);
+ if (current?.running) return showProgress();
+ button.disabled = false;
+ showError(noAnswer);
+ return;
+ }
+ state.busy = false;
+ const next = interpretInstall(result.status, result.body);
+ if (next.next === "progress") return showProgress();
+ if (next.next === "reload-plan") return loadPlan(next.message);
+ if (next.next === "outcome") return resume();
+ if (next.next === "session") return showSession();
+ button.disabled = false;
+ showError(next.message, () => loadPlan());
+ }
+
+ /** One GET /api/progress?after=0, or null when the host does not answer usefully. */
+ async function currentProgress() {
+ try {
+ const result = await api("/api/progress?after=0");
+ if (result.status !== 200 || !isProgress(result.body)) return null;
+ ingest(result.body.entries);
+ return { running: result.body.running === true, outcome: result.body.outcome ?? null };
+ } catch {
+ return null;
+ }
+ }
+
+ function progressSnapshot() {
+ return progressModel(state.steps, state.entries, { running: state.running, outcome: state.outcome });
+ }
+
+ function showProgress() {
+ stopPolling();
+ state.running = true;
+ state.poll = initialPoll();
+ state.progress = renderProgress(doc);
+ state.progress.update(progressSnapshot(), state.entries);
+ show(state.progress.node);
+ announce("Installation started.");
+ schedule(state.poll.delay);
+ }
+
+ function schedule(ms) {
+ stopPolling();
+ state.timer = later(() => {
+ state.timer = null;
+ void pollOnce();
+ }, ms);
+ }
+
+ function pollFailed(event) {
+ state.poll = nextPoll(state.poll, event);
+ if (state.poll.stop) return pollStopped();
+ schedule(state.poll.delay);
+ }
+
+ function pollStopped() {
+ const message = state.poll.reason === "stalled"
+ ? "The installer stopped reporting progress. Check the terminal, then try again."
+ : "Lost contact with the installer. Check that the terminal is still running it, then try again.";
+ showError(message, () => {
+ state.poll = initialPoll();
+ schedule(0);
+ });
+ }
+
+ async function pollOnce() {
+ let result;
+ try {
+ result = await api(`/api/progress?after=${state.lastSeq}`);
+ } catch {
+ return pollFailed({ type: "error" });
+ }
+ if (sessionEnded(result.status)) return showSession();
+ if (result.status !== 200 || !isProgress(result.body)) return pollFailed({ type: "error" });
+ const fresh = ingest(result.body.entries);
+ const outcome = result.body.outcome ?? null;
+ state.running = result.body.running === true;
+ state.poll = nextPoll(state.poll, { type: "entries", count: fresh.length, running: state.running, outcome });
+ if (outcome) return showOutcome(outcome);
+ clearError();
+ state.progress?.update(progressSnapshot(), state.entries);
+ const last = fresh.at(-1);
+ if (last) announce(`${stepLabel(last.step)}: ${statusText[last.status] ?? last.status}.`);
+ if (state.poll.stop) return pollStopped();
+ schedule(state.poll.delay);
+ }
+
+ function showOutcome(outcome) {
+ stopPolling();
+ state.outcome = outcome;
+ state.running = false;
+ const model = outcomeModel(outcome);
+ const copy = clipboard ? async (value) => {
+ try {
+ await clipboard.writeText(value);
+ announce("Command copied.");
+ return true;
+ } catch {
+ return false;
+ }
+ } : undefined;
+ show(renderOutcome(doc, model, { close, copy }, state.entries));
+ announce(`${model.title}.`);
+ }
+
+ function showSession() {
+ stopPolling();
+ clearError();
+ show(renderSession(doc));
+ }
+
+ async function close() {
+ if (state.busy) return;
+ state.busy = true;
+ let result;
+ try {
+ result = await api("/api/shutdown", { method: "POST", body: {} });
+ } catch {
+ state.busy = false;
+ showError("The installer did not answer. It may already be closed; check the terminal.");
+ return;
+ }
+ state.busy = false;
+ if (result.status === 200) {
+ stopPolling();
+ clearError();
+ show(renderClosed(doc, state.outcome));
+ announce("Installer closed.");
+ return;
+ }
+ if (sessionEnded(result.status)) return showSession();
+ if (result.status === 409) {
+ showError("An installation is still running. Wait for it to finish, then close the installer.");
+ return;
+ }
+ showError("The installer could not close. Press Ctrl+C in the terminal to stop it.");
+ }
+
+ return { start: resume, state };
+}
+
+if (typeof window !== "undefined" && typeof document !== "undefined" && typeof fetch === "function") {
+ const app = createWizard({
+ document,
+ fetch: (...args) => fetch(...args),
+ setTimeout: (fn, ms) => window.setTimeout(fn, ms),
+ clearTimeout: (id) => window.clearTimeout(id),
+ clipboard: window.navigator?.clipboard ?? null,
+ });
+ void app.start();
+}
diff --git a/bin/gentle-shell-install.mjs b/bin/gentle-shell-install.mjs
new file mode 100644
index 000000000..983387a59
--- /dev/null
+++ b/bin/gentle-shell-install.mjs
@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { spawn as spawnChild } from "node:child_process";
+import * as fsPromises from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, posix, resolve, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { collectInventory, planPreflight } from "../scripts/installer-preflight.mjs";
+import { createProbes, hostAdapters, userEnvironment } from "../scripts/installer-probes.mjs";
+import { packageNativeGentleAi, pnpmInvocation, runStandardInstall } from "../scripts/installer-runner.mjs";
+import { createInstallerServer } from "../scripts/installer-server.mjs";
+
+// Browser installation wizard entry, started by the bootstrap with no argv.
+// Thin wiring only: real probes and adapters, the standard runner and the
+// loopback host. Exit 0 keeps the bootstrap's tools; nonzero removes them.
+
+/** Fixed per-platform browser opener for a local file, spawned with shell:false; null when none. */
+export function openerFor(platform, file, env) {
+ if (platform === "darwin") return { command: "/usr/bin/open", args: [file] };
+ if (platform === "linux") return { command: "xdg-open", args: [file] };
+ if (platform === "win32") {
+ // Absolute path: Windows would otherwise search the current directory first.
+ const systemRoot = env.SystemRoot ?? env.SYSTEMROOT;
+ if (typeof systemRoot !== "string" || !win32.isAbsolute(systemRoot)) return null;
+ return { command: win32.join(systemRoot, "System32", "rundll32.exe"), args: ["url.dll,FileProtocolHandler", file] };
+ }
+ return null;
+}
+
+function escapeHtml(value) {
+ return String(value).replace(/[&<>"']/g, (char) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[char]);
+}
+
+/** Static page that refreshes to the session URL; no script. */
+export function redirectPage(url) {
+ const href = escapeHtml(url);
+ return [
+ "",
+ '',
+ '',
+ ``,
+ "Gentle Shell installation wizard ",
+ `Continue to the Gentle Shell installation wizard
`,
+ "",
+ ].join("\n");
+}
+
+/**
+ * Writes the redirect page into a fresh private directory (0700, file 0600)
+ * under tempDir, so the one-time code never appears in the opener's argv.
+ * remove() is idempotent and best effort: it deletes the file, then the directory.
+ */
+export async function writeRedirect(url, { tempDir = tmpdir(), files = fsPromises } = {}) {
+ const dir = await files.mkdtemp(join(tempDir, "gentle-shell-install-"));
+ const file = join(dir, "open.html");
+ let removed = false;
+ const remove = async () => {
+ if (removed) return;
+ removed = true;
+ await files.unlink(file).catch(() => {});
+ await files.rmdir(dir).catch(() => {});
+ };
+ try {
+ await files.chmod(dir, 0o700);
+ await files.writeFile(file, redirectPage(url), { mode: 0o600, flag: "wx" });
+ } catch (error) {
+ await remove();
+ throw error;
+ }
+ return { dir, file, remove };
+}
+
+/**
+ * Opens url through a private redirect file with the fixed opener (shell:false,
+ * detached). Returns { file, remove } while the file exists, or null when nothing
+ * was opened; a failed opener removes the file. The printed URL stays the fallback.
+ */
+export async function openBrowser(url, { platform = process.platform, env = process.env, tempDir = tmpdir(), files = fsPromises,
+ spawn = spawnChild } = {}) {
+ // Resolve the opener first so no file is written when there is none.
+ if (openerFor(platform, "", env) === null) return null;
+ let redirect;
+ try {
+ redirect = await writeRedirect(url, { tempDir, files });
+ } catch {
+ return null;
+ }
+ const opener = openerFor(platform, redirect.file, env);
+ try {
+ const child = spawn(opener.command, opener.args, { shell: false, detached: true, stdio: "ignore", windowsHide: true });
+ child.once("error", () => {
+ void redirect.remove();
+ });
+ child.unref();
+ } catch {
+ await redirect.remove();
+ return null;
+ }
+ return { file: redirect.file, remove: redirect.remove };
+}
+
+/** 0 only for a completed installation; blocked, failed or none is 1. */
+export function exitCodeFor(outcome) {
+ return ["ready", "terminal-action-required"].includes(outcome?.outcome) ? 0 : 1;
+}
+
+/** The runner's environment: the user's real PATH, so a temporary bootstrap npm
+ * or node never counts as persistent and globalBin.onPath stays truthful. A
+ * POSIX bootstrap pnpm (passed only through PATH) stays reachable as the last
+ * PATH entry; Windows passes pnpm through the GENTLE_INSTALL_PNPM_* handoff.
+ */
+export async function runnerEnvironment({ platform, env, fs }) {
+ const user = userEnvironment({ platform, env });
+ if (platform === "win32" || (await pnpmInvocation(user, platform, fs)) !== null) return user;
+ const wizard = await pnpmInvocation(env, platform, fs);
+ if (wizard === null || wizard.prefix.length > 0) return user;
+ const rest = String(user.PATH ?? "").split(posix.delimiter).filter((entry) => entry.length > 0);
+ return { ...user, PATH: [...rest, posix.dirname(wizard.command)].join(posix.delimiter) };
+}
+
+async function main() {
+ const { platform, arch, env } = process;
+ const { run, fs } = hostAdapters();
+ // The redirect file is removed once the code is redeemed, or when the host closes.
+ let redeemed = false;
+ let redirect = null;
+ const host = createInstallerServer({
+ onRedeemed: () => {
+ redeemed = true;
+ void redirect?.remove();
+ },
+ assetsDir: fileURLToPath(new URL("../assets/install-wizard/", import.meta.url)),
+ collectPlan: async () => {
+ // Fresh probes every time: createProbes caches its global package listing.
+ const inventory = await collectInventory({ platform, arch, probes: createProbes({ platform, env, run, fs }) });
+ return { inventory, plan: planPreflight(inventory) };
+ },
+ runInstall: async (request, log) => runStandardInstall(request, {
+ platform,
+ nodePath: process.execPath,
+ env: await runnerEnvironment({ platform, env, fs }),
+ run,
+ fs,
+ verifyGentleAi: packageNativeGentleAi,
+ log,
+ }),
+ });
+ let started;
+ try {
+ started = await host.listen();
+ } catch {
+ console.error("The installation wizard could not start its local server. Nothing was installed.");
+ process.exitCode = 1;
+ return;
+ }
+ console.log("Gentle Shell installation wizard");
+ console.log(`Open this link in your browser (it works once and expires in 2 minutes):\n ${started.url}`);
+ console.log("Press Ctrl+C to stop the wizard.");
+
+ let signalled = false;
+ const stop = () => {
+ signalled = true;
+ host.close("signal");
+ };
+ process.once("SIGINT", stop);
+ process.once("SIGTERM", stop);
+ const opening = openBrowser(started.url).then((opened) => {
+ redirect = opened;
+ // The printed URL may have been redeemed while the file was being written.
+ if (redeemed) void opened?.remove();
+ return opened;
+ });
+ const { reason, outcome } = await host.closed;
+ process.off("SIGINT", stop);
+ process.off("SIGTERM", stop);
+ await (await opening)?.remove();
+ const code = exitCodeFor(outcome);
+ if (outcome?.guidance) console.log(outcome.guidance);
+ else if (reason === "idle") console.log("The wizard closed after 30 minutes without activity. Nothing was installed.");
+ else console.log("The wizard closed without installing anything.");
+ if (signalled) process.exit(code);
+ process.exitCode = code;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+ main().catch(() => {
+ console.error("The installation wizard stopped unexpectedly.");
+ process.exitCode = 1;
+ });
+}
diff --git a/docs/install-wizard.md b/docs/install-wizard.md
new file mode 100644
index 000000000..0bc0b2ad0
--- /dev/null
+++ b/docs/install-wizard.md
@@ -0,0 +1,1287 @@
+# Installation wizard groundwork
+
+The preflight planner, real host probes, POSIX bootstrap, Windows prerequisite
+foundation, the standard installation runner module (including runtime
+persistence), the secure local wizard host with its packaged entry and the
+interactive browser wizard UI are implemented. Windows native validation
+remains unavailable locally.
+**This is not a supported installation path yet:** published bootstrap
+artifacts, real browsers and native macOS/Windows clean-machine runs are still
+unverified (T7); one Linux clean-container run passed (see
+[Clean-machine acceptance](#clean-machine-acceptance-t7)). For ordinary
+installation and terminal use, follow the [README](../README.md).
+
+## What is available
+
+`scripts/installer-preflight.mjs` exports four small integration surfaces:
+
+| API | Contract |
+| --- | --- |
+| `requirements` | Repository-derived Node/Pi minima, pnpm acquisition pin, package version, native installer pin and Windows Go minimum. |
+| `collectInventory({ platform, arch, probes })` | Calls injected named read-only probes serially. Missing/failed probes become unknown; error text is not retained. |
+| `planPreflight(inventory)` | Pure classification and ordered action intents; no commands, downloads, installation or setup execution. |
+| `pnpmGlobalBin({ platform, env })` | Pure pnpm 11 global-bin resolution: `{ pnpmHome, path, onPath }` or `null` when unknowable. |
+| `persistencePins` | Fixed runtime persisted under PNPM_HOME: Node 24.21.0, its bundled npm 11.19.0 and the pnpm acquisition pin. |
+
+`scripts/installer-probes.mjs` supplies the real read-only probes for
+`collectInventory`; see [Host probes](#host-probes).
+
+Current requirements come from `package.json` and
+[`gentle-ai-installer.mjs`](../scripts/gentle-ai-installer.mjs): Node ≥22.19.0,
+Pi ≥0.99.1, pnpm acquisition 11.1.1, Gentle Shell package 4.0.0 and package-local
+Gentle AI 4.0.0. Windows native source builds require Go ≥1.25.10 when the
+required usable native binary is missing. A reusable binary does not require Go.
+Pins change with the repository; the API reads the metadata rather than copying
+these values into a second installer.
+
+## Probe adapter contract
+
+Supply `platform` as `linux`, `darwin` or `win32`, and `arch` as `x64` or `arm64`.
+These are planning targets, **not evidence of native OS/libc support**. Other
+pairs produce an unsupported-target blocker and no actions. Native lanes,
+minimum OS versions, libc compatibility, artifact trust and elevation handling
+remain to be verified in later units.
+
+Probes are named `node`, `pnpm`, `pi`, `shell`, `gentleAi`, `go`, `globalBin`, and
+`setup`. `collectInventory` has no default probes; the real implementations live
+in [`installer-probes.mjs`](#host-probes). Probes must use bounded read-only
+checks, never launcher setup, postinstall, paid model requests, credential
+inspection or home writes. The collector cannot enforce purity of
+caller-provided functions; adapter implementations require review.
+
+- Tool observations use `{ available: true, version, usable: true }`; absence is
+ `{ available: false }`. Unknown availability, usability or unparseable versions
+ block planning. Versions are exact stable `major.minor.patch` strings (optional
+ `v` prefix); prereleases and raw command output are unknown, not silently reused.
+- Node may add `persistent` (resolvable from the user's PATH without bootstrap
+ tool directories) and `npm` (a genuine npm resolves there) booleans; pnpm
+ may add `persistent` (resolvable from the user's PATH). A `false` value
+ yields the runtime persistence intents below; absent or `null` values add
+ nothing, and the runner's own npm gate still applies.
+- Shell additionally needs `global: true`, proving normal global ownership.
+ Compatible newer Node, Pi and Shell versions are reused, never downgraded.
+- pnpm additionally needs `compatible: true`, based on its actual Node engine and
+ required global-install capabilities. The acquisition pin is not a minimum:
+ newer compatible pnpm is reusable. Do not infer compatibility from its version
+ alone; the later acquisition adapter must validate the pinned engine too.
+- Gentle AI additionally needs `compatible: true`: evidence from the normal
+ package-local binary resolution/integrity contract, for the selected Shell
+ installation. Its exact installer pin is required; another version blocks
+ rather than being overwritten. Do not confuse an unrelated PATH binary with
+ the package's reusable native binary. For a newer reusable Shell, the adapter
+ must establish native-pin compatibility before presenting this evidence.
+- Global-bin observations use `{ available: true, path, writable: true, onPath }`.
+ A known missing PATH entry yields an explicit setup intent. Unknown or
+ non-writable directories block; no directory is created or permission probed
+ by writing. pnpm 11 places global executables in **`$PNPM_HOME/bin`**, not
+ `$PNPM_HOME`, and `pnpm root -g`/`bin -g` fail when that directory is not on
+ PATH. Probes must report `pnpmGlobalBin().path`, whose `onPath` compares PATH
+ entries with that bin directory. PNPM_HOME is the user's existing absolute
+ value; otherwise pnpm's documented default (`$XDG_DATA_HOME/pnpm` or
+ `~/.local/share/pnpm` on Linux, `~/Library/pnpm` on macOS,
+ `%LOCALAPPDATA%\pnpm` on Windows). A relative PNPM_HOME or missing home is
+ unknown, not guessed.
+- `setup` is a boolean evidence of normal Shell setup readiness. Unknown setup
+ on an existing stack blocks; a missing Shell/native binary needs normal setup.
+
+## Reading a plan
+
+Tool statuses distinguish `unavailable`, `unknown`, `incompatible`, `reusable`,
+`needs-setup` and `not-required`. Any blocker suppresses all actions: repairing an
+existing incompatible or uncertain component requires a later explicit decision,
+not automatic replacement. `ready` means no acquisition/setup is indicated by
+this inventory, **not that verification has executed**.
+
+A clean target receives these intents in dependency order:
+
+1. Acquire and verify Node, then pnpm; prepare the usable global-bin environment.
+ Persist only what is missing. A bootstrap-only reusable Node gets the full
+ group, always together: `persist-node` (`persist-runtime`, version
+ 24.21.0), `persist-package-managers` (`install-global`) and
+ `configure-npm-prefix` (`configure`). A persistent Node is never replaced:
+ it gets at most one intent, `persist-npm` (npm 11.19.0) when no genuine
+ npm resolves, `persist-pnpm` (pnpm 11.1.1) when pnpm is bootstrap-only, or
+ `persist-package-managers` when both are missing.
+2. On Windows, acquire and verify Go before missing native provisioning.
+3. Install Pi globally, then `gentle-pi` globally (its existing postinstall owns
+ native installation). For an existing Shell with missing native binary, call
+ the existing installer instead.
+4. Run normal Shell setup and verify stack readiness. Verification is always
+ included, even when all components can be reused.
+
+A recoverable setup (the pinned stack is installed, Gentle AI is verified and
+only setup did not finish) plans exactly `setup-global-bin` (only when the
+global bin is off PATH), `setup-shell` and `verify-readiness`: never an
+acquisition, persistence or installation intent. See
+[Setup recovery](#setup-recovery).
+
+Actions are structured `{ id, kind, target, version? }` descriptors, **not shell
+commands**. Later runners must re-inventory after changes, verify prerequisite
+versions and global-bin readiness before dependent steps, obtain explicit consent
+and stop on mandatory failures. They must preserve existing versions/paths and
+use normal global package ownership and default `~/.gentle-shell/agent` semantics.
+No alternate product root, Engram database/server, credential migration or custom
+companion installer belongs in this plan.
+
+## Remaining boundaries
+
+`npm:` registry sources are package references, not npm executable calls. Pi's
+`npmCommand` supports pnpm, but independent upstream `npm exec` control remains
+unverified. **This preflight does not establish an npm-free installation chain.**
+
+The consent UI is the local wizard host described below. A published
+distribution bundle and native acceptance evidence remain future work in the
+[feature plan](../odd/tasks/browser-install-wizard.md). Deterministic injected
+tests do not prove clean-machine installation on Windows, macOS or Linux.
+
+Focused verification:
+
+```sh
+node --experimental-strip-types --test tests/installer-server.test.ts tests/verify-package-files.test.ts tests/installer-probes.test.ts tests/installer-runner.test.ts tests/installer-preflight.test.ts tests/installer-posix-bootstrap.test.ts tests/installer-windows-bootstrap.test.ts
+sh -n scripts/bootstrap.sh
+```
+
+## Host probes
+
+`scripts/installer-probes.mjs` exports `createProbes({ platform, env, run, fs,
+home?, verifyGentleAi? })`, returning the eight named probes for
+`collectInventory`. `env` is the wizard's own environment, with bootstrap tools
+first on PATH. Every probe returns the documented shape or the unknown shape
+`{ available: null }`; adapter errors are caught and never retained.
+
+| Export | Contract |
+| --- | --- |
+| `bootstrapRoots({ platform, env })` | Bootstrap tool roots: an absolute `GENTLE_BOOTSTRAP_TOOLS` plus every PATH entry segment named `.gentle-shell-bootstrap-tools.*` (case-insensitive on Windows). |
+| `userEnvironment({ platform, env })` | A copy of `env` whose PATH omits entries inside those roots: the user's real PATH. |
+| `hostAdapters({ maxOutputBytes?, maxTextBytes? })` | Real `run` and read-only `fs` adapters, described below. |
+
+Adapters:
+
+- `run(command, argv, { env, deadlineMs })` is the runner's process contract:
+ argv arrays with `shell:false`, SIGKILL at the deadline and stdout bounded
+ to `maxOutputBytes` (default 1 MiB, reported as `truncated: true`). stderr
+ is discarded because it can hold private paths, unless the caller passes
+ `stderrTail: ` (a positive integer, clamped to 4 KiB): then stderr is
+ piped and only its last bytes are kept and returned as `stderrTail`, also on a
+ deadline. Only the runner's `shell-setup` and `persist-path` steps ask for it. A spawn failure returns
+ `code: null`. The deadline signals the direct child only, not descendants;
+ it then destroys the child's pipes and settles as timed out (`code: null`,
+ `signal: "SIGKILL"`) without waiting for `close`, which a descendant holding
+ stdout could otherwise delay indefinitely.
+- `fs` offers `isFile`, `isDirectory`, `exists` (only ENOENT/ENOTDIR are
+ absent), `realpath`, `readText` (regular files up to `maxTextBytes`) and
+ `writable` (an access check, never a write). No probe creates, deletes or
+ writes anything.
+
+Probes run only fixed argv: `node --version`, `pnpm --version`,
+`pnpm list -g --depth 0 --json` (once, shared), `go version` and npm's
+`npm-cli.js --version`. Deadlines are 10 seconds for versions and 30 seconds for
+the listing; truncated, nonzero, signalled or timed-out output is unknown.
+
+| Probe | Evidence |
+| --- | --- |
+| `node` | The first `node` on the user's real PATH (Go `exec.LookPath` order, PATHEXT on Windows), else the bootstrap one. `persistent` says which. `npm` is the runner's genuine-npm proof in the user's real PATH with `$PNPM_HOME/bin` first, so a bootstrap npm never counts. A Windows `.cmd`/`.bat` cannot run with `shell:false` and is unknown. |
+| `pnpm` | The runner's invocation (bootstrap handoff, or a POSIX `pnpm` on PATH). `compatible` requires a successful run (pnpm checks its Node engine at startup) at the pinned major and at least the pin, because the runner's argv is verified for pnpm 11 only. `persistent` is whether any `pnpm` resolves on the real PATH. |
+| `pi`, `shell` | pnpm-global entries from the listing. A package that is not pnpm-global but whose command (`pi`, `gentle-shell`) resolves on the real PATH is unknown, never absent, so another installation is not duplicated. Shell is `usable` only when `$PNPM_HOME/bin/gentle-shell` (`.cmd` on Windows) exists. |
+| `gentleAi` | Absent without gentle-pi or without its package-native binary. Otherwise compatible only for this package version, a listed path that resolves inside PNPM_HOME and `verifyGentleAi` (default `packageNativeGentleAi`) success; anything else is unknown. |
+| `go` | `go version` from the real PATH; `go1.22` normalizes to `1.22.0`; devel and release-candidate builds are unknown. |
+| `globalBin` | `pnpmGlobalBin` over the real PATH; `writable` is write access on the nearest existing ancestor of `$PNPM_HOME/bin` (itself included). A non-directory ancestor is not writable. |
+| `setup` | `false` when gentle-pi is absent. `{ available: true, recoverable: true }` for the pinned stack this pnpm installed (see [Setup recovery](#setup-recovery)), using the runner's `recoverableStackRoot`. Unknown otherwise, because an existing Shell's setup readiness has no read-only evidence. |
+
+A failed, empty or unparseable listing makes Pi, Shell, Gentle AI and setup
+unknown, which blocks planning. A package listed in two projects is ambiguous
+and unknown.
+
+## Standard installation runner
+
+`scripts/installer-runner.mjs` exports `runStandardInstall({ plan, consent },
+adapters)`, the fixed installation step the local wizard host
+(`bin/gentle-shell-install.mjs`, below) calls after bootstrap and a fresh
+preflight. It is a pure module: every process, filesystem,
+environment, integrity and log effect goes through adapters supplied by trusted
+local code, never through the browser.
+
+### Request contract
+
+The request is exactly `{ plan, consent }`. `plan` must be an unmodified
+`planPreflight` result: every action must equal a descriptor preflight can emit
+(same id, kind, target and repository-derived version, no extra keys). Extra
+request keys, commands, URLs, roots, environment or altered versions are
+rejected as `invalid-request` before any process runs. `consent` must be the
+boolean `true`; anything else returns `consent-required` with no commands. The
+consent covers the whole displayed plan, including the PATH profile change and
+the runtime persistence and npm prefix actions below, so the wizard must show
+those changes before asking.
+
+### Adapters
+
+| Adapter | Contract |
+| --- | --- |
+| `platform` | `linux`, `darwin` or `win32`. |
+| `nodePath` | Absolute Node executable of the trusted host, used for npm proof and `gentle-shell setup`. |
+| `env` | The user's environment. Never mutated; child environments are copies. |
+| `home` | Optional; defaults to `HOME` (`USERPROFILE` on Windows). |
+| `run(command, argv, { env, deadlineMs })` | Argv arrays with `shell:false` semantics and a hard deadline; returns `{ code, signal, timedOut, stdout }` with bounded output. |
+| `fs` | Read-only `isFile`, `realpath`, `readText` (also used to read pnpm's npm shim). The runner has no delete or write operation. |
+| `verifyGentleAi({ packageRoot, platform, env, home })` | Returns `{ ok: true }` only for package-native integrity. `packageNativeGentleAi` is the default implementation over `runtime/gentle-ai-binary.mjs`. |
+| `log({ step, status, reason? })` | Receives step identifiers and statuses only, never raw command output or error text. |
+
+### Fixed sequence
+
+No-process gates, all returning `blocked`:
+
+1. Valid request and explicit consent.
+2. Preflight blockers are absent. Two plans are supported. The clean-stack
+ plan must contain `install-pi`, `install-shell`, `setup-shell` and
+ `verify-readiness`, plus optional `setup-global-bin` and at most one exact
+ persistence variant: `persist-node` + `persist-package-managers` +
+ `configure-npm-prefix`, or `persist-package-managers` alone, or
+ `persist-npm` alone, or `persist-pnpm` alone. The
+ [setup recovery](#setup-recovery) plan is exactly `setup-shell` and
+ `verify-readiness`, plus optional `setup-global-bin`, and nothing else.
+ Prerequisite acquisition intents (Node, pnpm, Go), `provision-native`, any
+ other persistence combination, other partial existing stacks and fully
+ reused stacks are `unsupported-plan`.
+3. On Windows, Go must be `reusable` in a clean-stack plan because gentle-pi's
+ postinstall may build Gentle AI from source; the runner never acquires Go
+ (`go-required`). A recovery runs no postinstall, so it needs no Go.
+4. `pnpmGlobalBin` resolves PNPM_HOME (`pnpm-home-unknown` otherwise) and
+ `nodePath` is absolute.
+5. pnpm comes from the bootstrap handoff `GENTLE_INSTALL_PNPM_NODE` +
+ `GENTLE_INSTALL_PNPM_ENTRY` (both absolute), or on POSIX from a `pnpm`
+ executable on PATH. Windows requires the handoff because a `.cmd` shim cannot
+ run with `shell:false` (`pnpm-unavailable`).
+
+Every child process receives the user's environment plus `PNPM_HOME` and
+`$PNPM_HOME/bin` first on PATH.
+
+Pre-install checks, returning `blocked` on a false result or adapter error:
+
+1. `check-npm`: Gentle AI's normal Pi install always runs an Engram init step
+ that can use `npm exec` and stops on failure. The runner resolves `npm` the
+ way Go's `exec.LookPath` (used by Gentle AI) does: absolute child PATH
+ directories in order and, on Windows, every child PATHEXT extension in
+ PATHEXT order (case-insensitive keys; default `.COM;.EXE;.BAT;.CMD`). That
+ first candidate must be the npm package's own `bin/npm-cli.js` (symlink
+ target on POSIX; on Windows the candidate must be `npm.cmd`, with
+ `node_modules/npm` beside it), its `package.json` must name `npm` with a
+ stable version, and `node npm-cli.js --version` must print that version.
+ A candidate in `$PNPM_HOME/bin` must instead be pnpm's global npm: a POSIX
+ symlink, or a shim whose single quoted `npm-cli.js` target (`$basedir/...`
+ on POSIX, `%~dp0\...` or `%dp0%\...` on Windows, or absolute), must
+ resolve (realpath) to `node_modules/npm/bin/npm-cli.js` inside PNPM_HOME,
+ and the package must be exactly `npm@11.19.0`. Two different targets, a
+ target outside PNPM_HOME or another version are rejected. When the plan
+ adds npm, this check runs after the add and fails as a mutating step. On
+ Windows an `npm.com`, `npm.exe` or `npm.bat` that resolves first, in the
+ same or an earlier directory, blocks as `npm-shadowed`; any other mismatch
+ blocks as `npm-unavailable`. No npm wrapper is created.
+2. `check-global-bin`: `pnpm bin -g` must succeed and equal `$PNPM_HOME/bin`
+ (`global-bin-mismatch`; case-insensitive on Windows).
+3. `check-existing-stack`: `pnpm list -g --depth 0 --json` runs before any
+ mutation. If `@earendil-works/pi-coding-agent` or `gentle-pi` appears in the
+ dependencies, devDependencies or optionalDependencies of any listed project,
+ the runner blocks as `existing-stack` and never overwrites it, whatever the
+ caller's plan says. A failed, timed-out or unparseable listing, or an
+ unexpected JSON shape, blocks as `global-list-unavailable`. A recovery runs
+ `check-recoverable-stack` instead (see [Setup recovery](#setup-recovery)).
+
+Mutating and verification steps, returning `failed` with `failedStep` and the
+`completed` step list. When the plan contains a persistence variant, its
+[runtime persistence](#runtime-persistence) steps run first, after
+`check-global-bin` and `check-existing-stack`:
+
+1. `install-global`: exactly one
+ `pnpm add -g @earendil-works/pi-coding-agent@1.0.0 gentle-pi@ --allow-build=gentle-pi`.
+ Pi is gentle-pi's optional peer, so both resolve in one command. pnpm 11
+ silently skips global postinstall scripts by default; the package-scoped
+ approval runs only gentle-pi's postinstall, which provisions Gentle AI. No
+ blanket build approval is ever passed.
+2. `verify-global-list`: `pnpm list -g --depth 0 --json` must report exactly the
+ two pinned versions in the single listed project that owns gentle-pi
+ (other projects, such as the persisted npm and pnpm, are ignored), and
+ gentle-pi's absolute `path` must resolve inside PNPM_HOME.
+3. `verify-shell-bin`: `$PNPM_HOME/bin/gentle-shell` (`gentle-shell.cmd` on
+ Windows) exists.
+4. `verify-gentle-ai`: package-native integrity of the installed package. A
+ declared development override (`GENTLE_PI_GENTLE_AI_DEV_BINARY` or its
+ registration file) is never package-native proof and fails.
+5. `shell-setup`: the installed public CLI, `node /bin/gentle-shell.mjs
+ setup`, with the child environment minus every `GENTLE_BOOTSTRAP_*` and
+ `GENTLE_INSTALL_*` key (case-insensitive on Windows); pnpm commands keep the
+ handoff. Nonzero, signal or deadline fails. The runner neither duplicates
+ setup logic nor writes the automatic provisioning marker. It requests the
+ last 4 KiB of setup's stderr, where `gentle-shell setup` reports errors, and
+ a failure carries `detail`: the last error line (containing `Error:` or a
+ pnpm `ERR_` code), else the last non-empty line, without terminal escapes,
+ control or bidi characters, with the user's home replaced by `~` and at most
+ 300 characters (`setupErrorDetail`). The raw output is not kept; only this
+ step and `persist-path` have a detail.
+6. `persist-path`, only when `$PNPM_HOME/bin` was not on the user's own PATH:
+ `pnpm setup`, then the outcome is `terminal-action-required` with
+ `action: "open-new-terminal"`. A child environment never proves that a fresh
+ terminal resolves `gentle-shell`. On POSIX, `pnpm setup` picks the profile
+ to edit from the inherited `SHELL` variable (bash, zsh, fish, ksh, dash, sh
+ or nushell); without it pnpm 11.1.1 fails with `ERR_PNPM_UNKNOWN_SHELL`,
+ with another shell `ERR_PNPM_UNSUPPORTED_SHELL`. A terminal session always
+ exports `SHELL`; a launcher that does not (for example `docker exec`, some
+ service managers or IDE tasks) makes this step fail. pnpm prints these
+ errors on stdout, so a failure takes `detail` from the same 4-KiB stderr
+ tail or, when that has no line, from stdout. Before checking the shell, the
+ observed pnpm 11.1.1 also installs the latest `@pnpm/exe` globally ("Installing
+ pnpm CLI globally"), which is upstream behavior the runner does not control.
+
+`ready` requires every step above to complete and the global bin to already be
+on the user's PATH. Skipped, unverified or failed mandatory steps never yield
+`ready`, and no existing installation, home or data is deleted on any outcome.
+Deadlines are 30 seconds for probes and npm config commands, and 20 minutes
+each for the install, persistence and setup steps, including `pnpm setup`,
+which installs `@pnpm/exe` from the registry.
+
+### Setup recovery
+
+`gentle-shell setup` runs after `add -g`, so a setup that stops (for example on
+the [GitHub API limit](#github-api-limit-during-setup)) or a failed `pnpm setup`
+leaves Pi and gentle-pi installed. Rerunning the installer then completes that
+installation instead of blocking as an existing stack.
+
+Detection is the setup probe, with the same rule the runner applies
+(`recoverableStackRoot`): the global listing names Pi and gentle-pi exactly
+once each, both in the single project that owns gentle-pi, Pi at exactly
+1.0.0 and gentle-pi at exactly this package's version, and gentle-pi's path
+resolves (realpath) inside PNPM_HOME. Preflight also requires Pi, Shell and
+Gentle AI to be `reusable`. Anything else (another version, a second listing,
+a path outside PNPM_HOME, Pi missing) keeps the setup probe unknown, so a
+foreign or other-version stack stays blocked exactly as before.
+
+The recovery plan is all or nothing: `setup-shell`, `verify-readiness` and
+`setup-global-bin` only when the global bin is off PATH. The runner then runs
+`check-npm`, `check-global-bin` and `check-recoverable-stack`, which lists the
+global packages again and blocks as `existing-stack-unverified` when the stack
+no longer matches (or as `global-list-unavailable` when pnpm cannot list).
+It skips `install-global` (never `add -g`) and continues with the unchanged
+`verify-global-list`, `verify-shell-bin`, `verify-gentle-ai`, `shell-setup`
+and, when planned, `persist-path`, with the same outcomes. A recovery never
+persists the runtime: the earlier run persisted it before installing the
+stack, and `check-npm` still proves a genuine npm in the child environment.
+
+Rerunning `gentle-shell setup` is acceptable because it is the public,
+rerunnable command the clean installation already runs; the runner adds no
+setup logic of its own. The review screen says "Gentle Shell is already
+installed; this completes setup" and offers **Complete setup**.
+
+### Runtime persistence
+
+A bootstrap-acquired Node lives in a temporary tools directory, so a later
+terminal would not find `node` or the genuine npm that Gentle AI's Engram step
+needs. Every persistence step uses the same pnpm argv prefix and child
+environment as the stack install, and the runner persists only what is missing.
+
+For a bootstrap-only Node, the full group runs these fixed steps:
+
+1. `persist-node`: `pnpm runtime set node 24.21.0 -g`, which installs Node under
+ PNPM_HOME and links `node` into `$PNPM_HOME/bin`.
+2. `persist-package-managers`: `pnpm add -g npm@11.19.0 pnpm@11.1.1`, which
+ adds the `npm`, `npx` and `pnpm` shims to `$PNPM_HOME/bin`. No build
+ approval of any kind is passed.
+3. `verify-persistent-runtime`: in the child environment both `node` and `npm`
+ must resolve (`exec.LookPath` order) from `$PNPM_HOME/bin`, the node must be
+ spawnable (`.exe`/`.com` on Windows) and print `v24.21.0`.
+4. `check-npm`: the genuine-npm gate above, now accepting the pinned shim.
+5. `configure-npm-prefix`: with a pnpm-managed node, npm's default prefix is
+ derived from a path inside pnpm's store, so `npm install -g` would write
+ there. The runner reads `npm config get prefix` with the persisted node.
+ Unless an `npm_config_prefix` (any case) or `PREFIX` variable is set, it
+ asks pnpm for its store with `pnpm store path` (30-second deadline); a
+ failed, non-absolute or unresolvable answer fails this step rather than
+ assuming `$PNPM_HOME/store`. Only when the effective prefix resolves inside
+ that store does it run
+ `npm config set prefix --location=user`, then require the
+ effective prefix to equal PNPM_HOME. An explicit user prefix elsewhere
+ makes npm report that prefix, so it is never overwritten. A failed read,
+ write or verification fails this step with the completed list.
+
+The outcome then also reports `npmPrefix: "configured"` or `"unchanged"`.
+
+A persistent Node is never replaced or shadowed: there is no `runtime set` and
+no prefix change. One fixed add runs, then only the matching checks:
+
+| Intent | Command | Then |
+| --- | --- | --- |
+| `persist-npm` | `pnpm add -g npm@11.19.0` | `check-npm` |
+| `persist-pnpm` | `pnpm add -g pnpm@11.1.1` | `verify-persistent-pnpm` |
+| `persist-package-managers` | `pnpm add -g npm@11.19.0 pnpm@11.1.1` | `check-npm`, `verify-persistent-pnpm` |
+
+`check-npm` is the genuine-npm gate above. `verify-persistent-pnpm` requires
+the first `pnpm` in the child environment to be in `$PNPM_HOME/bin` (`.cmd`
+on Windows), resolving like the npm shim to `node_modules/pnpm/bin/pnpm.mjs`
+inside PNPM_HOME, with `package.json` `pnpm@11.1.1`, and `node pnpm.mjs
+--version` printing `11.1.1`. When pnpm is not added, `check-npm` stays a
+pre-install gate.
+`npm config get` ignores `--location`, and `.npmrc` files can hold credentials,
+so the runner never reads them: a user-level prefix that itself points into
+the store is indistinguishable from the default and would be replaced.
+
+### Remaining T7 real-machine checks
+
+The runner is verified only with deterministic fake adapters. Observed pnpm
+11.1.1 facts come from one Linux laboratory run. Before claiming support, T7
+must establish on real Windows, macOS and Linux machines:
+
+- `pnpm list -g --json` reports a dependency `path` that resolves inside
+ PNPM_HOME for the installed layout, and prints a parseable JSON array (for
+ example `[]`) when no global package exists yet; empty output would block
+ a clean installation as `global-list-unavailable`;
+- Windows npm resolution matches Gentle AI's actual lookup, including its
+ current-directory handling;
+- the scoped `--allow-build=gentle-pi` postinstall provisions package-native
+ Gentle AI, including Windows source builds with the user's Go;
+- `gentle-shell setup` completes the Engram init step with genuine npm, and
+ whether Gentle AI selects `pnpm dlx` or `npm exec`;
+- `pnpm setup` makes `gentle-shell` resolvable in a fresh terminal of each
+ supported shell (the Linux lab showed it does not make `pnpm` itself
+ resolvable);
+- the chosen deadlines suffice on slow networks, and pnpm's registry and
+ update-notice traffic is acceptable;
+- interrupted installs are recoverable by rerunning the wizard without data loss;
+- `pnpm runtime set node -g` on Windows links a spawnable `node.exe` (a `.cmd`
+ shim fails `verify-persistent-runtime`), and pnpm's real `npm.cmd`/POSIX
+ shim text matches the accepted target forms;
+- npm's Windows global layout: it places executables in the prefix itself, so
+ a PNPM_HOME prefix may not put `npm install -g` executables on PATH; also
+ whether Windows npm's default prefix lands in the store at all;
+- `pnpm store path` reports a directory (for example `$PNPM_HOME/store/v11`)
+ that actually contains the effective npm prefix of a pnpm-managed node;
+- pnpm's real global `pnpm` shim targets `node_modules/pnpm/bin/pnpm.mjs`, and
+ a persistent Node missing npm has a prefix outside the store (the variant
+ without `runtime set` configures no prefix);
+- download integrity of the Node runtime and the npm and pnpm tarballs fetched
+ during persistence (the Linux lab saw a lockfile hash matching the Node pin,
+ not download-time verification);
+- pnpm's update notifier contacting registry.npmjs.org during these commands;
+- `pnpm list -g --json` listing persisted npm/pnpm and the stack as separate
+ projects with a usable gentle-pi `path`;
+- the probes' `access(W_OK)` writability check, which ignores Windows ACLs, and
+ process deadlines that kill only the direct child.
+
+## Local wizard host and entry
+
+`bin/gentle-shell-install.mjs` is the entry the bootstrap's `launchWizard`
+starts with no argv and inherited stdio. It is not a `package.json` `bin`
+command; it ships inside the package's `bin/` directory and is listed in
+`scripts/verify-package-files.mjs` with the other installer files
+(`installerPaths`).
+
+### Entry wiring
+
+- Probes: `createProbes` over the wizard's own environment with
+ `hostAdapters()` (argv spawn with `shell:false`, deadlines, bounded output,
+ read-only fs). Each plan request creates fresh probes, then
+ `collectInventory` and `planPreflight` run server-side.
+- Runner: `runStandardInstall` with `nodePath: process.execPath`, the same
+ adapters, `packageNativeGentleAi` and `runnerEnvironment`: the user's real
+ PATH from `userEnvironment`, so a temporary bootstrap npm or node never counts
+ as persistent and `onPath` stays truthful. A POSIX bootstrap pnpm, which the
+ bootstrap passes only through PATH, stays reachable as the **last** PATH
+ entry (its directory holds only the `pnpm` wrapper); Windows uses the
+ `GENTLE_INSTALL_PNPM_*` handoff, which `userEnvironment` keeps.
+- The entry prints the session URL, then opens it through a private redirect
+ file so the one-time code never appears in the opener's argv (visible to
+ local process listings). `writeRedirect` creates a fresh `mkdtemp` directory
+ `gentle-shell-install-*` under the OS temp dir (mode 0700) holding
+ `open.html` (mode 0600, exclusive create): a static page with a meta refresh
+ and a link to the session URL, no script. `openBrowser` passes only that file
+ path to a fixed opener spawned with `shell:false` and detached:
+ `/usr/bin/open` on macOS, `xdg-open` on Linux, `%SystemRoot%\System32\rundll32.exe
+ url.dll,FileProtocolHandler` on Windows (absolute, so the current directory is
+ never searched). Without an opener nothing is written; a failed write opens
+ nothing; an opener that fails to start removes the file. The file and its
+ directory are removed (file, then directory, best effort) once the code is
+ redeemed (`onRedeemed`) or when the host closes. File modes are POSIX only;
+ on Windows the per-user `%TEMP%` ACLs apply. The printed URL stays the
+ fallback.
+
+| Exit code | When |
+| --- | --- |
+| 0 | The last installation outcome was `ready` or `terminal-action-required`. Node, npm and pnpm now persist under `$PNPM_HOME` or were already the user's, so the bootstrap removes the tools directory it created. |
+| 1 | `blocked`, `failed`, a shutdown or idle close without a completed installation, a signal, or a host start failure. The bootstrap removes its tools. |
+
+SIGINT and SIGTERM close the server and exit with the code above. An
+installation that is still running is not cancelled cleanly: Ctrl+C reaches the
+runner's children through the terminal's process group, but SIGTERM does not.
+
+Known debt, not fixed yet: on SIGINT or SIGTERM, `close` does not wait for a
+running installation to settle, and runner deadlines kill only the direct child
+process, not the processes it started (for example, the ones `pnpm` or
+`gentle-shell setup` spawn).
+
+### Security model
+
+`scripts/installer-server.mjs` exports `createInstallerServer({ collectPlan,
+runInstall, assetsDir, now?, random?, limits?, onRedeemed? })`, a
+dependency-free `node:http` host. Every effect is injected; tests use fake
+plans and runners. `onRedeemed()` runs once when the one-time code is used; an
+exception from it is ignored.
+
+- Binds `127.0.0.1` on port 0 only and asserts the bound IPv4 address; never
+ `localhost`, `::` or `0.0.0.0`.
+- Every request needs `Host` exactly `127.0.0.1:`, otherwise 421 before
+ any authorization (a missing Host included).
+- Every response carries `Content-Security-Policy: default-src 'self';
+ frame-ancestors 'none'; base-uri 'none'; form-action 'none'`,
+ `X-Content-Type-Options: nosniff`, `Cache-Control: no-store`,
+ `Referrer-Policy: no-referrer`, `X-Frame-Options: DENY`,
+ `Cross-Origin-Resource-Policy: same-origin` and
+ `Cross-Origin-Opener-Policy: same-origin`. No CORS header is ever sent; error
+ bodies are generic codes such as `{ "error": "forbidden" }`.
+- Session: a 32-byte random secret becomes the cookie
+ `gentle_install_session` (`HttpOnly; SameSite=Strict; Path=/`). The printed
+ URL `http://127.0.0.1:/session?code=` carries a separate random
+ one-time code that expires after 2 minutes; a valid `GET /session` consumes it
+ and answers 200 with a minimal HTML page that sets the cookie and refreshes
+ to `/` (``, no script or
+ style, same strict headers). It is not a 303: reached from the `file:`
+ redirect page, a redirect chain counts as cross-site and the
+ `SameSite=Strict` cookie could be withheld on `/`, while a navigation started
+ by this same-origin page carries it. Code and cookie comparisons use
+ `timingSafeEqual`. Every asset and `/api/*` request needs the cookie (401).
+- A request with an `Origin` other than `http://127.0.0.1:` is rejected
+ (403), including GET. Every `/api/*` request, GET included, needs the header
+ `X-Gentle-Install: 1` (403 otherwise, before any probe or plan rotation), so
+ a cross-origin fetch always needs a CORS preflight, which never succeeds.
+ POST also requires that exact Origin and `Content-Type: application/json`
+ (415 otherwise).
+- Bodies are limited to 1 KiB (413, by declared length and while streaming).
+ Server `headersTimeout` is 10 s and `requestTimeout` 30 s.
+- The host closes after 30 minutes without activity while no installation
+ runs (`limits.idleMs`, checked every 15 s with the injected clock). Only a
+ request with the right Host and a valid session cookie, a successful code
+ redemption or a finished installation counts as activity; wrong-Host,
+ unauthenticated or bad-code traffic never extends the timeout.
+
+### Endpoints
+
+Fixed allowlist, matched on the raw request path: anything else is 404, a
+known path with another method is 405. Only `/session` and `/api/progress`
+take a query string. Assets map to fixed file names in `assetsDir`; no request
+path reaches the filesystem, so traversal forms (`/../`, `%2e%2e`, `%2f`) are
+simply unknown paths.
+
+| Route | Contract |
+| --- | --- |
+| `GET /session?code=` | Consumes the one-time code, sets the cookie and returns 200 `text/html` that refreshes to `/`; 401 for a missing, wrong, used or expired code. |
+| `GET /`, `/wizard.js`, `/wizard.css` | `index.html`, `wizard.js`, `wizard.css` from `assetsDir`; 404 when absent. |
+| `GET /api/plan` | Runs `collectPlan()` server-side, stores the plan under a new opaque `planId` and returns a view model: `actions` (`id` plus a fixed English description), `blockers` (`code`, `tool` — a preflight tool key such as `node` or `gentleAi`, otherwise `unknown` — and guidance), `profileChange` (whether `pnpm setup` edits the shell profile or Windows user PATH, and the bin directory), `persistence` (which of node, npm and pnpm go under `$PNPM_HOME`) and `ready`. 409 while installing. Accepts no input. |
+| `POST /api/install` | Body exactly `{ "planId": string, "consent": true }` (400 otherwise, including extra keys or a plan). 409 `install-running` while an installation runs; 409 `already-completed` once an installation has a final outcome (one installation per wizard run; the outcome is never replaced); 409 `plan-changed` for a stale `planId` or when a fresh re-inventory differs from the stored plan. Otherwise 202, and the runner receives the server-stored plan with `consent: true`. |
+| `GET /api/progress?after=` | Entries `{ seq, step, status, reason }` after `seq` from a ring buffer of the last 200; values outside `[a-z][a-z0-9-]*` become `unknown`, and no other runner field is kept. Also `running` and the final `outcome` with fixed guidance. |
+| `POST /api/shutdown` | Body empty or `{}`. Closes the host (409 while installing). |
+
+`guidance` (exported) holds fixed English text for every runner blocked
+reason, every failed step, every preflight blocker code and both successful
+outcomes, plus a generic fallback; a runner exception becomes a `failed`
+outcome with the fallback. A failed `shell-setup` or `persist-path` outcome also passes the
+runner's `detail` through, bounded again (string only, control and bidi
+characters removed, at most 300 characters); the host drops it for any other
+step. When that detail names GitHub's rate limit (`rate limit`, or `GitHub API`
+together with `403`), the guidance becomes `guidance.setupRateLimit`: GitHub's
+anonymous API limit was reached on this network, wait up to an hour and run the
+installer again. No token or credential is ever requested. For `persist-path`,
+a detail with `ERR_PNPM_UNKNOWN_SHELL` or `ERR_PNPM_UNSUPPORTED_SHELL` selects
+`guidance.persistPathShell`: open a regular terminal and run the installer
+again, or add `$PNPM_HOME/bin` to PATH manually. `scripts/installer-runner.mjs` exports the frozen
+arrays `blockedReasons` and `failedSteps`; a test requires guidance for exactly
+those entries, and the runner tests check that every reason and step their
+scenarios observe is listed.
+
+### Wizard UI
+
+`assets/install-wizard/index.html`, `wizard.js` (an ES module) and
+`wizard.css` are the whole browser side. They load only from the host itself
+and follow its CSP: no inline script or style, no external fonts, images or
+requests, and server strings are inserted as text nodes only (never parsed as
+HTML).
+
+| Screen | What the user sees |
+| --- | --- |
+| Check | Shown while `GET /api/progress?after=0` and `GET /api/plan` run. A running installation resumes the Install screen; a finished one shows its outcome instead of a new plan. |
+| Review | Each fixed action with its description, the `profileChange` and `persistence` disclosures (state as text: "Will change", "No change"), one consent checkbox and **Install Gentle Shell** (for a setup recovery, "Finish setting up Gentle Shell" and **Complete setup**). Without the checkbox no request is sent; the error is announced and focus moves to the checkbox. Preflight blockers replace the plan with their guidance, **Check again** and **Close installer**. |
+| Install | Expected runner steps (`expectedSteps`) with a text status (Done, In progress, Pending, Failed, Blocked, Not run), a `