gentle-pi 4.0.0 → 4.2.0

package/scripts/test-installer-acceptance.sh

@@ -0,0 +1,161 @@
+#!/bin/sh
+# Opt-in Linux clean-machine acceptance for the browser installation wizard.
+# Runs the real bootstrap and wizard inside a disposable debian:bookworm-slim
+# container as a non-root user. Network access happens only inside that
+# container; nothing reads or writes the host HOME. Not part of CI.
+#
+# Usage: sh scripts/test-installer-acceptance.sh [--worktree]
+#   default     bundle = `git archive HEAD`
+#   --worktree  bundle = tracked files as they are in the working tree,
+#               including uncommitted modifications (untracked files excluded)
+# GENTLE_ACCEPTANCE_KEEP=1 keeps a failed run's container for inspection.
+set -eu
+fail() { printf 'acceptance: %s\n' "$1" >&2; exit 1; }
+note() { printf 'acceptance: %s\n' "$1"; }
+source_mode='head'
+case $# in
+    0) ;;
+    1) [ "$1" = --worktree ] || fail "unknown argument: $1"; source_mode=worktree;;
+    *) fail 'usage: sh scripts/test-installer-acceptance.sh [--worktree]';;
+esac
+image=debian:bookworm-slim
+# Upper bound for the whole installation inside the container.
+install_limit=${GENTLE_ACCEPTANCE_INSTALL_SECONDS:-1500}
+case $install_limit in ''|*[!0-9]*) fail 'GENTLE_ACCEPTANCE_INSTALL_SECONDS must be a whole number';; esac
+command -v docker >/dev/null 2>&1 || fail 'Docker is required; refusing to run anything on the host'
+docker info >/dev/null 2>&1 || fail 'Docker daemon is unavailable; refusing to run anything on the host'
+command -v git >/dev/null 2>&1 || fail 'git is required to package the bundle'
+repo=$(git rev-parse --show-toplevel) || fail 'run from inside the repository'
+started=$(date +%s)
+elapsed() { printf '%ss' "$(( $(date +%s) - started ))"; }
+name=gentle-install-acceptance-$$-$started
+container=
+passed=0
+cleanup() {
+    if [ -n "$container" ] && [ "$passed" = 0 ] && [ "${GENTLE_ACCEPTANCE_KEEP:-}" = 1 ]; then
+        printf 'acceptance: kept %s; inspect with: docker exec -it -u tester %s bash; remove with: docker rm -f %s\n' "$container" "$container" "$container" >&2
+    elif [ -n "$container" ]; then
+        docker rm -f "$container" >/dev/null 2>&1 || printf 'acceptance: could not remove container %s\n' "$container" >&2
+    fi
+}
+trap cleanup EXIT
+trap 'exit 1' HUP INT TERM
+
+note "image $image, bundle from $source_mode"
+docker run -d --name "$name" --pull missing "$image" sleep infinity >/dev/null || fail 'cannot start the container'
+container=$name
+# Clean machine: no Node, npm, pnpm, Pi or Gentle Shell. curl and CA roots are
+# bootstrap prerequisites that a stock Debian desktop already has.
+docker exec "$container" sh -c 'export DEBIAN_FRONTEND=noninteractive
+    apt-get update -qq >/dev/null && apt-get install -y -qq --no-install-recommends ca-certificates curl >/dev/null
+    useradd --create-home --shell /bin/bash tester
+    mkdir /opt/bundle
+    for tool in node npm pnpm pi gentle-shell; do if command -v "$tool" >/dev/null; then echo "unexpected $tool" >&2; exit 1; fi; done' \
+    || fail 'container preparation failed'
+# gentle-shell setup makes 2 anonymous GitHub API requests (upstream Gentle AI's
+# latest-engram lookup), limited to 60 per hour per public IP. /rate_limit does
+# not consume quota. Stop early instead of failing deep inside setup.
+quota=$(docker exec "$container" sh -c 'curl -fsS --max-time 20 -H "Accept: application/vnd.github+json" https://api.github.com/rate_limit' | tr -d ' \n') \
+    || fail 'cannot query the GitHub API rate limit from the container'
+rate=$(printf '%s' "$quota" | sed -n 's/.*"rate":{\([^}]*\)}.*/\1/p')
+remaining=$(printf '%s' "$rate" | sed -n 's/.*"remaining":\([0-9]*\).*/\1/p')
+reset=$(printf '%s' "$rate" | sed -n 's/.*"reset":\([0-9]*\).*/\1/p')
+[ -n "$remaining" ] && [ -n "$reset" ] || fail 'unexpected GitHub rate limit response'
+reset_at=$(date -u -d "@$reset" '+%Y-%m-%d %H:%M:%S UTC' 2>/dev/null || date -u -r "$reset" '+%Y-%m-%d %H:%M:%S UTC' 2>/dev/null || printf 'epoch %s' "$reset")
+if [ "$remaining" -lt 5 ]; then
+    fail "only $remaining anonymous GitHub API requests remain on this network (setup needs 2); the quota resets at $reset_at. Not starting."
+fi
+note "GitHub API quota: $remaining anonymous requests left (resets at $reset_at)"
+if [ "$source_mode" = head ]; then
+    git -C "$repo" archive --format=tar HEAD
+else
+    git -C "$repo" ls-files -z | tar -C "$repo" --null -T - -cf -
+fi | docker exec -i "$container" tar --no-same-owner -xf - -C /opt/bundle || fail 'cannot copy the bundle'
+note "prepared in $(elapsed)"
+
+bootstrap_started=$(date +%s)
+# A terminal session exports SHELL (the user's login shell); docker exec does
+# not. pnpm setup needs it to pick the profile to edit, and fails with
+# ERR_PNPM_UNKNOWN_SHELL without it.
+docker exec -d -u tester -w /home/tester -e SHELL=/bin/bash "$container" sh -c \
+    'sh /opt/bundle/scripts/bootstrap.sh > "$HOME/bootstrap.log" 2>&1; echo $? > "$HOME/bootstrap.status"' \
+    || fail 'cannot start the bootstrap'
+
+# Headless browser stand-in: the same requests the wizard page makes.
+driver=$(cat <<'DRIVER'
+set -eu
+log=$HOME/bootstrap.log
+say() { printf 'driver: %s\n' "$1"; }
+stop() { say "$1"; cat "$log" 2>/dev/null || :; exit 1; }
+waited=0
+while :; do
+    url=$(grep -o 'http://127\.0\.0\.1:[0-9]*/session?code=[A-Za-z0-9_-]*' "$log" 2>/dev/null | head -n 1) || url=
+    [ -z "$url" ] || break
+    [ ! -f "$HOME/bootstrap.status" ] || stop 'bootstrap exited before printing the session URL'
+    waited=$((waited + 1)); [ "$waited" -lt 600 ] || stop 'no session URL after 600 s'
+    sleep 1
+done
+say "session URL after ${waited}s"
+origin=${url%%/session*}
+jar=$HOME/acceptance-cookies
+curl -fsS -c "$jar" -b "$jar" -o /dev/null "$url" || stop 'session redemption failed'
+api() { curl -fsS -b "$jar" -H 'X-Gentle-Install: 1' "$@"; }
+post() { api -X POST -H "Origin: $origin" -H 'Content-Type: application/json' --data "$1" "$origin$2"; }
+plan=$(api "$origin/api/plan") || stop 'plan request failed'
+case $plan in *'"blockers":[]'*) ;; *) stop "plan has blockers: $plan";; esac
+plan_id=$(printf '%s' "$plan" | sed -n 's/.*"planId":"\([^"]*\)".*/\1/p')
+[ -n "$plan_id" ] || stop "plan has no planId: $plan"
+say "plan: $(printf '%s' "$plan" | grep -o '"actions":\[[^]]*\]' | grep -o '"id":"[^"]*"' | cut -d'"' -f4 | tr '\n' ' ')"
+post "{\"planId\":\"$plan_id\",\"consent\":true}" /api/install >/dev/null || stop 'install request rejected'
+seq=0
+polls=0
+while :; do
+    progress=$(api "$origin/api/progress?after=$seq") || stop 'progress request failed'
+    printf '%s' "$progress" | grep -o '"step":"[^"]*","status":"[^"]*"' | sed 's/"step":"\([^"]*\)","status":"\([^"]*\)"/  step \1: \2/' || :
+    last=$(printf '%s' "$progress" | grep -o '"seq":[0-9]*' | tail -n 1 | cut -d: -f2) || last=
+    [ -z "$last" ] || seq=$last
+    case $progress in *'"running":false'*'"outcome":{'*) break;; esac
+    polls=$((polls + 1)); [ "$polls" -lt "$INSTALL_LIMIT" ] || stop "installation still running after $INSTALL_LIMIT s"
+    sleep 1
+done
+outcome=$(printf '%s' "$progress" | sed -n 's/.*"outcome":{"outcome":"\([a-z-]*\)".*/\1/p')
+say "outcome: $outcome"
+post '{}' /api/shutdown >/dev/null || stop 'shutdown request rejected'
+waited=0
+until [ -f "$HOME/bootstrap.status" ]; do
+    waited=$((waited + 1)); [ "$waited" -lt 60 ] || stop 'bootstrap still running 60 s after shutdown'
+    sleep 1
+done
+status=$(cat "$HOME/bootstrap.status")
+say "bootstrap exit status: $status"
+cat "$log"
+case $outcome in ready|terminal-action-required) [ "$status" = 0 ] || exit 1;; *) exit 1;; esac
+DRIVER
+)
+printf '%s\n' "$driver" | docker exec -i -u tester -w /home/tester -e INSTALL_LIMIT="$install_limit" "$container" sh -s \
+    || fail "wizard flow failed after $(elapsed)"
+note "bootstrap and wizard finished in $(( $(date +%s) - bootstrap_started ))s"
+
+# A fresh interactive shell must find the persisted stack; the bootstrap tools
+# must be gone. bash -i without a terminal warns about job control; harmless.
+checks=$(cat <<'CHECKS'
+set -eu
+for tool in node npm pnpm gentle-shell; do printf '%s -> %s\n' "$tool" "$(command -v "$tool")"; done
+printf 'node %s, npm %s, pnpm %s\n' "$(node --version)" "$(npm --version)" "$(pnpm --version)"
+gentle-shell --version
+for dir in "$HOME"/.gentle-shell-bootstrap-tools.*; do
+    if [ -e "$dir" ] || [ -L "$dir" ]; then echo "bootstrap tools left behind: $dir" >&2; exit 1; fi
+done
+echo 'bootstrap tools removed'
+CHECKS
+)
+docker exec -u tester -w /home/tester "$container" bash -ic "$checks" || fail "fresh-terminal checks failed after $(elapsed)"
+# Informational: pnpm setup edits only ~/.bashrc, which non-interactive login
+# shells skip on Debian (see docs/install-wizard.md).
+if docker exec -u tester -w /home/tester "$container" bash -lc 'command -v gentle-shell' >/dev/null 2>&1; then
+    note 'bash -lc resolves gentle-shell'
+else
+    note 'bash -lc does not resolve gentle-shell (expected: ~/.profile is not edited)'
+fi
+passed=1
+note "PASS in $(elapsed)"

package/scripts/test-packed-runner.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import assert from "node:assert/strict";
+import { normalizeNpmPackResult, parseNpmPackResult } from "./npm-pack-result.mjs";
 import { execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
@@ -599,6 +600,23 @@ function runWindowsStartupTimingProbe(runtimeScript, env, cwd) {
 	});
 }
 
+export function createHookedPackedConsumerManifest(installDirectory, tarball) {
+	const ownedTarball = assertOwnedRegularFile(dirname(tarball), basename(tarball));
+	const consumer = realpathSync.native(installDirectory);
+	const canonicalTarball = realpathSync.native(ownedTarball);
+	const filePath = relative(consumer, canonicalTarball);
+	if (isAbsolute(filePath)) throw new Error("packed tarball must share the consumer filesystem root");
+	const fileSpec = `file:${filePath.split(sep).join("/")}`;
+	if (realpathSync.native(resolve(consumer, fileSpec.slice(5))) !== canonicalTarball) throw new Error("script approval does not resolve to the packed tarball");
+	// npm 12 matches local dependencies by their resolved file spec, not name.
+	// Absolute installs on npm 12 retain an absolute node.resolved; the relative
+	// key alone was empirically blocked. Both keys identify this same tarball.
+	// Older npm ignores this consumer-only field. No transitive script is approved.
+	const absoluteSpec = `file:${canonicalTarball.split(sep).join("/")}`;
+	if (realpathSync.native(absoluteSpec.slice(5)) !== canonicalTarball) throw new Error("absolute script approval does not resolve to the packed tarball");
+	return { name: "gentle-pi-packed-runner-test", private: true, allowScripts: { [fileSpec]: true, [absoluteSpec]: true } };
+}
+
 async function testHookedPackedRunner() {
 	const temporary = mkdtempSync(join(tmpdir(), "gentle-pi-packed-runner-"));
 	const packDirectory = join(temporary, "pack");
@@ -615,14 +633,14 @@ async function testHookedPackedRunner() {
 		mkdirSync(piAgentHome);
 	const originalSettings = '{ "tuiMode": "regular", "theme": "packed-fixture" }\n';
 	writeFileSync(join(agentHome, "settings.json"), originalSettings);
-	const packed = JSON.parse(runNpm(["pack", "--ignore-scripts", "--json", "--pack-destination", packDirectory], {
+	const packed = parseNpmPackResult(runNpm(["pack", "--ignore-scripts", "--json", "--pack-destination", packDirectory], {
 		cwd: root,
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "inherit"],
 }));
 	if (packed.length !== 1 || typeof packed[0]?.filename !== "string") throw new Error("npm pack did not return one tarball");
-	const tarball = join(packDirectory, packed[0].filename);
-	writeFileSync(join(installDirectory, "package.json"), JSON.stringify({ name: "gentle-pi-packed-runner-test", private: true }), "utf8");
+	const { tarball } = assertPackResult(packed, packDirectory, newUnhookedReceipt());
+	writeFileSync(join(installDirectory, "package.json"), JSON.stringify(createHookedPackedConsumerManifest(installDirectory, tarball)), "utf8");
 	runNpm(["install", "--ignore-scripts=false", "--no-audit", "--no-fund", "--package-lock=false", "--omit=dev", "--legacy-peer-deps", tarball], {
 		cwd: installDirectory,
 		stdio: "inherit",
@@ -657,6 +675,7 @@ async function testHookedPackedRunner() {
 	assert.ok(!abandonAuthorization.includes("evidence_records_present"));
 	// Accept prerelease pins too: a stable-only pattern here was a second,
 	// silent pin that refused the first prerelease version directory.
+	if (!existsSync(join(packageRoot, ".gentle-ai"))) throw new Error("packed postinstall did not create .gentle-ai; npm may have blocked lifecycle scripts — check the consumer allowScripts exact tarball approval and installer output");
 	const versions = readdirSync(join(packageRoot, ".gentle-ai"), { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.]*)?$/.test(entry.name));
 	if (versions.length !== 1) throw new Error("packed install did not contain exactly one package-local Gentle AI version");
 	const executable = join(packageRoot, ".gentle-ai", versions[0].name, process.platform === "win32" ? "gentle-ai.exe" : "gentle-ai");
@@ -801,8 +820,7 @@ export function validateWindowsStartupTimingMachinePaths(delta, operations = { l
 
 function assertPackResult(packed, packDirectory, receipt) {
 	selectUnhookedCheck(receipt, "pack-metadata");
-	if (!Array.isArray(packed) || packed.length !== 1 || !packed[0] || typeof packed[0] !== "object") throw new Error("npm pack did not return exactly one package");
-	const entry = packed[0];
+	const [entry] = normalizeNpmPackResult(packed);
 	if (entry.name !== "gentle-pi" || typeof entry.filename !== "string" || entry.filename !== basename(entry.filename)) throw new Error("npm pack returned an unsafe package identity");
 	if (typeof entry.integrity !== "string" || !/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(entry.integrity)) throw new Error("npm pack did not report a sha512 integrity");
 	const tarball = resolve(packDirectory, entry.filename);

package/scripts/types-baseline.json

@@ -1,95 +1,5 @@
 {
   "note": "Recorded TypeScript diagnostics. Regenerate with `node scripts/check-types.mjs --update` after fixing or deliberately accepting diagnostics. This file may only shrink without a review decision.",
-  "total": 200,
-  "byFileAndCode": {
-    "extensions/codegraph-tools.ts TS2339": 1,
-    "extensions/codegraph-tools.ts TS2345": 1,
-    "extensions/gentle-agents.ts TS2322": 3,
-    "extensions/gentle-ai.ts TS2322": 5,
-    "extensions/gentle-ai.ts TS2339": 11,
-    "extensions/gentle-ai.ts TS2345": 15,
-    "extensions/gentle-ai.ts TS2365": 1,
-    "extensions/gentle-ai.ts TS2488": 2,
-    "extensions/gentle-ai.ts TS2554": 1,
-    "extensions/gentle-ai.ts TS2740": 1,
-    "extensions/gentle-shell.ts TS2556": 1,
-    "extensions/quiet-tools.ts TS2339": 1,
-    "extensions/quiet-tools.ts TS2352": 2,
-    "lib/agents-messaging.ts TS2322": 1,
-    "lib/native-review-cli.ts TS2304": 6,
-    "lib/native-review-cli.ts TS2339": 1,
-    "lib/native-review-cli.ts TS2345": 1,
-    "lib/review-candidate-view.ts TS2353": 2,
-    "lib/review-compact-contract.ts TS2322": 2,
-    "lib/review-compact-contract.ts TS2365": 1,
-    "lib/review-integration-v2.ts TS2322": 2,
-    "lib/review-integration-v2.ts TS2352": 2,
-    "lib/review-publication-gate.ts TS2365": 2,
-    "lib/review-transaction.ts TS2322": 1,
-    "lib/review-transaction.ts TS2345": 1,
-    "lib/runtime-metrics-children.ts TS2345": 2,
-    "lib/sdd-preflight.ts TS2352": 1,
-    "lib/sdd-preflight.ts TS2365": 1,
-    "lib/shell-sidebar-layout.ts TS2341": 1,
-    "tests/agents-queries.test.ts TS2322": 1,
-    "tests/agents-queries.test.ts TS2345": 3,
-    "tests/agents-runner-process.test.ts TS2322": 1,
-    "tests/devbinary/native-review-parity.devtest.ts TS2339": 1,
-    "tests/devbinary/pi-host-relay.devtest.ts TS2339": 3,
-    "tests/gentle-ai-binary.test.ts TS2339": 2,
-    "tests/gentle-ai-installer.test.ts TS2339": 7,
-    "tests/gentle-ai-installer.test.ts TS2556": 1,
-    "tests/gentle-ai-renderer.test.ts TS2345": 6,
-    "tests/gentle-ai.test.ts TS2339": 1,
-    "tests/gentle-ai.test.ts TS2352": 8,
-    "tests/gentle-ai.test.ts TS2353": 1,
-    "tests/gentle-shell.test.ts TS2352": 1,
-    "tests/gentle-shell.test.ts TS2540": 1,
-    "tests/gentle-shell.test.ts TS2554": 1,
-    "tests/maintainer/provider-relay.maintest.ts TS2339": 17,
-    "tests/maintainer/provider-relay.maintest.ts TS2345": 1,
-    "tests/maintainer/provider-relay.maintest.ts TS2540": 2,
-    "tests/native-binary-gate.test.ts TS2339": 2,
-    "tests/native-review-consent.test.ts TS2554": 1,
-    "tests/native-review-parity-runtime.test.ts TS2339": 1,
-    "tests/quiet-tool-rendering.test.ts TS2339": 1,
-    "tests/quiet-tool-rendering.test.ts TS2345": 1,
-    "tests/review-agent-end-preflight.test.ts TS2339": 2,
-    "tests/review-agent-end-preflight.test.ts TS2345": 1,
-    "tests/review-candidate-view.test.ts TS2353": 4,
-    "tests/review-candidate-view.test.ts TS2540": 2,
-    "tests/review-candidate-view.test.ts TS2554": 2,
-    "tests/review-controller-native-recovery.test.ts TS2345": 1,
-    "tests/review-controller-native-routing.test.ts TS2339": 2,
-    "tests/review-controller-workspace-root.test.ts TS2322": 2,
-    "tests/review-correction-lifecycle.test.ts TS2339": 4,
-    "tests/review-gate.test.ts TS2322": 5,
-    "tests/review-gate.test.ts TS2345": 4,
-    "tests/review-gate.test.ts TS2740": 1,
-    "tests/review-graph-schema.test.ts TS2352": 2,
-    "tests/review-host-relay-routing.test.ts TS2345": 1,
-    "tests/review-host-relay-routing.test.ts TS2739": 1,
-    "tests/review-integration-v2-forward.test.ts TS2322": 1,
-    "tests/review-last-event-closure.test.ts TS2322": 1,
-    "tests/review-policy-judgment-day.test.ts TS2345": 1,
-    "tests/review-policy-ordinary.test.ts TS2345": 1,
-    "tests/review-policy-ordinary.test.ts TS2554": 1,
-    "tests/review-risk-assessment.test.ts TS2345": 1,
-    "tests/review-risk-assessment.test.ts TS2352": 1,
-    "tests/review-session-standing-permission-controller.test.ts TS2339": 1,
-    "tests/review-session-standing-permission-controller.test.ts TS2345": 1,
-    "tests/review-session-standing-permission-controller.test.ts TS2352": 1,
-    "tests/review-session-standing-permission-ipc.test.ts TS2322": 4,
-    "tests/review-test-fixtures.ts TS2739": 1,
-    "tests/review-transaction.test.ts TS2339": 1,
-    "tests/runtime-metrics-extension.test.ts TS2345": 1,
-    "tests/sdd-preflight.test.ts TS2352": 1,
-    "tests/sdd-preflight.test.ts TS2554": 2,
-    "tests/sdd-research-live.test.ts TS2322": 1,
-    "tests/shell-sidebar-layout.test.ts TS2339": 1,
-    "tests/shell-sidebar-layout.test.ts TS2345": 1,
-    "tests/shell-usage-view.test.ts TS2322": 1,
-    "tests/skill-registry.test.ts TS2345": 5,
-    "tests/writer-edit-surface-scope.test.ts TS2352": 1
-  }
+  "total": 0,
+  "byFileAndCode": {}
 }

package/scripts/verify-package-files.mjs

@@ -7,10 +7,56 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const root = join(fileURLToPath(new URL("..", import.meta.url)));
 
-const requiredPaths = [
+// Browser installation wizard: bootstrap scripts, entry, host and static assets.
+export const installerPaths = Object.freeze([
+  "bin/gentle-shell-install.mjs",
+  "scripts/installer-server.mjs",
+  "scripts/installer-runner.mjs",
+  "scripts/installer-preflight.mjs",
+  "scripts/installer-probes.mjs",
+  "scripts/installer-downloads.mjs",
+  "scripts/main-channel.mjs",
+  "scripts/installer-windows.mjs",
+  "scripts/installer-windows-artifacts.json",
+  "scripts/bundled-wizard.mjs",
+  "scripts/bundled-install.mjs",
+  "scripts/bootstrap.sh",
+  "scripts/bootstrap.cmd",
+  "assets/install-wizard/index.html",
+  "assets/install-wizard/wizard.js",
+  "assets/install-wizard/wizard.css",
+]);
+
+export const requiredPaths = [
   "bin/gentle-shell.mjs",
+  ...installerPaths,
+  "extensions/gentle-notifications.ts",
+  "lib/notification-audio.ts",
+  "lib/notification-audio-native.ts",
+  "lib/notification-audio-windows.ts",
+  "lib/notification-pulse-protocol.ts",
+  "lib/notification-pulse-client.ts",
+  "lib/notification-pulse-stream.ts",
+  "lib/notification-pulse-worker.ts",
+  "lib/notification-customize.ts",
+  "lib/notification-events.ts",
+  "lib/notification-policy.ts",
+  "lib/notification-scheduler.ts",
+  "lib/notification-service.ts",
+  "lib/notification-ui.ts",
+  "assets/sounds/success.wav",
+  "assets/sounds/error.wav",
+  "assets/sounds/attention.wav",
+  "assets/sounds/LICENSE.md",
+  "docs/sound-notifications.md",
+  "docs/sound-notifications-proposal.md",
+  "scripts/npm-pack-result.mjs",
   "assets/orchestrator.md",
   "assets/orchestrator-delegation.md",
+  "assets/orchestrator-tracking.md",
+  "assets/orchestrator-verification.md",
+  "assets/orchestrator-writer.md",
+  "assets/orchestrator-prompts.md",
   "assets/orchestrator-memory.md",
   "assets/orchestrator-skills.md",
   "assets/agents/gentle-ai-explore.md",
@@ -36,20 +82,33 @@ const requiredPaths = [
   "extensions/gentle-ai.ts",
   "extensions/resume-hint.ts",
   "extensions/skill-registry.ts",
+  "lib/child-package-injection.ts",
   "lib/gentle-ai-binary.ts",
   "lib/gentle-shell-launcher.ts",
+  "lib/gentle-shell-bundled.ts",
+  "lib/gentle-shell-startup-update.ts",
+  "lib/gentle-shell-update-panel.ts",
+  "lib/gentle-shell-startup-flow.ts",
   "lib/gentle-shell-resume-hint.ts",
   "lib/native-review-cli.ts",
+  "lib/status-timing-diagnostics.ts",
   "lib/provider-contract-bundle.ts",
   "lib/review-host-relay.ts",
   "lib/review-integration-v2.ts",
   "lib/review-relay-contract.ts",
   "lib/agent-assets.ts",
   "lib/telemetry-trigger.ts",
+	"runtime/child-package-injection.mjs",
 	"runtime/gentle-ai-binary.mjs",
 	"runtime/gentle-shell-launcher.mjs",
+	"runtime/gentle-shell-bundled.mjs",
+	"runtime/gentle-shell-startup-update.mjs",
+	"runtime/gentle-shell-update-panel.mjs",
+	"runtime/gentle-shell-startup-flow.mjs",
 	"runtime/gentle-shell-resume-hint.mjs",
+	"runtime/gentle-shell-uninstall.mjs",
 	"runtime/native-review-cli.mjs",
+	"runtime/status-timing-diagnostics.mjs",
 	"runtime/review-integration-v2.mjs",
 	"runtime/review-risk-assessment.mjs",
 	"runtime/review-relay-contract.mjs",
@@ -72,17 +131,17 @@ const requiredPaths = [
   // exact bytes are pinned by the lock-driven scripts/check-provider-contract.mjs
   // drift check, which runs in the same pnpm test flow.
   "contracts/review-provider-contract-mirror/provider-contract.lock.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/README.md",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/manifest.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/orchestration/pi.md",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/lens.schema.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/refuter.schema.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/targeted-validator.schema.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/vectors/lens.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/vectors/refuter.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/bundle/vectors/targeted-validator.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/generated/provider-capabilities.baseline.json",
-  "contracts/review-provider-contract-mirror/v1.2.0/generated/provider-roles.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/README.md",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/manifest.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/orchestration/pi.md",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/lens.schema.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/refuter.schema.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/targeted-validator.schema.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/lens.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/refuter.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/targeted-validator.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/generated/provider-capabilities.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.3.0/generated/provider-roles.baseline.json",
   "prompts/skill-creation.md",
   "skills/_shared/review-ledger-contract.md",
   "skills/branch-pr/SKILL.md",
@@ -173,6 +232,14 @@ const contractHashes = {
 
 requiredPaths.push(...Object.keys(contractHashes));
 
+// Required package-relative paths that are missing or are not regular files.
+export function missingRequiredPaths(packageRoot, paths) {
+  return paths.filter((relativePath) => {
+    const absolutePath = join(packageRoot, relativePath);
+    return !existsSync(absolutePath) || !statSync(absolutePath).isFile();
+  });
+}
+
 function listFilesRecursively(directory) {
   return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
     const absolutePath = join(directory, entry.name);
@@ -287,10 +354,7 @@ async function main() {
     process.exit(1);
   }
 
-  const missing = requiredPaths.filter((relativePath) => {
-    const absolutePath = join(root, relativePath);
-    return !existsSync(absolutePath) || !statSync(absolutePath).isFile();
-  });
+  const missing = missingRequiredPaths(root, requiredPaths);
 
   if (missing.length > 0) {
     console.error("gentle-pi package is missing required Pi resources:");
@@ -331,7 +395,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v4.0.0 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v4.1.1 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -376,7 +440,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.0.0 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.1.1 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;

package/skills/gentle-ai/SKILL.md

@@ -14,11 +14,11 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 ## Compact Rules
 
 - Clarify scope, constraints, acceptance criteria, and non-goals before implementation.
-- For substantial authorized ODD work, track the feature in its task document and mirror.
+- Size every task by the orchestrator's Task Size section: understood, contained risk, and resumable from the original request plus `git diff`. Counts of files, commands, tests, or fixes never decide it. Track only large work in its task document and mirror.
 - For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, relevant alternate cases, then REFACTOR and record evidence. Test presence alone does not establish applicability. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, state why and run proportionate ordinary functional or structural verification. Never invent RED/GREEN, skip checks, or require a chat/TUI toggle.
 - Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
-- Parent-only delegation triggers apply after complexity appears: reading beyond the evidence budget, 2+ non-trivial files to write, tooling/worktree incidents, or a parent context past the context backstop.
-- Keep writes single-threaded unless the user explicitly approves isolated parallel worktrees.
+- Parent-only delegation triggers fire one mechanism at a time: an open decision (ask), understanding beyond the evidence budget (explore), high risk (independent verifier), a large task (track), a writer reason (parallel units or context), tooling/worktree incidents, or a parent context past the context backstop.
+- Parallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
 - Keep dangerous-command safety independent and authoritative.
 - Never claim persistent memory is available because of el Gentleman itself; memory is provided by separate packages/tools when active.
@@ -30,23 +30,24 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 Use the smallest safe harness:
 
 ```text
-small + known context      → inline direct
-unknown / context-heavy    → simple delegation
-substantial authorized work → track ODD tasks and implement by work unit
+small task                 → inline direct, focused test and suite inline
+understanding is missing   → explore, then re-evaluate
+large authorized work      → track ODD tasks and implement by work unit
 ```
 
-For bounded implementation with subagents:
+For large implementation with subagents:
 
 ```text
-clarify → scout/context-builder when context-heavy → one worker → verify
+clarify → scout/context-builder when context-heavy → inline, or a writer only for a reason → verify
 ```
 
 Hard delegation triggers:
 
-- **Evidence-budget rule**: read inline only when the evidence fits one parallel batch of at most 3 calls, ~10k tokens (grep and line ranges, never whole large files). Larger reading, more than ~5 sequential lookups, or a long session ahead means delegate one explorer that returns a handoff of at most ~2k tokens with `path:line` evidence. Never force delegation for a small targeted question; do not re-read what the handoff covered beyond one spot check.
-- **Multi-file write rule**: touching 2+ non-trivial files means use one worker.
+- **Evidence-budget rule**: read inline only when the evidence fits one parallel batch of at most 3 calls, ~10k tokens (grep and line ranges, never whole large files). When understanding needs more reading or more than ~5 sequential lookups, delegate one explorer that returns a handoff of at most ~2k tokens with `path:line` evidence. Never force delegation for a small targeted question; do not re-read what the handoff covered beyond one spot check.
+- **Writer rule**: a writer only for a reason (parallel units launched together, or context); size and file count never fire it.
+- **Verification rule**: a high-risk change gets an independent verifier; otherwise the change's own focused test and suite run inline.
 - **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, diagnose separately.
-- **Context backstop**: when the parent context passes ~150k tokens, pause and delegate the next bounded unit of work to a non-review subagent. Keep command output bounded (counts, `--stat`, `tail`) and send full suites and builds to a verifier.
+- **Context backstop**: when the parent context passes ~150k tokens, pause and delegate the next bounded unit of work to a non-review subagent. Keep command output bounded (counts, `--stat`, `tail`).
 
 ## Review Lens Selection
 

package/tests/agent-home.test.ts

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { gentlePiConfigHome } from "../lib/agent-home.ts";
+import { bundledGentlePiAgentHome, gentlePiConfigHome } from "../lib/agent-home.ts";
+import { setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
 
 // The two Pi homes: `~/.pi/agent` holds Pi's own agent definitions and
 // `~/.pi/gentle-ai` holds everything the Gentle AI commands own. Both are resolved
@@ -15,7 +16,9 @@ function isolatedHome(t: test.TestContext): string {
 	const home = mkdtempSync(join(tmpdir(), "gentle-pi-config-home-"));
 	const previousHome = process.env.HOME;
 	const previousUserProfile = process.env.USERPROFILE;
-	// Isolation must cover POSIX and Windows, the way homedir() resolves each.
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	// Clear the higher-priority config override as well as isolating both OS homes.
+	delete process.env.GENTLE_PI_CONFIG_HOME;
 	process.env.HOME = home;
 	process.env.USERPROFILE = home;
 	t.after(() => {
@@ -23,6 +26,8 @@ function isolatedHome(t: test.TestContext): string {
 		else process.env.HOME = previousHome;
 		if (previousUserProfile === undefined) delete process.env.USERPROFILE;
 		else process.env.USERPROFILE = previousUserProfile;
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
 		rmSync(home, { recursive: true, force: true });
 	});
 	return home;
@@ -41,6 +46,25 @@ test("gentlePiConfigHome honours GENTLE_PI_CONFIG_HOME and otherwise falls back
 	);
 });
 
+test("the isolated home restores defined and undefined config overrides", async (t) => {
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	try {
+		for (const inherited of [undefined, "/synthetic-inherited-config"]) {
+			if (inherited === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+			else process.env.GENTLE_PI_CONFIG_HOME = inherited;
+			await t.test(`inherited override: ${inherited === undefined ? "unset" : "set"}`, (child) => {
+				const home = isolatedHome(child);
+				assert.equal(process.env.GENTLE_PI_CONFIG_HOME, undefined);
+				assert.equal(gentlePiConfigHome(), join(home, ".pi", "gentle-ai"));
+			});
+			assert.equal(process.env.GENTLE_PI_CONFIG_HOME, inherited);
+		}
+	} finally {
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+	}
+});
+
 test("the config home ignores the Pi agent-home overrides", (t) => {
 	const home = isolatedHome(t);
 	// PI_CODING_AGENT_DIR and GENTLE_PI_AGENT_HOME move Pi's agent directory only.
@@ -50,3 +74,32 @@ test("the config home ignores the Pi agent-home overrides", (t) => {
 		join(home, ".pi", "gentle-ai"),
 	);
 });
+
+// S9: a bundled Gentle Shell keeps gentle-pi's config inside its prefix. It is
+// derived from this package's bundled install and the launcher's
+// GENTLE_SHELL_PREFIX, never exported (Gentle AI 4.0.0 reads
+// GENTLE_PI_CONFIG_HOME as a parent folder). The testing overlay stands in for
+// this package running from that install.
+function bundledInstall(t: test.TestContext): string {
+	const prefix = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-bundled-config-")));
+	setBundledInstallForTesting({ root: prefix });
+	t.after(() => {
+		setBundledInstallForTesting(undefined);
+		rmSync(prefix, { recursive: true, force: true });
+	});
+	return prefix;
+}
+
+test("a bundled install derives the config home inside its prefix and the agent home from Pi's", (t) => {
+	isolatedHome(t);
+	const prefix = bundledInstall(t);
+	const env = { GENTLE_SHELL_PREFIX: prefix, GENTLE_PI_CONFIG_HOME: "/home/ana/.pi/gentle-ai", PI_CODING_AGENT_DIR: "/agent" };
+	assert.equal(gentlePiConfigHome(env), join(prefix, "config", "gentle-ai"));
+	assert.equal(bundledGentlePiAgentHome(env), "/agent");
+	// Another prefix, or none, is not this install: everything stays as before.
+	for (const other of [{ GENTLE_PI_CONFIG_HOME: "/custom" }, { GENTLE_SHELL_PREFIX: join(prefix, "other"), GENTLE_PI_CONFIG_HOME: "/custom" }]) {
+		assert.equal(gentlePiConfigHome(other), "/custom");
+		assert.equal(bundledGentlePiAgentHome({ ...other, PI_CODING_AGENT_DIR: "/agent" }), undefined);
+	}
+	assert.equal(gentlePiConfigHome({ GENTLE_PI_CONFIG_HOME: "" }), join(homedir(), ".pi", "gentle-ai"));
+});