gentle-pi 2.7.0 → 3.0.0

package/lib/review-publication-gate.ts

@@ -136,6 +136,7 @@ function runGateGit(cwd: string, args: readonly string[]): string {
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: reviewGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError(`Git publication identity could not be resolved: ${args.join(" ")}`);
 	return result.stdout.trim();
@@ -150,6 +151,7 @@ function listConfiguredRemotes(cwd: string): string[] {
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: reviewGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError("Configured Git remotes could not be listed");
 	return result.stdout.split(/\r?\n/).filter(Boolean);
@@ -160,6 +162,7 @@ function configuredRemoteValues(cwd: string, key: string): string[] {
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: publicationProbeGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || (result.status !== 0 && result.status !== 1)) {
 		throw publicationError(`Configured Git remote value "${key}" could not be resolved`);
@@ -178,6 +181,7 @@ export function resolveConfiguredPushDestinationV1(cwd: string, remote: string):
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: publicationProbeGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError(`Configured remote "${remote}" push destination could not be resolved`);
 	const urls = result.stdout.split(/\r?\n/).filter(Boolean);
@@ -205,6 +209,7 @@ export function resolvePushRemoteRefV1(
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: publicationProbeGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError(`${label} could not be resolved`);
 	if (result.stdout.length === 0) return { destination, object_id: null };
@@ -232,6 +237,7 @@ export function resolvePushDestinationRefV1(
 		cwd,
 		stdio: "ignore",
 		env: reviewGitEnvironment(),
+		windowsHide: true,
 	});
 	if (formatCheck.error || formatCheck.status !== 0) throw publicationError(`${label} is malformed`);
 	const destination = resolveConfiguredPushDestinationV1(cwd, remote);
@@ -240,6 +246,7 @@ export function resolvePushDestinationRefV1(
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: publicationProbeGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError(`${label} could not be resolved`);
 	const rows = result.stdout.split(/\r?\n/).filter(Boolean);
@@ -271,6 +278,7 @@ export function pushRemoteAdvertisesObjectV1(
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: publicationProbeGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError("Push parent advertisement could not be resolved");
 	const rows = result.stdout.split(/\r?\n/).filter(Boolean);
@@ -357,7 +365,7 @@ function defaultGhCommandRunner(
 	args: readonly string[],
 	options: { cwd: string; env: NodeJS.ProcessEnv },
 ): { status: number | null; stdout: string; error?: Error } {
-	const result = spawnSync("gh", args, { ...options, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+	const result = spawnSync("gh", args, { ...options, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
 	return { status: result.status, stdout: result.stdout ?? "", error: result.error };
 }
 
@@ -423,6 +431,7 @@ function resolveConfiguredRemoteUrl(cwd: string, remote: string): string {
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: reviewGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError(`Configured remote "${remote}" URL could not be resolved`);
 	const url = result.stdout.trim();
@@ -437,6 +446,7 @@ function resolveRemoteGateRef(cwd: string, remote: string, ref: string, label: s
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env: reviewGitEnvironment(),
+		windowsHide: true,
 	});
 	if (result.error || result.status !== 0) throw publicationError(`${label} could not be resolved`);
 	const matches = result.stdout.split(/\r?\n/).filter(Boolean).flatMap((line) => {

package/lib/review-repository.ts

@@ -75,7 +75,7 @@ export function publicationProbeGitEnvironment(): NodeJS.ProcessEnv {
 function gitLines(cwd: string, args: string[]): string[] {
 	let output: string;
 	try {
-		output = execFileSync("git", ["-C", resolve(cwd), ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], shell: false, env: reviewGitEnvironment() });
+		output = execFileSync("git", ["-C", resolve(cwd), ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], shell: false, env: reviewGitEnvironment(), windowsHide: true });
 	} catch (error) {
 		if (error instanceof ReviewRepositoryError) throw error;
 		throw new ReviewRepositoryError("Unable to resolve Git repository authority");

package/lib/review-snapshot.ts

@@ -171,6 +171,7 @@ function runGit(
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 		env,
+		windowsHide: true,
 	}).trim();
 }
 

package/lib/review-transaction.ts

@@ -935,12 +935,12 @@ export function reviewStoreRootForRepository(cwd: string): string {
 	const repositoryRoot = execFileSync(
 		"git",
 		["rev-parse", "--show-toplevel"],
-		{ cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+		{ cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
 	).trim();
 	const gitPath = execFileSync(
 		"git",
 		["rev-parse", "--git-path", "gentle-ai/reviews"],
-		{ cwd: repositoryRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+		{ cwd: repositoryRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
 	).trim();
 	return isAbsolute(gitPath) ? gitPath : resolve(repositoryRoot, gitPath);
 }
@@ -950,6 +950,7 @@ function repositoryRootForGate(cwd: string): string {
 		cwd,
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
+		windowsHide: true,
 	}).trim();
 }
 
@@ -1528,6 +1529,7 @@ function runGateGit(cwd: string, args: readonly string[]): string {
 		cwd,
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
+		windowsHide: true,
 	}).trim();
 }
 

package/lib/sdd-preflight.ts

@@ -99,7 +99,6 @@ export const SHIPPED_SDD_AGENT_NAMES = Object.freeze([
 	"sdd-status",
 	"sdd-apply",
 	"sdd-verify",
-	"sdd-sync",
 	"sdd-archive",
 	"sdd-remediate",
 ]);
@@ -725,6 +724,8 @@ function copyDirectoryFiles(
 // history); user-modified copies are left in place and only lose managed
 // ownership.
 const RETIRED_MANAGED_ASSETS = Object.freeze([
+	// Canonical spec composition now belongs to archive (gentle-pi#1051).
+	"agents/sdd-sync.md",
 	"agents/review-refuter.md",
 	"agents/review-validator.md",
 ]);

package/lib/sdd-research-capabilities.ts

@@ -1,6 +1,5 @@
 import { isAbsolute, resolve, dirname, basename } from "node:path";
-import { realpathSync, lstatSync, openSync, readSync, fstatSync, closeSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { realpathSync, lstatSync } from "node:fs";
 import type { AgentDefinition } from "./agents-config.ts";
 
 // Exact registered Pi names, not provider display namespaces. MCP's generic
@@ -34,14 +33,14 @@ export function resolveResearchCapabilities(pi: Inventory, restriction?: readonl
 	const capability = (required: string[], guidance: string): Capability => {
 		const missing = required.filter(name => !tools.includes(name as typeof RESEARCH_TOOLS[number]));
 		return {
-			status: missing.length === 0 ? "available" : "blocked",
+			status: required.some(name => tools.includes(name as typeof RESEARCH_TOOLS[number])) ? "available" : "blocked",
 			tools: required.filter(name => tools.includes(name as typeof RESEARCH_TOOLS[number])),
 			reason: `${missing.length === 0 ? "" : `Missing active, approved, child-reachable tools: ${missing.join(", ")}. `}${guidance}`,
 		};
 	};
 	return {
 		documentation: capability(["fetch_content"], "Fetch official documentation URLs; validate publisher and version before citing."),
-		"open-web": capability(["web_search", "source_check", "fetch_content", "get_search_content"], "All four tools are required. Search, check sources and retrieve original content; inventory and search snippets alone are not evidence."),
+		"open-web": capability(["web_search", "source_check", "fetch_content", "get_search_content"], "Use the available authorized tools for the requested questions; search snippets alone are not validated evidence."),
 	};
 }
 
@@ -50,8 +49,8 @@ export function renderResearchCapabilities(capabilities: ResearchCapabilities):
 		"## SDD Research Capabilities",
 		"Package-approved mapping intersected with active runtime tools and explicit agent restrictions:",
 		...Object.entries(capabilities).map(([kind, value]) => `- ${kind}: ${value.status}; tools=${JSON.stringify(value.tools)}. ${value.reason}`),
-		"Availability is not evidence or proposal admission. Run selected supported classes, record tool calls, source URLs, retrieval time, publisher/version, excerpts and claim-to-source IDs. Child-local inventory must confirm availability before evidence collection.",
-		"Missing required tools block only the affected class. Any selected unavailable or partial class keeps proposal_ready=false. Preserve explicit source restrictions; never recommend skipping selected research because of a blanket denial.",
+		"Availability is not evidence. Use actual authorized tools, cite retrieved sources with publisher/version/date, and distinguish supported findings from unanswered questions.",
+		"Unavailable tools limit the answers, not proposal readiness. Preserve explicit source restrictions, report useful partial findings and unavailable sources honestly, and never claim online access from inventory alone.",
 		"Generic MCP and dynamic namespace gateways are not approved evidence routes. Never infer remote method access from gateway names, tool descriptions, bash, persistence tools, or remembered facts.",
 	].join("\n");
 }
@@ -66,54 +65,25 @@ export function researchAgent(agent: AgentDefinition, pi: Inventory, selection?:
 	for (const [kind, capability] of Object.entries(capabilities)) {
 		const value = requested[kind];
 		const grant = value && typeof value === "object" ? value as Partial<ResearchGrant> : {};
-		const required = kind === "documentation" ? ["fetch_content"] : ["web_search", "source_check", "fetch_content", "get_search_content"];
+		const supported: readonly string[] = kind === "documentation" ? ["fetch_content"] : RESEARCH_TOOLS;
 		const exact = Object.keys(requested).every(key => Object.hasOwn(capabilities, key)) &&
-			Array.isArray(grant.tools) && grant.tools.length === required.length &&
-			required.every(name => grant.tools!.includes(name)) &&
-			grant.extensions && Object.keys(grant.extensions).length === required.length;
-		const paths = required.map(name => registered.find(tool => tool.name === name)?.sourceInfo?.path);
-		capability.tools = exact ? required.filter((name, i) => capability.tools.includes(name) &&
-			typeof paths[i] === "string" && isAbsolute(paths[i]!) && paths[i] === grant.extensions![name]) : [];
-		if (capability.tools.length !== required.length) {
-			capability.status = "blocked";
-			capability.reason = `Selected exact grants and matching active extension provenance required. ${capability.reason}`;
-		} else {
-			for (const path of paths) extensionPaths.add(path!);
-		}
+			Array.isArray(grant.tools) && grant.tools.length > 0 && new Set(grant.tools).size === grant.tools.length &&
+			grant.tools.every(name => supported.includes(name)) && grant.extensions &&
+			Object.keys(grant.extensions).length === grant.tools.length;
+		capability.tools = exact ? grant.tools!.filter(name => {
+			const path = registered.find(tool => tool.name === name)?.sourceInfo?.path;
+			return capability.tools.includes(name) && typeof path === "string" && isAbsolute(path) && path === grant.extensions![name];
+		}) : [];
+		capability.status = capability.tools.length ? "available" : "blocked";
+		capability.reason = `Only individually selected tools with matching active extension provenance are usable. ${capability.reason}`;
+		for (const name of capability.tools) extensionPaths.add(grant.extensions![name]);
 	}
 	const available = new Set(Object.values(capabilities).filter(value => value.status === "available").flatMap(value => value.tools));
-	const local = new Set(["read", "grep", "find", "edit", "write", "mem_search", "mem_get_observation", "mem_save"]);
-	const tools = agent.tools.filter(name => local.has(name) || available.has(name));
+	const tools = agent.tools.filter(name => available.has(name));
 	return { agent: { ...agent, tools, instructions: `${agent.instructions}\n\n${renderResearchCapabilities(capabilities)}` }, capabilities, extensionPaths: [...extensionPaths] };
 }
 
-export const RESEARCH_ARTIFACT_ENV = "GENTLE_PI_RESEARCH_ARTIFACT";
-const ARTIFACT_STORES = ["openspec", "engram", "both", "none"] as const;
-interface EngramLocator {
-	id: number;
-	project: string;
-	topic_key: string;
-	revision_count: number;
-}
-export interface ResearchWriteIdentity {
-	revision: number;
-	digest: string;
-}
-interface ResearchLocator extends ResearchWriteIdentity {
-	artifact: string;
-	path?: string;
-	engram?: EngramLocator;
-}
-export interface ResearchArtifactIntent {
-	store: typeof ARTIFACT_STORES[number];
-	worktree: string;
-	changeName: string;
-	retainedIntent: string;
-	locators: ResearchLocator[];
-}
-const record = (value: unknown): Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-const positive = (value: unknown) => Number.isSafeInteger(value) && Number(value) > 0;
-// Missing leaves are allowed for diagnostic persistence; existing symlinks are not.
+// Resolve existing ancestors for real remediation permission checks, including missing leaves.
 export function canonicalArtifactPath(path: string): string {
 	try { lstatSync(path); }
 	catch (error) {
@@ -122,107 +92,3 @@ export function canonicalArtifactPath(path: string): string {
 	}
 	return realpathSync(path);
 }
-export function parseResearchArtifactIntent(value: unknown, cwd: string, previous?: ResearchArtifactIntent): ResearchArtifactIntent {
-	const input = record(value);
-	if (!ARTIFACT_STORES.includes(input.store as ResearchArtifactIntent["store"])
-		|| input.worktree !== realpathSync(cwd) || input.worktree !== cwd) throw new Error("Research artifact worktree/store scope mismatch.");
-	if (typeof input.changeName !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(input.changeName)
-		|| typeof input.retainedIntent !== "string" || !input.retainedIntent.trim() || !Array.isArray(input.locators)) throw new Error("Missing bounded research scope/retained intent.");
-	const scope = structuredClone(input) as unknown as ResearchArtifactIntent;
-	const local = scope.store === "openspec" || scope.store === "both";
-	const memory = scope.store === "engram" || scope.store === "both";
-	if (scope.locators.length > 3 || (scope.store === "none" ? scope.locators.length !== 0 : scope.locators.length === 0)) throw new Error("Invalid research locator scope.");
-	const names = new Set<string>();
-	for (const locator of scope.locators) {
-		const item = record(locator), engram = record(item.engram);
-		if (!["research", "preproposal", "explore"].includes(String(item.artifact))
-			|| names.has(String(item.artifact))
-			|| !positive(item.revision) || typeof item.digest !== "string" || !/^[a-f0-9]{64}$/.test(item.digest)) throw new Error("Invalid research identity scope.");
-		names.add(locator.artifact);
-		const path = resolve(cwd, "openspec/changes", scope.changeName, `${locator.artifact}.md`);
-		if (local ? item.path !== path || canonicalArtifactPath(path) !== path : item.path !== undefined) throw new Error("OpenSpec locator outside exact scope.");
-		if (memory ? !positive(engram.id) || !positive(engram.revision_count) || typeof engram.project !== "string" || !engram.project.trim() || engram.topic_key !== `sdd/${scope.changeName}/${locator.artifact}` : item.engram !== undefined) throw new Error("Engram locator outside exact scope.");
-	}
-	if (previous) {
-		if (scope.store !== previous.store || scope.worktree !== previous.worktree
-			|| scope.changeName !== previous.changeName || scope.retainedIntent !== previous.retainedIntent || scope.locators.length !== previous.locators.length) throw new Error("Research continuation cannot replace retained scope.");
-		for (const next of scope.locators) {
-			const old = previous.locators.find(item => item.artifact === next.artifact);
-			if (!old || old.path !== next.path || old.engram?.id !== next.engram?.id
-				|| old.engram?.project !== next.engram?.project || old.engram?.topic_key !== next.engram?.topic_key) throw new Error("Research continuation cannot broaden scope.");
-			if (next.revision < old.revision || (next.engram?.revision_count ?? 0) < (old.engram?.revision_count ?? 0)
-				|| next.revision === old.revision && next.digest !== old.digest) throw new Error("Research continuation has stale/divergent scope.");
-		}
-	}
-	return scope;
-}
-
-// Negative intersection only: callers must still enforce host permissions/inventory.
-export function researchArtifactCall(scope: ResearchArtifactIntent, cwd: string, tool: string, input: Record<string, unknown>): number {
-	if (realpathSync(cwd) !== scope.worktree) throw new Error("Research artifact worktree changed.");
-	const index = scope.locators.findIndex(locator => {
-		if (locator.artifact === "explore" && ["write", "edit", "mem_save"].includes(tool)) return false;
-		if (["read", "write", "edit", "grep"].includes(tool)) {
-			if (!locator.path || typeof input.path !== "string") return false;
-			const path = resolve(cwd, input.path);
-			return path === locator.path && canonicalArtifactPath(path) === path;
-		}
-		if (!locator.engram) return false;
-		if (tool === "mem_get_observation") return input.id === locator.engram.id && Object.keys(input).every(key => key === "id");
-		if (tool === "mem_search") return input.project === locator.engram.project && input.query === locator.engram.topic_key && input.all_projects !== true;
-		if (tool === "mem_save") return input.project === locator.engram.project && input.topic_key === locator.engram.topic_key;
-		return false;
-	});
-	if (index < 0) throw new Error("Tool arguments outside retained research artifact scope.");
-	return index;
-}
-
-// Consume actual child tool results, never transported success assertions.
-export function researchArtifactReadback(locator: ResearchLocator, tool: string, returned: unknown, afterWrite = false): boolean {
-	let bytes: unknown = returned;
-	if (tool === "mem_get_observation") {
-		const value = record(returned), expected = locator.engram;
-		if (!expected || value.id !== expected.id || value.project !== expected.project || value.topic_key !== expected.topic_key
-			|| (afterWrite ? !positive(value.revision_count) || Number(value.revision_count) <= expected.revision_count : value.revision_count !== expected.revision_count)) return false;
-		bytes = value.content;
-	} else if (tool !== "read") return false;
-	if (typeof bytes !== "string" || createHash("sha256").update(bytes).digest("hex") !== locator.digest) return false;
-	try { return record(JSON.parse(bytes)).revision === locator.revision; } catch { return false; }
-}
-
-export const RESEARCH_PERSISTENCE_ENTRY = "gentle-sdd-research-persistence";
-export function parseResearchPersistence(value: unknown, scope: ResearchArtifactIntent, cwd: string) {
-	const saved = record(value), previous = parseResearchArtifactIntent(saved.scope, cwd);
-	parseResearchArtifactIntent(scope, cwd, previous);
-	if (saved.version !== 1 || !saved.accepted || typeof saved.accepted !== "object" || Array.isArray(saved.accepted) || !saved.writes || typeof saved.writes !== "object" || Array.isArray(saved.writes)) throw new Error("Invalid research persistence snapshot");
-	const accepted = record(saved.accepted) as Record<string, ResearchLocator>, writes = record(saved.writes) as Record<string, ResearchWriteIdentity>;
-	const tools = scope.store === "both" ? ["read", "mem_get_observation"] : [scope.store === "openspec" ? "read" : "mem_get_observation"];
-	for (const key of new Set([...Object.keys(accepted), ...Object.keys(writes)])) {
-		const [index, tool] = key.split(":"), old = previous.locators[Number(index)];
-		if (!/^[0-2]:(read|mem_get_observation)$/.test(key) || !old || !tools.includes(tool)) throw new Error("Research persistence key outside scope");
-		if (Object.hasOwn(accepted, key)) parseResearchArtifactIntent({ ...previous, locators: [accepted[key]] }, cwd, { ...previous, locators: [old] });
-		const desired = writes[key];
-		if (Object.hasOwn(writes, key) && (!desired || !positive(desired.revision) || desired.revision <= (accepted[key] ?? old).revision || typeof desired.digest !== "string" || !/^[a-f0-9]{64}$/.test(desired.digest))) throw new Error("Invalid durable desired identity");
-	}
-	for (const [index, locator] of scope.locators.entries()) {
-		const identities = [previous.locators[index], ...tools.map(tool => ({ ...(accepted[`${index}:${tool}`] ?? previous.locators[index]), ...writes[`${index}:${tool}`] }))];
-		const advanced = identities.slice(1).filter(item => item.revision > previous.locators[index].revision);
-		if (scope.store === "both" && advanced.length === 2 && (advanced[0].revision !== advanced[1].revision || advanced[0].digest !== advanced[1].digest)) throw new Error("Divergent durable hybrid desired identity");
-		if (!identities.some(item => item.revision === locator.revision && item.digest === locator.digest && item.engram?.revision_count === locator.engram?.revision_count)) throw new Error("Transported research identity differs from retained operation");
-	}
-	return structuredClone({ accepted, writes });
-}
-
-// Pi may defer custom entries in an in-memory/unflushed session. Verify the
-// actual bounded tail, not appendEntry's void return or an in-memory receipt.
-export function assertResearchCheckpoint(file: string, expected: unknown): void {
-	const fd = openSync(file, "r");
-	try {
-		const size = fstatSync(fd).size, length = Math.min(size, 65_536), tail = Buffer.alloc(length);
-		if (readSync(fd, tail, 0, length, size - length) !== length) throw new Error("Incomplete research checkpoint read");
-		const text = tail.toString("utf8");
-		if (!text.endsWith("\n")) throw new Error("Research checkpoint append incomplete");
-		const last = JSON.parse(text.trimEnd().split("\n").at(-1)!);
-		if (last.type !== "custom" || last.customType !== RESEARCH_PERSISTENCE_ENTRY || JSON.stringify(last.data) !== JSON.stringify(expected)) throw new Error("Research checkpoint not durably retained");
-	} finally { closeSync(fd); }
-}