@gajae-code/coding-agent 0.12.0 → 0.12.1

package/src/web/search/providers/searxng.ts

@@ -25,7 +25,9 @@
  * Reference: https://docs.searxng.org/dev/search_api.html
  */
 
+import * as path from "node:path";
 import type { AuthStorage } from "@gajae-code/ai";
+import { $credentialEnv, parseEnvFile } from "@gajae-code/utils";
 
 import { settings } from "../../../config/settings";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
@@ -74,6 +76,47 @@ interface SearXNGAuth {
 }
 
 /** Find SearXNG endpoint from settings or environment. */
+/**
+ * SearXNG environment value, from trusted sources only, preserving an
+ * intentionally empty setting.
+ *
+ * These four names decide where search requests go and what credential they
+ * carry, and `$env` merges the caller's `cwd/.env` into `process.env`, so a
+ * repository could otherwise redirect the search and hand over the basic-auth
+ * material.
+ *
+ * `$credentialEnv` is the resolver for that boundary, but it collapses an empty
+ * value to `undefined` — and SearXNG basic auth treats "set but empty" as
+ * meaningful (`alice:` and `:s3cret` are both valid). So an empty value is
+ * recovered explicitly, and only when the project `.env` is not what set it.
+ */
+function trustedSearxngEnv(name: string): string | null {
+	const trusted = $credentialEnv(name);
+	if (trusted !== undefined) return trusted;
+
+	const raw = process.env[name];
+	if (raw === undefined || raw.trim().length > 0) return null;
+	// Empty-but-set. Honour it unless the project `.env` is the source.
+	const projectValue = parseEnvFile(path.join(process.cwd(), ".env"))[name];
+	if (projectValue !== undefined && projectValue.trim().length === 0) return null;
+	return "";
+}
+
+/** Test seam: the SearXNG endpoint and auth material as resolved from trusted env. */
+export function resolveSearxngConfigForTest(): {
+	endpoint: string | null;
+	token: string | null;
+	basicUsername: string | null;
+	basicPassword: string | null;
+} {
+	return {
+		endpoint: findEndpoint(),
+		token: findToken(),
+		basicUsername: findBasicUsername(),
+		basicPassword: findBasicPassword(),
+	};
+}
+
 function findEndpoint(): string | null {
 	try {
 		const endpoint = settings.get("searxng.endpoint");
@@ -81,7 +124,7 @@ function findEndpoint(): string | null {
 	} catch {
 		// Settings not initialized yet
 	}
-	return process.env.SEARXNG_ENDPOINT ?? null;
+	return trustedSearxngEnv("SEARXNG_ENDPOINT");
 }
 
 /** Find SearXNG bearer token from settings or environment. */
@@ -92,7 +135,7 @@ function findToken(): string | null {
 	} catch {
 		// Settings not initialized yet
 	}
-	return process.env.SEARXNG_TOKEN ?? null;
+	return trustedSearxngEnv("SEARXNG_TOKEN");
 }
 
 /** Find SearXNG Basic auth username from settings or environment. */
@@ -103,7 +146,7 @@ function findBasicUsername(): string | null {
 	} catch {
 		// Settings not initialized yet
 	}
-	return process.env.SEARXNG_BASIC_USERNAME ?? null;
+	return trustedSearxngEnv("SEARXNG_BASIC_USERNAME");
 }
 
 /** Find SearXNG Basic auth password from settings or environment. */
@@ -114,7 +157,7 @@ function findBasicPassword(): string | null {
 	} catch {
 		// Settings not initialized yet
 	}
-	return process.env.SEARXNG_BASIC_PASSWORD ?? null;
+	return trustedSearxngEnv("SEARXNG_BASIC_PASSWORD");
 }
 
 /** Build the RFC 7617 Basic auth credential using UTF-8 bytes. */

package/src/web/search/providers/xai.ts

@@ -5,7 +5,7 @@
  * Endpoint: POST https://api.x.ai/v1/responses
  */
 import type { AuthStorage } from "@gajae-code/ai";
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv, $env } from "@gajae-code/utils";
 import type { SearchCitation, SearchResponse, SearchSource, SearchUsage } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import type { SearchParams } from "./base";
@@ -71,8 +71,13 @@ function getModel(): string {
 	return asTrimmed($env.PI_XAI_WEB_SEARCH_MODEL) ?? asTrimmed($env.XAI_WEB_SEARCH_MODEL) ?? DEFAULT_MODEL;
 }
 
+/** Test seam: the xAI search base URL as resolved from trusted env. */
+export function resolveXaiSearchBaseUrlForTest(): string {
+	return getBaseUrl();
+}
+
 function getBaseUrl(): string {
-	return asTrimmed($env.XAI_SEARCH_BASE_URL) ?? DEFAULT_BASE_URL;
+	return asTrimmed($credentialEnv("XAI_SEARCH_BASE_URL")) ?? DEFAULT_BASE_URL;
 }
 
 function responsesEndpoint(): string {

package/dist/types/gjc-runtime/ultragoal-pipeline.d.ts

@@ -1,23 +0,0 @@
-import { type JsonObject, type UltragoalGoal, type UltragoalPipelineOverlapReceipt, type UltragoalPlan } from "./ultragoal-runtime";
-export declare function requirePipelineStartable(plan: UltragoalPlan, prior: UltragoalGoal, next: UltragoalGoal): void;
-export declare function startUltragoalPipelineOverlap(input: {
-    cwd: string;
-    priorGoalId: string;
-    nextGoalId: string;
-    reviewHandles: JsonObject | JsonObject[];
-    qaHandles: JsonObject | JsonObject[];
-    implementationHandle: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt>;
-export declare function joinUltragoalPipelineOverlap(input: {
-    cwd: string;
-    overlapId: string;
-    reviewResult: JsonObject;
-    qaResult: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt>;
-export declare function rebaselineUltragoalPipelineOverlap(input: {
-    cwd: string;
-    overlapId: string;
-    goalId: string;
-    evidence: string;
-    targetState: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt>;

package/src/defaults/gjc/skills/ultragoal/pipeline-validation-contracts.md

@@ -1,30 +0,0 @@
-# Ultragoal Pipeline & Validation-Batch Contracts Fragment
-
-Internal Ultragoal sub-skill fragment (`kind: "skill-fragment"`, parent skill `ultragoal`, installed at `skill-fragments/ultragoal/pipeline-validation-contracts.md`). The Ultragoal leader loads it on demand before operating a pipeline overlap or checkpointing a validation-batch member; it is never user-facing, not slash-command discoverable, and never resolvable through `skill://`. The runtime enforces every rule below verbatim and fails closed.
-
-## Runtime-backed pipeline overlap lifecycle
-
-Use the lifecycle commands exactly when runtime metadata proves safety:
-
-```sh
-gjc ultragoal start-pipeline-overlap --prior-goal-id G001 --next-goal-id G002 --review-handles-json '<json>' --qa-handles-json '<json>' --implementation-handle-json '<json>' --json
-gjc ultragoal join-pipeline-overlap --overlap-id <id> --review-result-json '<json>' --qa-result-json '<json>' --json
-gjc ultragoal rebaseline-pipeline-overlap --overlap-id <id> --goal-id G002 --evidence "<evidence>" --target-state-json '<json>' --json
-```
-
-Runtime-backed pipelining is deliberately narrow:
-
-- At most one eligible next goal may overlap the current goal's review/QA join window.
-- G(N) remains active until `join-pipeline-overlap` records a clean join; do not checkpoint G(N) complete before clean join evidence exists.
-- `start-pipeline-overlap` must fail closed for missing metadata, one-sided independence, shared target files/surfaces, stale metadata hashes, missing handles, another open overlap, or per-story mode.
-- `join-pipeline-overlap` must fail closed for missing lane evidence or unresolved blockers. Continue G(N+1) only when structured blocker footprints are disjoint from G(N+1) targets; otherwise quarantine and re-baseline with `rebaseline-pipeline-overlap` before G(N+1) can complete.
-- Complete checkpoints must fail closed for open overlaps, missing clean joins, stale metadata, quarantined next goals, shared or unattributable change-set paths, and any missing pipeline evidence.
-- After a crash or lost live handles, the leader reruns review/QA lanes and joins with replacement evidence when metadata hashes still match; otherwise quarantine and re-baseline. Ultragoal must not auto-start G(N+2) during recovery.
-
-## Validation-batch checkpoint contract
-
-- **Non-final members** checkpoint `complete` with a single top-level `deferredToBatch` quality gate (kind `validation-batch-deferred`): targeted verification, ai-slop-cleaner pass, and a rerun iteration, plus a cumulative-since-base change set. A `deferredToBatch` gate must NOT contain `architectReview`, `executorQa`, or `validationBatchClose` — deferring never manufactures fake review approvals.
-- **The final member** (`finalGoalId`) checkpoints `complete` with the normal full strict gate PLUS a top-level `validationBatchClose` proof that covers all member IDs, member metadata hashes, member receipt/checkpoint-ledger-event IDs, per-member change-set hashes, and union change-set coverage. The final close only starts once every non-final member is already `complete` with a structurally fresh deferred receipt (out-of-order close is rejected).
-- Close state is append-only proof: it lives in the final member's checkpoint receipt and matching `goal_checkpointed` ledger row only. Never stamp `closedReceiptId`/`closedAt` or any close-state field onto member goals, and never append a separate close ledger event.
-- Change sets are cumulative-since-base: each member's `changeSet.paths` is the whole-worktree diff vs base (`cumulativeFromBase: true`), `memberGoalId` is a label not a per-path attribution, and `unionChangeSet.paths` carries no per-goal attribution.
-- Batch invalidation is fail-closed: steering mutations that would invalidate a batch are rejected while any member holds a fresh deferred receipt.

package/src/gjc-runtime/ultragoal-pipeline.ts

@@ -1,306 +0,0 @@
-import * as crypto from "node:crypto";
-import {
-	appendLedger,
-	collectPipelineBlockerFootprints,
-	currentUltragoalSessionId,
-	getUltragoalPaths,
-	handleIdsFromValue,
-	hashPipelineMetadata,
-	isSubstantiveEvidence,
-	type JsonObject,
-	nonEmptyString,
-	openPipelineOverlap,
-	pipelinePeer,
-	readUltragoalLedger,
-	readUltragoalPlan,
-	requireCoveredHandles,
-	requireFreshPipelineMetadata,
-	requireJsonObjectOrArrayValue,
-	requireJsonObjectValue,
-	requireNonEmptyPipelineTargets,
-	resultHandleIds,
-	stringArray,
-	targetsAreDisjoint,
-	targetsOverlap,
-	type UltragoalGoal,
-	type UltragoalLedgerEvent,
-	type UltragoalPipelineLedgerEventName,
-	type UltragoalPipelineOverlapReceipt,
-	type UltragoalPipelineOverlapState,
-	type UltragoalPlan,
-	validateValidationBatchPipelineExclusion,
-	writePlan,
-} from "./ultragoal-runtime";
-
-export function requirePipelineStartable(plan: UltragoalPlan, prior: UltragoalGoal, next: UltragoalGoal): void {
-	if (plan.gjcGoalMode !== "aggregate")
-		throw new Error("pipeline overlap is supported only for aggregate ultragoal mode");
-	if (openPipelineOverlap(plan))
-		throw new Error("Cannot start pipeline overlap because another overlap is already open");
-	if (prior.status !== "active")
-		throw new Error(`Prior goal ${prior.id} must be active before pipeline overlap starts`);
-	if (next.status !== "pending" && next.status !== "failed")
-		throw new Error(`Next goal ${next.id} must be pending or retryable failed`);
-	validateValidationBatchPipelineExclusion(prior);
-	validateValidationBatchPipelineExclusion(next);
-	if (prior.validationBatch || next.validationBatch)
-		throw new Error("pipeline overlap cannot start for validation batch goals");
-	const priorMetadata = requireFreshPipelineMetadata(prior);
-	const nextMetadata = requireFreshPipelineMetadata(next);
-	if (!priorMetadata.eligible || !nextMetadata.eligible)
-		throw new Error("pipeline overlap requires eligible original-plan metadata on both goals");
-	if (!priorMetadata.independentOf.includes(next.id) || !nextMetadata.independentOf.includes(prior.id)) {
-		throw new Error("pipeline overlap requires symmetric original independence");
-	}
-	if (!targetsAreDisjoint(priorMetadata.targets, nextMetadata.targets))
-		throw new Error("pipeline overlap requires disjoint files and surfaces");
-}
-
-function pipelineEventRefs(prior: UltragoalGoal, next: UltragoalGoal): JsonObject {
-	return {
-		priorMetadataHash: prior.pipelineMetadata?.metadataHash,
-		nextMetadataHash: next.pipelineMetadata?.metadataHash,
-		priorTargets: prior.pipelineMetadata?.targets,
-		nextTargets: next.pipelineMetadata?.targets,
-	};
-}
-
-function pipelineReceipt(
-	cwd: string,
-	event: string,
-	overlapId: string,
-	prior: UltragoalGoal,
-	next: UltragoalGoal,
-): UltragoalPipelineOverlapReceipt {
-	const paths = getUltragoalPaths(cwd, currentUltragoalSessionId(cwd));
-	return {
-		ok: true,
-		event,
-		overlap_id: overlapId,
-		prior_goal_id: prior.id,
-		next_goal_id: next.id,
-		status: next.pipelineMetadata?.overlap,
-		next_goal_status: next.status,
-		goals_path: paths.goalsPath,
-		ledger_path: paths.ledgerPath,
-	};
-}
-
-export async function startUltragoalPipelineOverlap(input: {
-	cwd: string;
-	priorGoalId: string;
-	nextGoalId: string;
-	reviewHandles: JsonObject | JsonObject[];
-	qaHandles: JsonObject | JsonObject[];
-	implementationHandle: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt> {
-	const plan = await readUltragoalPlan(input.cwd);
-	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const prior = plan.goals.find(goal => goal.id === input.priorGoalId);
-	const next = plan.goals.find(goal => goal.id === input.nextGoalId);
-	if (!prior || !next) throw new Error("start-pipeline-overlap requires existing prior and next goal ids");
-	const reviewHandles = requireJsonObjectOrArrayValue(input.reviewHandles, "review handles");
-	const qaHandles = requireJsonObjectOrArrayValue(input.qaHandles, "QA handles");
-	requireJsonObjectValue(input.implementationHandle, "implementation handle");
-	requirePipelineStartable(plan, prior, next);
-	const now = new Date().toISOString();
-	const overlapId = `pipeline-${crypto.randomUUID()}`;
-	const priorMetadata = requireFreshPipelineMetadata(prior);
-	const nextMetadata = requireFreshPipelineMetadata(next);
-	const priorOpenMetadata = {
-		...priorMetadata,
-		overlap: "open" as const,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-	};
-	const nextOpenMetadata = {
-		...nextMetadata,
-		overlap: "open" as const,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-	};
-	prior.pipelineMetadata = { ...priorOpenMetadata, metadataHash: hashPipelineMetadata(priorOpenMetadata) };
-	next.pipelineMetadata = { ...nextOpenMetadata, metadataHash: hashPipelineMetadata(nextOpenMetadata) };
-	prior.updatedAt = now;
-	next.updatedAt = now;
-	next.status = "active";
-	next.startedAt = next.startedAt ?? now;
-	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	const refs = pipelineEventRefs(prior, next);
-	const expectedReviewHandleIds = handleIdsFromValue(reviewHandles, "review");
-	const expectedQaHandleIds = handleIdsFromValue(qaHandles, "QA");
-	await appendLedger(input.cwd, {
-		event: "pipeline_overlap_started",
-		eventId: crypto.randomUUID(),
-		timestamp: now,
-		schemaVersion: 1,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-		reviewHandles,
-		reviewHandleIds: expectedReviewHandleIds,
-		qaHandles,
-		qaHandleIds: expectedQaHandleIds,
-		implementationHandle: input.implementationHandle,
-		...refs,
-	});
-	await appendLedger(input.cwd, { event: "goal_started", goalId: next.id, pipelineOverlapId: overlapId });
-	return pipelineReceipt(input.cwd, "pipeline_overlap_started", overlapId, prior, next);
-}
-
-function resultStatus(value: JsonObject, fieldName: string): string {
-	const status = nonEmptyString(value.status) ?? nonEmptyString(value.verdict) ?? nonEmptyString(value.result);
-	if (!status) throw new Error(`${fieldName} requires status, verdict, or result`);
-	return status.toLowerCase();
-}
-
-function requireCleanPipelineResult(result: JsonObject, expectedHandleIds: readonly string[], fieldName: string): void {
-	const status = resultStatus(result, fieldName);
-	if (!["passed", "pass", "approved", "clear"].includes(status)) throw new Error(`${fieldName} did not pass`);
-	const evidence = nonEmptyString(result.evidence);
-	if (!evidence || !isSubstantiveEvidence(evidence)) throw new Error(`${fieldName} requires substantive evidence`);
-	requireCoveredHandles(expectedHandleIds, resultHandleIds(result, fieldName), fieldName);
-	if (collectPipelineBlockerFootprints(result, fieldName).length > 0)
-		throw new Error(`${fieldName} cannot clean-join with blockers`);
-}
-
-function pipelineStartEventHandleIds(
-	ledger: UltragoalLedgerEvent[],
-	overlapId: string,
-): { review: string[]; qa: string[] } {
-	const event = ledger.find(row => row.event === "pipeline_overlap_started" && row.overlapId === overlapId) as
-		| JsonObject
-		| undefined;
-	if (!event) throw new Error(`No pipeline_overlap_started event found for ${overlapId}`);
-	const review =
-		stringArray(event.reviewHandleIds) ??
-		handleIdsFromValue(requireJsonObjectOrArrayValue(event.reviewHandles, "review handles"), "review");
-	const qa =
-		stringArray(event.qaHandleIds) ??
-		handleIdsFromValue(requireJsonObjectOrArrayValue(event.qaHandles, "QA handles"), "QA");
-	return { review, qa };
-}
-
-export async function joinUltragoalPipelineOverlap(input: {
-	cwd: string;
-	overlapId: string;
-	reviewResult: JsonObject;
-	qaResult: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt> {
-	const plan = await readUltragoalPlan(input.cwd);
-	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const overlap = openPipelineOverlap(plan);
-	if (!overlap || overlap.overlapId !== input.overlapId)
-		throw new Error(`No open pipeline overlap found for ${input.overlapId}`);
-	const { prior, next, overlapId } = overlap;
-	const nextMetadata = requireFreshPipelineMetadata(next);
-	const ledger = await readUltragoalLedger(input.cwd);
-	const expectedHandles = pipelineStartEventHandleIds(ledger, overlapId);
-	const reviewBlockers = collectPipelineBlockerFootprints(input.reviewResult, "review result");
-	const qaBlockers = collectPipelineBlockerFootprints(input.qaResult, "QA result");
-	const blockerFootprints = [...reviewBlockers, ...qaBlockers];
-	let state: UltragoalPipelineOverlapState;
-	let event: UltragoalPipelineLedgerEventName;
-	if (blockerFootprints.length === 0) {
-		try {
-			requireCleanPipelineResult(input.reviewResult, expectedHandles.review, "review result");
-			requireCleanPipelineResult(input.qaResult, expectedHandles.qa, "QA result");
-			state = "joined_clean";
-			event = "pipeline_overlap_joined";
-		} catch {
-			state = "quarantine_required";
-			event = "pipeline_overlap_quarantined";
-		}
-	} else if (blockerFootprints.every(footprint => !targetsOverlap(footprint, nextMetadata.targets))) {
-		state = "blocked_disjoint_continue";
-		event = "pipeline_overlap_joined";
-	} else {
-		state = "quarantine_required";
-		event = "pipeline_overlap_quarantined";
-	}
-	const now = new Date().toISOString();
-	for (const goal of [prior, next]) {
-		const metadata = requireFreshPipelineMetadata(goal);
-		const joinedMetadata = { ...metadata, overlap: state, blockerFootprints };
-		goal.pipelineMetadata = { ...joinedMetadata, metadataHash: hashPipelineMetadata(joinedMetadata) };
-		goal.updatedAt = now;
-	}
-	if (state === "quarantine_required") next.status = "blocked";
-	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	await appendLedger(input.cwd, {
-		event,
-		eventId: crypto.randomUUID(),
-		timestamp: now,
-		schemaVersion: 1,
-		overlapId,
-		priorGoalId: prior.id,
-		nextGoalId: next.id,
-		status: state,
-		reviewResult: input.reviewResult,
-		qaResult: input.qaResult,
-		blockerFootprints,
-		...pipelineEventRefs(prior, next),
-	});
-	return pipelineReceipt(input.cwd, event, overlapId, prior, next);
-}
-
-export async function rebaselineUltragoalPipelineOverlap(input: {
-	cwd: string;
-	overlapId: string;
-	goalId: string;
-	evidence: string;
-	targetState: JsonObject;
-}): Promise<UltragoalPipelineOverlapReceipt> {
-	const plan = await readUltragoalPlan(input.cwd);
-	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
-	const goal = plan.goals.find(item => item.id === input.goalId);
-	if (!goal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
-	const evidence = input.evidence.trim();
-	if (!isSubstantiveEvidence(evidence)) throw new Error("rebaseline-pipeline-overlap requires substantive evidence");
-	const targetState = requireNonEmptyPipelineTargets(input.targetState, "target state");
-	const metadata = requireFreshPipelineMetadata(goal);
-	if (metadata.overlap !== "quarantine_required" || metadata.overlapId !== input.overlapId) {
-		throw new Error(`Goal ${goal.id} is not quarantined for overlap ${input.overlapId}`);
-	}
-	for (const footprint of metadata.blockerFootprints ?? []) {
-		if (targetsOverlap(footprint, targetState))
-			throw new Error("rebaseline-pipeline-overlap target state overlaps unresolved blocker footprints");
-	}
-	const now = new Date().toISOString();
-	const rebaselinedMetadata = { ...metadata, overlap: "rebaseline_complete" as const, targets: targetState };
-	goal.pipelineMetadata = { ...rebaselinedMetadata, metadataHash: hashPipelineMetadata(rebaselinedMetadata) };
-	goal.status = "active";
-	goal.evidence = evidence;
-	goal.updatedAt = now;
-	plan.updatedAt = now;
-	await writePlan(input.cwd, plan);
-	const peer = pipelinePeer(plan, metadata);
-	await appendLedger(input.cwd, {
-		event: "pipeline_overlap_rebaselined",
-		eventId: crypto.randomUUID(),
-		timestamp: now,
-		schemaVersion: 1,
-		overlapId: input.overlapId,
-		priorGoalId: metadata.priorGoalId ?? peer?.id ?? "",
-		nextGoalId: metadata.nextGoalId ?? goal.id,
-		goalId: goal.id,
-		evidence,
-		targetState,
-		metadataHash: goal.pipelineMetadata.metadataHash,
-	});
-	const paths = getUltragoalPaths(input.cwd, currentUltragoalSessionId(input.cwd));
-	return {
-		ok: true,
-		event: "pipeline_overlap_rebaselined",
-		overlap_id: input.overlapId,
-		prior_goal_id: metadata.priorGoalId ?? peer?.id ?? "",
-		goal_id: goal.id,
-		status: goal.pipelineMetadata.overlap,
-		goals_path: paths.goalsPath,
-		ledger_path: paths.ledgerPath,
-	};
-}