gentle-pi 0.3.7 → 0.3.9

package/README.md

@@ -462,12 +462,17 @@ node --experimental-strip-types --check extensions/startup-banner.ts
 npm pack --dry-run
 ```
 
-Publish:
+Publish npm through GitHub Actions only:
 
 ```bash
-npm publish
+gh workflow run publish.yml --repo Gentleman-Programming/gentle-pi --ref main -f dist-tag=latest
+gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
+npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
+npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
 ```
 
+Do not run `npm publish` locally for `gentle-pi`; the GitHub workflow provides provenance, environment protection, and registry credentials.
+
 ## Principles
 
 - Human control over agent momentum.

package/extensions/gentle-ai.ts

@@ -233,6 +233,9 @@ const MODEL_CONTROL_OPTIONS = [
 	INHERIT_MODEL,
 	CUSTOM_MODEL,
 ] as const;
+const MODEL_PANEL_MAX_RENDER_ROWS = 20;
+const AGENT_LIST_MAX_VISIBLE_ROWS = MODEL_PANEL_MAX_RENDER_ROWS - 13;
+const MODEL_LIST_MAX_VISIBLE_ROWS = 12;
 
 function readStringPath(value: unknown, path: string[]): string | undefined {
 	let current = value;
@@ -367,16 +370,32 @@ function isThinkingLevel(value: unknown): value is ThinkingLevel {
 	);
 }
 
+const ANSI_ESCAPE_PATTERN =
+	/[\u001b\u009b][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+const CONTROL_CHAR_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
+const SAFE_MODEL_ID_PATTERN = /^[A-Za-z0-9._~:@/+%-]+$/;
+
+function sanitizeTerminalText(value: string): string {
+	return value
+		.replace(ANSI_ESCAPE_PATTERN, "")
+		.replace(CONTROL_CHAR_PATTERN, "");
+}
+
+function normalizeModelId(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const model = value.trim();
+	if (model.length === 0) return undefined;
+	if (!SAFE_MODEL_ID_PATTERN.test(model)) return undefined;
+	return model;
+}
+
 function normalizeRoutingEntry(value: unknown): AgentRoutingEntry | undefined {
 	if (typeof value === "string") {
-		const model = value.trim();
-		return model.length > 0 ? { model } : undefined;
+		const model = normalizeModelId(value);
+		return model ? { model } : undefined;
 	}
 	if (!isRecord(value)) return undefined;
-	const model =
-		typeof value.model === "string" && value.model.trim().length > 0
-			? value.model.trim()
-			: undefined;
+	const model = normalizeModelId(value.model);
 	const thinking = isThinkingLevel(value.thinking) ? value.thinking : undefined;
 	if (!model && !thinking) return undefined;
 	return { model, thinking };
@@ -804,14 +823,15 @@ function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
 		const entry = config[agent.name];
 		const model = entry?.model ?? "inherit";
 		const thinking = entry?.thinking ?? "inherit";
-		return `${agent.name}: model=${model}, effort=${thinking}`;
+		return `${sanitizeTerminalText(agent.name)}: model=${sanitizeTerminalText(model)}, effort=${sanitizeTerminalText(thinking)}`;
 	});
 }
 
 async function getPiModelOptions(ctx: ExtensionContext): Promise<string[]> {
 	const models = await ctx.modelRegistry.getAvailable();
 	const modelIds = models
-		.map((model) => `${model.provider}/${model.id}`)
+		.map((model) => normalizeModelId(`${model.provider}/${model.id}`))
+		.filter((model): model is string => model !== undefined)
 		.sort((left, right) => left.localeCompare(right));
 	return [...MODEL_CONTROL_OPTIONS, ...modelIds];
 }
@@ -868,9 +888,25 @@ class SddModelPanel implements OverlayComponent {
 	}
 
 	render(width: number): string[] {
-		if (this.mode === "models") return this.renderModelPicker(width);
-		if (this.mode === "effort") return this.renderEffortPicker(width);
-		return this.renderAgentList(width);
+		const innerWidth = Math.max(1, width - 4);
+		const lines =
+			this.mode === "models"
+				? this.renderModelPicker(innerWidth)
+				: this.mode === "effort"
+					? this.renderEffortPicker(innerWidth)
+					: this.renderAgentList(innerWidth);
+		return this.renderCard(lines, width);
+	}
+
+	private renderCard(lines: string[], width: number): string[] {
+		const innerWidth = Math.max(1, width - 4);
+		const fit = (text = "") =>
+			truncateToWidth(sanitizeTerminalText(text), innerWidth, "…", true).padEnd(innerWidth);
+		return [
+			`╭${"─".repeat(innerWidth + 2)}╮`,
+			...lines.map((line) => `│ ${fit(line)} │`),
+			`╰${"─".repeat(innerWidth + 2)}╯`,
+		];
 	}
 
 	private handleAgentInput(data: string): void {
@@ -883,25 +919,33 @@ class SddModelPanel implements OverlayComponent {
 			this.done({ type: "save", config: this.draft });
 			return;
 		}
-		if (matchesKey(data, "down") || data === "j") {
+		if (matchesKey(data, "down") || matchesKey(data, "j")) {
 			this.cursor = Math.min(maxCursor, this.cursor + 1);
 			return;
 		}
-		if (matchesKey(data, "up") || data === "k") {
+		if (matchesKey(data, "up") || matchesKey(data, "k")) {
 			this.cursor = Math.max(0, this.cursor - 1);
 			return;
 		}
-		if (data === "i") {
+		if (matchesKey(data, "g")) {
+			this.cursor = 0;
+			return;
+		}
+		if (data === "G") {
+			this.cursor = maxCursor;
+			return;
+		}
+		if (matchesKey(data, "i")) {
 			this.applyInherit();
 			return;
 		}
-		if (data === "e") {
+		if (matchesKey(data, "e")) {
 			this.selectedRow = this.rows[this.cursor] ?? SET_ALL_AGENTS;
 			this.mode = "effort";
 			this.effortCursor = 0;
 			return;
 		}
-		if (data === "c") {
+		if (matchesKey(data, "c")) {
 			const row = this.rows[this.cursor];
 			if (row === SET_ALL_AGENTS)
 				this.done({ type: "custom", agent: "all", config: this.draft });
@@ -943,14 +987,14 @@ class SddModelPanel implements OverlayComponent {
 			);
 			return;
 		}
-		if (matchesKey(data, "down") || data === "j") {
+		if (matchesKey(data, "down") || matchesKey(data, "j")) {
 			this.modelCursor = Math.min(
 				Math.max(0, options.length - 1),
 				this.modelCursor + 1,
 			);
 			return;
 		}
-		if (matchesKey(data, "up") || data === "k") {
+		if (matchesKey(data, "up") || matchesKey(data, "k")) {
 			this.modelCursor = Math.max(0, this.modelCursor - 1);
 			return;
 		}
@@ -1041,11 +1085,22 @@ class SddModelPanel implements OverlayComponent {
 		const lines: string[] = [];
 		const line = (text = "") =>
 			truncateToWidth(text, Math.max(1, width), "…", true);
-		lines.push(line("Assign Models to Agents"));
+		lines.push(line("Assign Models and Effort to Agents"));
 		lines.push("");
 		lines.push(line("Current assignments:"));
 		lines.push("");
-		for (let i = 0; i < this.rows.length; i++) {
+		const visibleRows = Math.min(AGENT_LIST_MAX_VISIBLE_ROWS, this.rows.length);
+		const listCursor = Math.min(this.cursor, this.rows.length - 1);
+		const start = Math.max(
+			0,
+			Math.min(
+				listCursor - Math.floor(visibleRows / 2),
+				Math.max(0, this.rows.length - visibleRows),
+			),
+		);
+		const end = Math.min(this.rows.length, start + visibleRows);
+		if (start > 0) lines.push(line(`  ↑ ${start} more agent(s)`));
+		for (let i = start; i < end; i++) {
 			const row = this.rows[i] ?? SET_ALL_AGENTS;
 			const focused = i === this.cursor;
 			const label =
@@ -1054,6 +1109,8 @@ class SddModelPanel implements OverlayComponent {
 					: this.renderAgentLabel(row);
 			lines.push(line(`${focused ? "▸" : " "} ${label}`));
 		}
+		if (end < this.rows.length)
+			lines.push(line(`  ↓ ${this.rows.length - end} more agent(s)`));
 		lines.push("");
 		lines.push(
 			line(`${this.cursor === this.rows.length ? "▸" : " "} Continue`),
@@ -1064,7 +1121,7 @@ class SddModelPanel implements OverlayComponent {
 		lines.push("");
 		lines.push(
 			line(
-				"j/k: navigate • enter: change model / confirm • e: change effort • i: inherit all • c: custom model • ctrl+s: save • esc: back",
+				"j/k: scroll • g/G: top/bottom • enter: change model / confirm • e: effort • i: inherit • c: custom • ctrl+s: save • esc: back",
 			),
 		);
 		return lines;
@@ -1075,22 +1132,21 @@ class SddModelPanel implements OverlayComponent {
 		const options = this.filteredModelOptions();
 		const line = (text = "") =>
 			truncateToWidth(text, Math.max(1, width), "…", true);
-		lines.push(line(`Select model for ${this.selectedRow}`));
+		lines.push(line(`Select model for ${sanitizeTerminalText(this.selectedRow)}`));
 		lines.push("");
 		lines.push(line(`◎ ${this.query || "search..."}`));
 		lines.push("");
-		const maxVisible = 12;
 		const start = Math.max(
 			0,
 			Math.min(
-				this.modelCursor - Math.floor(maxVisible / 2),
-				Math.max(0, options.length - maxVisible),
+				this.modelCursor - Math.floor(MODEL_LIST_MAX_VISIBLE_ROWS / 2),
+				Math.max(0, options.length - MODEL_LIST_MAX_VISIBLE_ROWS),
 			),
 		);
-		const end = Math.min(options.length, start + maxVisible);
+		const end = Math.min(options.length, start + MODEL_LIST_MAX_VISIBLE_ROWS);
 		for (let i = start; i < end; i++) {
 			const focused = i === this.modelCursor;
-			lines.push(line(`${focused ? "▸" : " "} ${options[i]}`));
+			lines.push(line(`${focused ? "▸" : " "} ${sanitizeTerminalText(options[i] ?? "")}`));
 		}
 		if (options.length === 0) lines.push(line("  No matching models"));
 		lines.push("");
@@ -1109,14 +1165,14 @@ class SddModelPanel implements OverlayComponent {
 			this.mode = "agents";
 			return;
 		}
-		if (matchesKey(data, "down") || data === "j") {
+		if (matchesKey(data, "down") || matchesKey(data, "j")) {
 			this.effortCursor = Math.min(
 				Math.max(0, THINKING_OPTIONS.length - 1),
 				this.effortCursor + 1,
 			);
 			return;
 		}
-		if (matchesKey(data, "up") || data === "k") {
+		if (matchesKey(data, "up") || matchesKey(data, "k")) {
 			this.effortCursor = Math.max(0, this.effortCursor - 1);
 			return;
 		}
@@ -1131,7 +1187,7 @@ class SddModelPanel implements OverlayComponent {
 		const lines: string[] = [];
 		const line = (text = "") =>
 			truncateToWidth(text, Math.max(1, width), "…", true);
-		lines.push(line(`Select effort for ${this.selectedRow}`));
+		lines.push(line(`Select effort for ${sanitizeTerminalText(this.selectedRow)}`));
 		lines.push("");
 		for (let i = 0; i < THINKING_OPTIONS.length; i++) {
 			const focused = i === this.effortCursor;
@@ -1157,13 +1213,13 @@ class SddModelPanel implements OverlayComponent {
 		const effortLabel = efforts.every((value) => value === firstEffort)
 			? firstEffort
 			: "mixed";
-		return `${row.padEnd(20)} model=${modelLabel}, effort=${effortLabel}`;
+		return `${sanitizeTerminalText(row).padEnd(20)} model=${sanitizeTerminalText(modelLabel)}, effort=${sanitizeTerminalText(effortLabel)}`;
 	}
 
 	private renderAgentLabel(row: string): string {
 		const model = this.draft[row]?.model ?? "inherit";
 		const effort = this.draft[row]?.thinking ?? "inherit";
-		return `${row.padEnd(20)} model=${model}, effort=${effort}`;
+		return `${sanitizeTerminalText(row).padEnd(20)} model=${sanitizeTerminalText(model)}, effort=${sanitizeTerminalText(effort)}`;
 	}
 }
 
@@ -1206,18 +1262,27 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 				? "inherit"
 				: (config[result.agent]?.model ?? "inherit");
 		const custom = await ctx.ui.input(
-			`${result.agent === "all" ? "all agents" : result.agent} custom model id`,
-			current === "inherit" ? "provider/model" : current,
+			`${result.agent === "all" ? "all agents" : sanitizeTerminalText(result.agent)} custom model id`,
+			current === "inherit" ? "provider/model" : sanitizeTerminalText(current),
 		);
 		if (custom === undefined) return;
 		const trimmed = custom.trim();
 		if (trimmed.length > 0) {
+			const model = normalizeModelId(trimmed);
+			if (!model) {
+				ctx.ui.notify(
+					"Custom model id must be a single-line provider/model identifier using letters, numbers, '.', '-', '_', '~', ':', '@', '/', '+', '%' only.",
+					"warning",
+				);
+				result = await showSddModelPanel(ctx, config);
+				continue;
+			}
 			if (result.agent === "all") {
 				const next: AgentModelConfig = { ...config };
 				for (const agent of listDiscoverableAgents(ctx.cwd)) {
 					next[agent.name] = {
 						...(next[agent.name] ?? {}),
-						model: trimmed,
+						model,
 					};
 				}
 				config = next;
@@ -1226,7 +1291,7 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 					...config,
 					[result.agent]: {
 						...(config[result.agent] ?? {}),
-						model: trimmed,
+						model,
 					},
 				};
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/skills/release/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: release
+description: "Release gentle-pi through GitHub and npm. Trigger: release, publish, npm publish, GitHub release, version bump."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## When to Use
+
+Use this skill when preparing, publishing, or verifying a `gentle-pi` release.
+
+## Hard Rules
+
+- Do not publish `gentle-pi` to npm from a local machine.
+- npm publishing MUST go through the GitHub Actions workflow `.github/workflows/publish.yml` so provenance, environment protection, and registry credentials are controlled by GitHub.
+- Use a clean worktree for release commits. Do not package unrelated local files or scratch artifacts.
+- Run a fresh review before pushing a code release unless the change is trivial docs-only.
+- Never skip package verification. The publish workflow runs verification again, but local validation should still pass before tagging.
+
+## Release Procedure
+
+1. **Inspect state**
+
+   ```bash
+   git status --short
+   git fetch origin main --tags
+   git log --oneline --decorate --max-count=5 origin/main
+   ```
+
+2. **Prepare the release commit**
+
+   - Apply only intended changes.
+   - Bump `package.json` to the next semver version.
+   - Keep lockfile changes out unless dependency resolution actually changed.
+
+3. **Verify locally**
+
+   ```bash
+   pnpm test
+   pnpm publish --dry-run --no-git-checks
+   ```
+
+   The dry run is allowed because it does not publish. It verifies package contents and lifecycle scripts.
+
+4. **Commit and push**
+
+   ```bash
+   git add <intended-files>
+   git commit -m "<type(scope): release-ready change>"
+   git push origin HEAD:main
+   ```
+
+5. **Create the GitHub release**
+
+   ```bash
+   git tag -a v<version> -m "gentle-pi v<version>"
+   git push origin v<version>
+   gh release create v<version> \
+     --repo Gentleman-Programming/gentle-pi \
+     --title "gentle-pi v<version>" \
+     --notes "<release notes>"
+   ```
+
+6. **Publish npm through GitHub Actions**
+
+   ```bash
+   gh workflow run publish.yml \
+     --repo Gentleman-Programming/gentle-pi \
+     --ref main \
+     -f dist-tag=latest
+   ```
+
+   Watch the run and fail the release if it fails:
+
+   ```bash
+   gh run list --repo Gentleman-Programming/gentle-pi --workflow publish.yml --limit 3
+   gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
+   ```
+
+7. **Verify npm**
+
+   ```bash
+   npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
+   npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
+   ```
+
+## Failure Handling
+
+- If a local `npm publish` fails, do not retry locally. Use the GitHub workflow instead.
+- If the workflow fails, inspect logs with:
+
+  ```bash
+  gh run view <run-id> --repo Gentleman-Programming/gentle-pi --log
+  ```
+
+- If npm verification is briefly stale after a successful workflow, check the exact version first (`npm view gentle-pi@<version> version`) before assuming publish failed.
+
+## Output Contract
+
+Report:
+
+- Commit SHA pushed to `main`.
+- GitHub release URL.
+- Publish workflow run URL and conclusion.
+- npm exact version and `latest` dist-tag.
+- Any remaining follow-up or warnings.

package/tests/runtime-harness.mjs

@@ -5,6 +5,7 @@ import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promis
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { discoverAndLoadExtensions } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -640,12 +641,75 @@ async function run() {
 			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
 			`---\nname: sdd-apply\ndescription: Apply phase\n---\n\nbody\n`,
 		);
+		for (let i = 0; i < 25; i++) {
+			const name = `large-agent-${String(i).padStart(2, "0")}`;
+			await writeFile(
+				join(modelsCwd, ".pi", "agents", `${name}.md`),
+				`---\nname: ${name}\ndescription: Scroll fixture\n---\n`,
+			);
+		}
+		await writeFile(
+			join(modelsCwd, ".pi", "agents", "escape-agent.md"),
+			`---\nname: evil\u001b]52;c;Zm9v\u0007-agent\ndescription: Escape fixture\n---\n`,
+		);
 		await writeFile(
 			globalModelsPath,
 			JSON.stringify({ "sdd-apply": "openai/gpt-5" }, null, 2),
 		);
 
 		const ctx = createCtx(modelsCwd, true);
+		ctx.modelRegistry.getAvailable = async () => [
+			{ provider: "safe", id: "model" },
+			{ provider: "evil\u001b]52;c;Zm9v\u0007", id: "model" },
+		];
+		ctx.ui.custom = (factory) => {
+			const panel = factory(null, null, null, () => undefined);
+			const initialLines = panel.render(120);
+			assert.ok(
+				initialLines[0].startsWith("╭") && initialLines.at(-1).startsWith("╰"),
+				"model panel should render inside a bordered card",
+			);
+			assert.ok(
+				initialLines.length <= 20,
+				"long model agent list should fit within a 24-row terminal 85% overlay budget",
+			);
+			assert.ok(
+				initialLines.some((line) => /↓ \d+ more agent\(s\)/.test(line)),
+				"long model agent list should render a down-scroll indicator",
+			);
+			assert.ok(
+				initialLines.some((line) => line.includes("Continue")),
+				"long model agent list should keep Continue visible",
+			);
+			assert.doesNotMatch(
+				initialLines.join("\n"),
+				/[\u001b\u0007]/,
+				"model panel must strip terminal control sequences from agent labels",
+			);
+			for (let i = 0; i < 20; i++) panel.handleInput("j");
+			const scrolledLines = panel.render(120);
+			assert.ok(
+				scrolledLines.length <= 20,
+				"scrolled model agent list should stay within the overlay height budget",
+			);
+			assert.ok(
+				scrolledLines.some((line) => /↑ \d+ more agent\(s\)/.test(line)),
+				"long model agent list should render an up-scroll indicator after navigation",
+			);
+			panel.handleInput("G");
+			const bottomLines = panel.render(120);
+			assert.ok(
+				bottomLines.length <= 20,
+				"bottom model agent list should stay within the overlay height budget",
+			);
+			assert.ok(
+				bottomLines.some((line) => line.includes("▸ ← Back")),
+				"G should jump to the Back action",
+			);
+			return Promise.resolve({ type: "cancel" });
+		};
+		await commands.get("gentle:models").handler("", ctx);
+
 		await hooks.get("session_start")[0]({ reason: "startup" }, ctx);
 		const legacyAppliedAgent = await readFile(
 			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
@@ -663,6 +727,11 @@ async function run() {
 				},
 			});
 		await commands.get("gentle:models").handler("", ctx);
+		assert.doesNotMatch(
+			ctx.ui.notifications.at(-1).message,
+			/[\u001b\u0007]/,
+			"model save notification must strip terminal control sequences from discovered agent names",
+		);
 
 		const savedConfig = JSON.parse(
 			await readFile(globalModelsPath, "utf8"),
@@ -693,6 +762,10 @@ async function run() {
 		);
 		assert.equal(settings.subagents.agentOverrides.worker.thinking, "low");
 
+		const kittyE = "\x1b[101u";
+		assert.notEqual(kittyE, "e");
+		assert.equal(matchesKey(kittyE, "e"), true);
+
 		let customPanelCalls = 0;
 		ctx.ui.input = async () => "custom/provider-model";
 		ctx.ui.custom = (factory) =>
@@ -700,7 +773,7 @@ async function run() {
 				customPanelCalls += 1;
 				const panel = factory(null, null, null, resolve);
 				if (customPanelCalls === 1) {
-					panel.handleInput("e"); // effort picker for all agents
+					panel.handleInput(kittyE); // effort picker for all agents
 					for (let i = 0; i < 4; i++) panel.handleInput("j"); // medium
 					panel.handleInput("\r");
 					panel.handleInput("c"); // custom model from the same unsaved draft
@@ -717,6 +790,31 @@ async function run() {
 			model: "custom/provider-model",
 			thinking: "medium",
 		});
+
+		let invalidCustomCalls = 0;
+		ctx.ui.input = async () => "bad\nmodel: injected";
+		ctx.ui.custom = (factory) =>
+			new Promise((resolve) => {
+				invalidCustomCalls += 1;
+				const panel = factory(null, null, null, resolve);
+				if (invalidCustomCalls === 1) {
+					panel.handleInput("c");
+					return;
+				}
+				panel.handleInput("\u001b");
+			});
+		await commands.get("gentle:models").handler("", ctx);
+		assert.match(
+			ctx.ui.notifications.at(-1).message,
+			/Custom model id must be a single-line/,
+		);
+		const rejectedCustomConfig = JSON.parse(
+			await readFile(globalModelsPath, "utf8"),
+		);
+		assert.deepEqual(rejectedCustomConfig["sdd-apply"], {
+			model: "custom/provider-model",
+			thinking: "medium",
+		});
 	} finally {
 		await rm(modelsCwd, { recursive: true, force: true });
 		await rm(globalModelsPath, { force: true });