pi-harness-runtime 1.1.448 → 1.1.451

package/AGENTS.md

@@ -117,9 +117,10 @@ git push origin develop
 #    request into main.
 bun scripts/release-all.ts --release-as patch
 
-# 3. The auto merge workflow merges develop into main as soon as the
-#    gates are green: "No sensitive terms" and "Tests".
-#    A pull request that is not green waits for a human.
+# 3. The auto merge workflow merges the pull request into main as soon
+#    as the gates are green: "No sensitive terms" and "Tests".
+#    The workflow merges the pull request itself, with the commit that
+#    was checked. A pull request that is not green waits for a human.
 
 # 4. After the merge, the tag is created on the tip of main.
 bun scripts/release-all.ts --tag
@@ -128,6 +129,26 @@ bun scripts/release-all.ts --tag
 #    and creates the GitHub release.
 ```
 
+**The merge gate**: `.github/workflows/auto-merge.yml` runs on a pull
+request into `main`. It reads the checks of the head commit of the pull
+request and merges the pull request when `No sensitive terms` and
+`Tests` are both green. The merge is the GraphQL mutation
+`mergePullRequest`, with the head commit that was checked - a push to
+the pull request after the check has to pass the gates again. The
+workflow checks out the base branch and runs no code of the pull
+request, so a pull request cannot change the rule that judges it.
+
+**The manual path**: a pull request that a workflow opened starts no
+workflow of its own, so the manual run takes that work over.
+
+```bash
+gh workflow run auto-merge.yml --ref develop -f open_release_pr=true
+```
+
+The manual run opens the pull request from `develop` into `main` when
+there is none, reads the same gates and merges the pull request when
+they are green.
+
 **Rules**:
 
 - **Never publish from `develop`.** The release workflow refuses a tag

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.1.451](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.448...v1.1.451) (2026-10-27)
+
+
+### Features
+
+* **jev:** the pending question carries the ask and the answer ([a792133](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a792133e517fb8c12d3363e98942f3af30270f27))
+* **merge:** a manual run can leave the merge to the pull request event ([b3d1950](https://github.com/ManotLuijiu/pi-harness-runtime/commit/b3d1950b5941c78ccd56951acdafd1d4afbe1bff))
+
+
+### Bug Fixes
+
+* **hooks:** a tag is checked through the commit behind it ([c823e8e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c823e8e1f6973c62b5449a97c101759a4d5cbba5))
+* **jev:** the alternatives of a question are parsed without a quadratic pattern ([63016a3](https://github.com/ManotLuijiu/pi-harness-runtime/commit/63016a3f0488acb801990dd46770c00d382b5858))
+* **keys:** the key directory is audited as a tree ([081cc75](https://github.com/ManotLuijiu/pi-harness-runtime/commit/081cc75ac8ceff36b0d619c3f76371dc08459d3c))
+* **merge:** the boolean input is read as a boolean ([971b716](https://github.com/ManotLuijiu/pi-harness-runtime/commit/971b7169a43db382dbdeb6bb9bab02ab56e0351c))
+* **merge:** the manual job needs the right of the merge ([7ba685e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7ba685ec43d815f90aa35b742579e87e76c69209))
+* **merge:** the merge of the pull request is the GraphQL mutation ([972bab4](https://github.com/ManotLuijiu/pi-harness-runtime/commit/972bab4b0f7faf1b0047f3bb767ef6db3de4b2fa))
+* **merge:** the workflow merges the pull request the gates cleared ([d7639ec](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d7639ec9b83723510acb4a5c4e23d5d6167c3af6))
+* **release:** a manual release keeps the version of its manifest ([122e661](https://github.com/ManotLuijiu/pi-harness-runtime/commit/122e661ea48cb8aff14c71dbd0221a4cf0ba4c8e))
+* **release:** the release scans the tree of the commit it publishes ([7d47a0b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7d47a0b5406480a1e1d3a52623a76aabd1e2d0ba))
+
+### [1.1.450](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.448...v1.1.450) (2026-10-27)
+
+
+### Features
+
+* **jev:** the pending question carries the ask and the answer ([a792133](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a792133e517fb8c12d3363e98942f3af30270f27))
+* **merge:** a manual run can leave the merge to the pull request event ([b3d1950](https://github.com/ManotLuijiu/pi-harness-runtime/commit/b3d1950b5941c78ccd56951acdafd1d4afbe1bff))
+
+
+### Bug Fixes
+
+* **hooks:** a tag is checked through the commit behind it ([c823e8e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c823e8e1f6973c62b5449a97c101759a4d5cbba5))
+* **jev:** the alternatives of a question are parsed without a quadratic pattern ([63016a3](https://github.com/ManotLuijiu/pi-harness-runtime/commit/63016a3f0488acb801990dd46770c00d382b5858))
+* **keys:** the key directory is audited as a tree ([081cc75](https://github.com/ManotLuijiu/pi-harness-runtime/commit/081cc75ac8ceff36b0d619c3f76371dc08459d3c))
+* **merge:** the boolean input is read as a boolean ([971b716](https://github.com/ManotLuijiu/pi-harness-runtime/commit/971b7169a43db382dbdeb6bb9bab02ab56e0351c))
+* **merge:** the manual job needs the right of the merge ([7ba685e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7ba685ec43d815f90aa35b742579e87e76c69209))
+* **merge:** the merge of the pull request is the GraphQL mutation ([972bab4](https://github.com/ManotLuijiu/pi-harness-runtime/commit/972bab4b0f7faf1b0047f3bb767ef6db3de4b2fa))
+* **merge:** the workflow merges the pull request the gates cleared ([d7639ec](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d7639ec9b83723510acb4a5c4e23d5d6167c3af6))
+* **release:** the release scans the tree of the commit it publishes ([7d47a0b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7d47a0b5406480a1e1d3a52623a76aabd1e2d0ba))
+
+### [1.1.449](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.448...v1.1.449) (2026-10-27)
+
+
+### Features
+
+* **jev:** the pending question carries the ask and the answer ([a792133](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a792133e517fb8c12d3363e98942f3af30270f27))
+* **merge:** a manual run can leave the merge to the pull request event ([b3d1950](https://github.com/ManotLuijiu/pi-harness-runtime/commit/b3d1950b5941c78ccd56951acdafd1d4afbe1bff))
+
+
+### Bug Fixes
+
+* **hooks:** a tag is checked through the commit behind it ([c823e8e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c823e8e1f6973c62b5449a97c101759a4d5cbba5))
+* **keys:** the key directory is audited as a tree ([081cc75](https://github.com/ManotLuijiu/pi-harness-runtime/commit/081cc75ac8ceff36b0d619c3f76371dc08459d3c))
+* **merge:** the boolean input is read as a boolean ([971b716](https://github.com/ManotLuijiu/pi-harness-runtime/commit/971b7169a43db382dbdeb6bb9bab02ab56e0351c))
+* **merge:** the manual job needs the right of the merge ([7ba685e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7ba685ec43d815f90aa35b742579e87e76c69209))
+* **merge:** the merge of the pull request is the GraphQL mutation ([972bab4](https://github.com/ManotLuijiu/pi-harness-runtime/commit/972bab4b0f7faf1b0047f3bb767ef6db3de4b2fa))
+* **merge:** the workflow merges the pull request the gates cleared ([d7639ec](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d7639ec9b83723510acb4a5c4e23d5d6167c3af6))
+
 ### [1.1.448](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.447...v1.1.448) (2026-10-26)
 
 

package/README.md

@@ -406,6 +406,23 @@ extension reads its own files (`qdrant-cluster-url.txt`, not
 variable). The startup fix commands always name the file the running code
 actually reads.
 
+**The permissions of the key directory.** The directory holds the secrets of
+the runtime, so it is created private (`700`) and audited at startup: a key
+file or a directory of the key tree that the group or the others can read is
+reported in the startup summary, together with one command that makes the
+whole tree private again. The command is shown, never executed:
+
+```bash
+chmod 700 ~/.pi-harness-runtime/keys && find ~/.pi-harness-runtime/keys -type d -exec chmod 700 {} + && find ~/.pi-harness-runtime/keys -type f -exec chmod 600 {} +
+```
+
+On Windows the same intent needs the access control list instead of the mode
+bits, and the summary says so:
+
+```powershell
+icacls "$env:USERPROFILE\.pi-harness-runtime\keys" /inheritance:r /grant:r "%USERNAME%:(OI)(CI)F" /T
+```
+
 See [Relay Setup](#relay-setup-two-way-telegram-stream) for the `echo` commands that
 create the relay and Telegram key files.
 
@@ -1312,6 +1329,19 @@ bun scripts/release-all.ts --release-as patch   # prepare the version on develop
 bun scripts/release-all.ts --tag                 # tag the tip of main after the merge
 ```
 
+**The merge gate**: the workflow merges the pull request itself, with
+the commit whose checks it read, so a push to the pull request after
+the check has to pass the gates again. The workflow runs the script of
+the base branch and no code of the pull request, so a pull request
+cannot change the rule that judges it.
+
+A pull request that a workflow opened starts no workflow of its own, so
+the manual run takes the work over:
+
+```bash
+gh workflow run auto-merge.yml --ref develop -f open_release_pr=true
+```
+
 ## License
 
 MIT © 2026 MooCoding

package/harness/key-file-audit.ts

@@ -15,7 +15,7 @@
  * state of a file (missing / empty).
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -319,6 +319,44 @@ export interface ExposedKeyFile {
 	readableBy: "group" | "others" | "group and others";
 }
 
+/**
+ * A directory of the key tree that other users on this machine can reach.
+ *
+ * A readable directory publishes the NAMES of the secrets below it and,
+ * together with a readable file, their content. The key directory itself is
+ * part of the audit: a directory of mode 755 hands the file names of every
+ * key to every account on the machine.
+ */
+export interface ExposedKeyDirectory {
+	/**
+	 * The name of the directory, relative to the key directory.
+	 *
+	 * The key directory itself is ".".
+	 */
+	name: string;
+	/** The mode of the directory, as an octal string ("755"). */
+	mode: string;
+	/** Who can reach the directory besides the owner. */
+	readableBy: "group" | "others" | "group and others";
+}
+
+/**
+ * The information the audit needs about one entry of the key tree.
+ */
+export interface KeyEntryInfo {
+	/** The permission bits. */
+	mode: number;
+	/** Is it a regular file? */
+	isFile: boolean;
+	/** Is it a directory? */
+	isDirectory?: boolean;
+	/** Is it a symbolic link? */
+	isSymbolicLink?: boolean;
+}
+
+/** How deep the audit walks into the key tree. */
+const MAX_KEY_TREE_DEPTH = 4;
+
 export interface KeyFileAuditOptions {
 	/** The key directory to scan (e.g. ~/.pi-harness-runtime/keys). */
 	keysDir: string;
@@ -330,8 +368,15 @@ export interface KeyFileAuditOptions {
 	exists?: (path: string) => boolean;
 	/** Directory reader override (used by the tests). */
 	readdir?: (path: string) => string[];
-	/** File information override (used by the tests). */
-	stat?: (path: string) => { mode: number; isFile: boolean } | undefined;
+	/**
+	 * File information override (used by the tests).
+	 *
+	 * The audit never follows a symbolic link: a link is reported by the
+	 * `isSymbolicLink` flag and is never classified as a regular file.
+	 */
+	stat?: (path: string) => KeyEntryInfo | undefined;
+	/** The platform the fix commands are written for (defaults to the current one). */
+	platform?: NodeJS.Platform;
 }
 
 export interface KeyFileAuditResult {
@@ -341,6 +386,125 @@ export interface KeyFileAuditResult {
 	byFeature: Map<string, MissingCredential[]>;
 	/** The key files that other users on this machine can read. */
 	exposed: ExposedKeyFile[];
+	/** The directories of the key tree that other users can reach. */
+	exposedDirectories: ExposedKeyDirectory[];
+}
+
+/**
+ * Compare two file names in a stable, locale independent order.
+ */
+function compareByName(a: string, b: string): number {
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+}
+
+/**
+ * Who can reach an entry besides its owner.
+ */
+function readableByOf(mode: number): ExposedKeyFile["readableBy"] | undefined {
+	const group = mode & 0o070;
+	const others = mode & 0o007;
+	if (group === 0 && others === 0) return undefined;
+	if (group !== 0 && others !== 0) return "group and others";
+	return group !== 0 ? "group" : "others";
+}
+
+/**
+ * The default entry reader: `lstat`, never `stat`.
+ *
+ * `lstat` does not follow a symbolic link, so a link to a secret is never
+ * read through and never counted as the file it points at.
+ */
+function defaultStat(path: string): KeyEntryInfo | undefined {
+	try {
+		const info = lstatSync(path);
+		return {
+			mode: info.mode & 0o777,
+			isFile: info.isFile(),
+			isDirectory: info.isDirectory(),
+			isSymbolicLink: info.isSymbolicLink(),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The default directory reader.
+ */
+function defaultReaddir(path: string): string[] {
+	try {
+		return readdirSync(path);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Walk the key tree and collect the exposed files and directories.
+ *
+ * The whole tree is scanned, not only the files of the inventory: a key
+ * file that the inventory does not know yet is a secret too. A symbolic
+ * link is never followed and never classified - it is neither a regular
+ * file nor a directory of the key tree.
+ */
+function collectKeyTree(
+	options: KeyFileAuditOptions,
+): { files: ExposedKeyFile[]; directories: ExposedKeyDirectory[] } {
+	const readdir = options.readdir ?? defaultReaddir;
+	const stat = options.stat ?? defaultStat;
+	const files: ExposedKeyFile[] = [];
+	const directories: ExposedKeyDirectory[] = [];
+
+	// The key directory itself: a readable directory publishes the names of
+	// every secret below it.
+	const root = stat(options.keysDir);
+	if (root?.isDirectory) {
+		const readableBy = readableByOf(root.mode);
+		if (readableBy) {
+			directories.push({
+				name: ".",
+				mode: root.mode.toString(8).padStart(3, "0"),
+				readableBy,
+			});
+		}
+	}
+
+	const walk = (dir: string, relative: string, depth: number): void => {
+		if (depth > MAX_KEY_TREE_DEPTH) return;
+		for (const name of readdir(dir).sort(compareByName)) {
+			const path = join(dir, name);
+			const info = stat(path);
+			if (!info) continue;
+			// A symbolic link is neither followed nor classified.
+			if (info.isSymbolicLink) continue;
+			const entryName = relative ? `${relative}/${name}` : name;
+			if (info.isDirectory) {
+				const readableBy = readableByOf(info.mode);
+				if (readableBy) {
+					directories.push({
+						name: entryName,
+						mode: info.mode.toString(8).padStart(3, "0"),
+						readableBy,
+					});
+				}
+				walk(path, entryName, depth + 1);
+				continue;
+			}
+			if (!info.isFile) continue;
+			const readableBy = readableByOf(info.mode);
+			if (!readableBy) continue;
+			files.push({
+				file: entryName,
+				mode: info.mode.toString(8).padStart(3, "0"),
+				readableBy,
+			});
+		}
+	};
+
+	walk(options.keysDir, "", 1);
+	return { files, directories };
 }
 
 /**
@@ -355,45 +519,20 @@ export interface KeyFileAuditResult {
  * key file that the inventory does not know yet is a secret too.
  */
 export function scanExposedKeyFiles(options: KeyFileAuditOptions): ExposedKeyFile[] {
-	const readdir =
-		options.readdir ??
-		((path: string) => {
-			try {
-				return readdirSync(path);
-			} catch {
-				return [];
-			}
-		});
-	const stat =
-		options.stat ??
-		((path: string) => {
-			try {
-				const info = statSync(path);
-				return { mode: info.mode & 0o777, isFile: info.isFile() };
-			} catch {
-				return undefined;
-			}
-		});
+	return collectKeyTree(options).files;
+}
 
-	const exposed: ExposedKeyFile[] = [];
-	for (const name of readdir(options.keysDir).sort()) {
-		const info = stat(join(options.keysDir, name));
-		if (!info || !info.isFile) continue;
-		const group = info.mode & 0o070;
-		const others = info.mode & 0o007;
-		if (group === 0 && others === 0) continue;
-		exposed.push({
-			file: name,
-			mode: info.mode.toString(8).padStart(3, "0"),
-			readableBy:
-				group !== 0 && others !== 0
-					? "group and others"
-					: group !== 0
-						? "group"
-						: "others",
-		});
-	}
-	return exposed;
+/**
+ * The directories of the key tree that other users can reach.
+ *
+ * The key directory itself is the first one: a directory of mode 755 hands
+ * the file names of every key to every account on the machine. A missing
+ * key directory is not an exposure - there is nothing to expose.
+ */
+export function scanExposedKeyDirectories(
+	options: KeyFileAuditOptions,
+): ExposedKeyDirectory[] {
+	return collectKeyTree(options).directories;
 }
 
 /**
@@ -471,7 +610,13 @@ export function auditKeyFiles(options: KeyFileAuditOptions): KeyFileAuditResult
 		byFeature.set(entry.requirement.feature, list);
 	}
 
-	return { missing, byFeature, exposed: scanExposedKeyFiles(options) };
+	const tree = collectKeyTree(options);
+	return {
+		missing,
+		byFeature,
+		exposed: tree.files,
+		exposedDirectories: tree.directories,
+	};
 }
 
 /**
@@ -487,6 +632,71 @@ export function formatExposedKeyFileFix(
 	return `chmod 600 ${join(displayKeysDir(keysDir), entry.file)}`;
 }
 
+/**
+ * Quote a path for a POSIX shell.
+ *
+ * The key directory can hold a file name with a space, a quote or a dollar
+ * sign. The command must not run into the shell, and it must not turn a
+ * name into a second command.
+ */
+export function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The one command that makes the whole key tree private again.
+ *
+ * The startup summary shows ONE command, not one command per file: a list
+ * of twenty `chmod` lines is a list nobody runs. The command covers the
+ * key directory, the directories below it and the files in it, and it is
+ * safe for any file name - `find` passes the names to `chmod` itself, so
+ * no name is ever interpreted by the shell.
+ *
+ * The command is never executed by the harness. It is a suggestion for the
+ * operator, and the operator decides when to run it.
+ */
+export function formatKeyPermissionFix(
+	keysDir: string,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	if (platform === "win32") {
+		// Windows has no Unix mode bits. The equivalent is the access
+		// control list of the directory and of the files below it.
+		return `icacls "${keysDir.replace(/"/g, '""')}" /inheritance:r /grant:r "%USERNAME%:(OI)(CI)F" /T`;
+	}
+	const dir = shellQuote(keysDir);
+	return (
+		`chmod 700 ${dir} && ` +
+		`find ${dir} -type d -exec chmod 700 {} + && ` +
+		`find ${dir} -type f -exec chmod 600 {} +`
+	);
+}
+
+/**
+ * The fix lines for the exposed key files and directories.
+ *
+ * On a Unix-like system this is the single batch command. On Windows it is
+ * the guidance that the same intent needs - the Unix command does not
+ * exist there and would only confuse the operator.
+ */
+export function formatKeyPermissionFixes(options: {
+	/** The key directory to repair. */
+	keysDir: string;
+	/** The platform the commands are written for. */
+	platform?: NodeJS.Platform;
+}): string[] {
+	const platform = options.platform ?? process.platform;
+	const command = formatKeyPermissionFix(options.keysDir, platform);
+	if (platform === "win32") {
+		return [
+			"Windows: restrict the key directory to your account (the Unix mode bits do not exist here).",
+			command,
+			"The command changes the access rights, not the values.",
+		];
+	}
+	return [command];
+}
+
 /**
  * The fix commands for every key file that other users can read.
  */

package/harness/startup-report.ts

@@ -11,7 +11,11 @@
  * - LINE must not be reported as configured when the audit could not run.
  */
 
-import type { ExposedKeyFile, KeyFileAuditResult } from "./key-file-audit.ts";
+import type {
+	ExposedKeyDirectory,
+	ExposedKeyFile,
+	KeyFileAuditResult,
+} from "./key-file-audit.ts";
 
 export type StartupStatus = "wait" | "ok" | "info" | "warn" | "err";
 
@@ -154,15 +158,16 @@ export function relayEndpointReport(options: {
 export function exposedKeyFilesReport(options: {
 	/** The key files that other users can read. */
 	exposed: ExposedKeyFile[];
+	/** The directories of the key tree that other users can reach. */
+	exposedDirectories?: ExposedKeyDirectory[];
 	/** The `chmod` command for each of them. */
 	fixes: string[];
 }): StartupReport | null {
-	if (options.exposed.length === 0) return null;
-	const count = options.exposed.length;
-	const text =
-		count === 1
-			? "1 key file can be read by other users on this machine"
-			: `${count} key files can be read by other users on this machine`;
+	const directories = options.exposedDirectories ?? [];
+	if (options.exposed.length === 0 && directories.length === 0) return null;
+	const files = options.exposed.length;
+	const dirs = directories.length;
+	const text = exposedPermissionText(files, dirs);
 	const details = [...options.fixes];
 	if (details.length === 0) {
 		details.push(
@@ -172,6 +177,26 @@ export function exposedKeyFilesReport(options: {
 	return { label: "Keys", text, status: "warn", details };
 }
 
+/**
+ * The text of the exposure line.
+ *
+ * It names the count and never a value: the line says that other users on
+ * the machine can read the files, it never says what is in them.
+ */
+function exposedPermissionText(files: number, directories: number): string {
+	if (files > 0 && directories > 0) {
+		return `${files} key file(s) and ${directories} director(y/ies) of the key tree can be read by other users on this machine`;
+	}
+	if (files > 0) {
+		return files === 1
+			? "1 key file can be read by other users on this machine"
+			: `${files} key files can be read by other users on this machine`;
+	}
+	return directories === 1
+		? "1 directory of the key tree can be read by other users on this machine"
+		: `${directories} directories of the key tree can be read by other users on this machine`;
+}
+
 /**
  * The two steps that create a usable LINE channel.
  *