@resolveio/server-lib 22.3.55 → 22.3.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resolveio/server-lib",
-  "version": "22.3.55",
+  "version": "22.3.57",
   "description": "",
   "scripts": {
     "package": "./build_package.sh",

package/src/methods/ai-terminal.ts

@@ -2024,8 +2024,10 @@ async function executeAiAssistantCodexRun(payload: AiCodexRunInput, context: any
 				details
 			});
 		};
+		let requestClassification = classifyAssistantRequestType(message);
+		let dataQuestion = requestClassification.dataQuestion;
 		const progressTracker = createAssistantProgressTracker(assistantMessageId, initialProgress);
-		const streamProgress = createAssistantStreamProgressHandler(progressTracker);
+		const streamProgress = createAssistantStreamProgressHandler(progressTracker, () => dataQuestion);
 		const remainingRunBudgetMs = () => {
 			if (!runDeadlineMs) {
 				return null;
@@ -2063,8 +2065,6 @@ async function executeAiAssistantCodexRun(payload: AiCodexRunInput, context: any
 		let toolResult: AiAssistantToolResult | null = null;
 		let assistantDebug: Record<string, any> | null = null;
 		let directiveSource: 'model' | 'forced' | 'none' = 'none';
-			let requestClassification = classifyAssistantRequestType(message);
-			let dataQuestion = requestClassification.dataQuestion;
 			let lastDirective: AssistantMongoDirective | null = null;
 			let heuristicDirectivePrecomputed: AssistantMongoDirective | null = null;
 			let usedDeterministicHeuristicFastPath = false;
@@ -2793,6 +2793,22 @@ async function executeAiAssistantCodexRun(payload: AiCodexRunInput, context: any
 							}
 						}
 						: directive;
+					const effectiveDirectiveMetadata = effectiveDirective.metadata && typeof effectiveDirective.metadata === 'object'
+						? effectiveDirective.metadata
+						: {};
+					const directiveAcknowledgementText = normalizeOptionalString(effectiveDirectiveMetadata.acknowledgementText);
+					const directiveProgressMessages = Array.isArray(effectiveDirectiveMetadata.progress)
+						? effectiveDirectiveMetadata.progress.map((entry: any) => normalizeOptionalString(entry)).filter(Boolean)
+						: [];
+					const deterministicDataIntentDirective = isAssistantAppDataIntentHeuristicDirective(effectiveDirective);
+					if (deterministicDataIntentDirective) {
+						toolTelemetry.intentId = normalizeOptionalString(effectiveDirectiveMetadata.intentId) || undefined;
+						toolTelemetry.recipeUsed = normalizeOptionalString(effectiveDirectiveMetadata.recipeUsed) || undefined;
+						toolTelemetry.acknowledgementText = directiveAcknowledgementText || undefined;
+						if (!collectionOverride) {
+							toolTelemetry.overrideBlockedReason = 'deterministic_data_intent_preserved_collection';
+						}
+					}
 					const rankedCollections = Array.isArray(collectionRanking?.ranked)
 						? collectionRanking.ranked
 							.map((entry: any) => normalizeOptionalString(entry?.name))
@@ -2820,9 +2836,22 @@ async function executeAiAssistantCodexRun(payload: AiCodexRunInput, context: any
 							deadlineMs: runDeadlineMs || undefined,
 							maxTimeMS: assistantMongoMaxTimeMs
 						};
+						if (isAssistantAppDataIntentHeuristicDirective(value)) {
+							request.__assistantRetryState = {
+								...(request.__assistantRetryState || {}),
+								disableCrossCollectionRetry: true,
+								rootCollection: normalizeOptionalString(request.collection) || undefined
+							};
+						}
 						return request;
 					};
-					progressTracker.push('Grabbing Data');
+					if (directiveAcknowledgementText) {
+						progressTracker.push(directiveAcknowledgementText);
+					}
+					else {
+						progressTracker.push(deterministicDataIntentDirective ? 'Pulling the requested data' : 'Grabbing Data');
+					}
+					directiveProgressMessages.slice(0, 2).forEach(messageText => progressTracker.push(messageText));
 					let executionDirective = effectiveDirective;
 					let probeFieldHints: string[] = [];
 					try {
@@ -2838,7 +2867,9 @@ async function executeAiAssistantCodexRun(payload: AiCodexRunInput, context: any
 							};
 						}
 						else {
-							const aggregateProbeDisabled = executionDirective.type === 'aggregate' && !alwaysAllowProbeEnabled;
+							const aggregateProbeDisabled = executionDirective.type === 'aggregate'
+								&& !alwaysAllowProbeEnabled
+								&& !isAssistantAppDataIntentHeuristicDirective(executionDirective);
 							const probeEnabled = AI_ASSISTANT_TOOL_MAX_STEPS > 1 && !aggregateProbeDisabled;
 							const probeBudgetAllowed = alwaysAllowProbeEnabled
 								|| hasRunBudget('Grabbing Data: probe', AI_ASSISTANT_MONGO_MIN_STAGE_BUDGET_MS);
@@ -6759,8 +6790,253 @@ function isAssistantSchemaHoursHeuristicDirective(directive: AssistantMongoDirec
 	return rawLine.includes('heuristic_agg(schema-hours-user-time)');
 }
 
+function isAssistantAppDataIntentHeuristicDirective(directive: AssistantMongoDirective | null): boolean {
+	const rawLine = normalizeOptionalString(directive?.rawLine).toLowerCase();
+	return rawLine.includes('heuristic_agg(app-data-intent:') || rawLine.includes('heuristic_read(app-data-intent:');
+}
+
+function scoreAssistantAppDataIntent(messageText: string, intent: AiAssistantAppDataIntent): number {
+	if ((intent.excludeTerms || []).some(term => containsAssistantHeuristicTerm(messageText, term))) {
+		return 0;
+	}
+	return (intent.terms || []).reduce((score, term) => {
+		if (!containsAssistantHeuristicTerm(messageText, term)) {
+			return score;
+		}
+		return score + (term.includes(' ') ? 4 : 1);
+	}, 0);
+}
+
+function selectAssistantAppDataIntent(message: string, collectionNames: string[], appId?: string): AiAssistantAppDataIntent | null {
+	const text = normalizeOptionalString(message).toLowerCase();
+	if (!text) {
+		return null;
+	}
+	const availableNames = new Set((Array.isArray(collectionNames) ? collectionNames : []).map(value => normalizeOptionalString(value)).filter(Boolean));
+	const profile = resolveAssistantAppHeuristicProfile(appId);
+	let selected: { intent: AiAssistantAppDataIntent; score: number } | null = null;
+	profile.dataIntents.forEach((intent) => {
+		if (!intent?.id || !intent.collection) {
+			return;
+		}
+		if (availableNames.size && !availableNames.has(intent.collection)) {
+			return;
+		}
+		const score = scoreAssistantAppDataIntent(text, intent);
+		if (score <= 0) {
+			return;
+		}
+		if (!selected || score > selected.score) {
+			selected = { intent, score };
+		}
+	});
+	return selected ? selected.intent : null;
+}
+
+function extractAssistantDataIntentCustomerText(message: string): string {
+	let value = normalizeOptionalString(message);
+	if (!value) {
+		return '';
+	}
+	value = value.replace(/\b(summarize|summary|show|list|give|pull|find|tell|me|about|of|the|a|an|and|amount|quantity|qty|total|totals|for|to|them|their|by)\b/gi, ' ');
+	value = value.replace(/\b(work\s*orders?|wos?|jobs?|invoices?|invoice|billed|billing|revenue|charged|chemicals?|chemical|sent|shipped|shipment|shipments|delivered|planned|inventory|on\s+hand|stock|this\s+year|ytd|year\s+to\s+date|current\s+year)\b/gi, ' ');
+	value = value.replace(/\b(last|past|current|completed|reviewed|closed)\b/gi, ' ');
+	value = value.replace(/[^a-z0-9&.' -]+/gi, ' ');
+	return normalizeOptionalString(value.replace(/\s+/g, ' '));
+}
+
+function resolveAssistantDataIntentDateWindow(message: string): { start?: string; end?: string; year?: number } {
+	const text = normalizeOptionalString(message).toLowerCase();
+	if (!/\b(this\s+year|ytd|year\s+to\s+date|current\s+year)\b/.test(text)) {
+		return {};
+	}
+	const now = new Date();
+	const year = now.getUTCFullYear();
+	return {
+		start: new Date(Date.UTC(year, 0, 1, 0, 0, 0, 0)).toISOString(),
+		end: new Date(Date.UTC(year, now.getUTCMonth(), now.getUTCDate(), 23, 59, 59, 999)).toISOString(),
+		year
+	};
+}
+
+function buildAssistantDataIntentAcknowledgement(
+	intent: AiAssistantAppDataIntent,
+	customerText: string,
+	dateWindow: { year?: number }
+): string {
+	const customer = customerText || 'the requested customer';
+	const yearText = dateWindow.year ? ` for ${dateWindow.year}` : '';
+	if (intent.id === 'snf_job_chemical_shipments') {
+		return `I understand you want a summary of chemicals sent to ${customer} jobs${yearText}. Let me pull the work-order shipment data for you.`;
+	}
+	if (intent.id === 'snf_invoice_chemical_quantities') {
+		return `I understand you want invoice and billed chemical details for ${customer}${yearText}. Let me pull the invoice data for you.`;
+	}
+	if (intent.id === 'snf_planned_job_chemicals') {
+		return `I understand you want planned chemicals for ${customer} jobs${yearText}. Let me pull the job setup data for you.`;
+	}
+	return 'I understand the data you want. Let me pull the matching records for you.';
+}
+
+function buildAssistantDataIntentMatchStage(
+	customerText: string,
+	dateField: string | undefined,
+	dateWindow: { start?: string; end?: string },
+	customerPaths: string[]
+): Record<string, any> {
+	const and: Record<string, any>[] = [];
+	if (customerText) {
+		and.push({
+			$or: customerPaths.map(path => ({
+				[path]: {
+					$regex: customerText,
+					$options: 'i'
+				}
+			}))
+		});
+	}
+	if (dateField && dateWindow.start && dateWindow.end) {
+		and.push({
+			[dateField]: {
+				$gte: dateWindow.start,
+				$lte: dateWindow.end
+			}
+		});
+	}
+	return and.length ? { $match: { $and: and } } : { $match: {} };
+}
+
+function buildAssistantAppDataIntentDirective(message: string, collectionNames: string[] = [], appId?: string): AssistantMongoDirective | null {
+	const intent = selectAssistantAppDataIntent(message, collectionNames, appId);
+	if (!intent) {
+		return null;
+	}
+	const customerText = extractAssistantDataIntentCustomerText(message);
+	const dateWindow = resolveAssistantDataIntentDateWindow(message);
+	const acknowledgementText = buildAssistantDataIntentAcknowledgement(intent, customerText, dateWindow);
+	const progress = intent.progress.map((entry) => {
+		return entry
+			.replace(/\{\{customer\}\}/g, customerText || 'the requested customer')
+			.replace(/\{\{year\}\}/g, dateWindow.year ? String(dateWindow.year) : 'the requested date range');
+	});
+	const metadata = {
+		intentId: intent.id,
+		recipeUsed: intent.id,
+		acknowledgementText,
+		progress,
+		assumptions: intent.assumptions,
+		fallbackCollections: intent.fallbackCollections
+	};
+	const basePayload = (pipeline: Record<string, any>[]) => ({
+		collection: intent.collection,
+		permissionView: intent.permissionView || resolveDefaultAssistantPermissionView(intent.collection),
+		pipeline,
+		options: {
+			allowDiskUse: true,
+			limit: 20
+		}
+	});
+	if (intent.id === 'snf_job_chemical_shipments') {
+		const pipeline: Record<string, any>[] = [
+			buildAssistantDataIntentMatchStage(customerText, intent.dateField || 'date_completed', dateWindow, ['customer', 'job.customer']),
+			{ $match: { status: { $in: ['Completed', 'Reviewed', 'Closed'] } } },
+			{ $unwind: '$chemicals' },
+			{ $match: { 'chemicals.shipped.quantity': { $gt: 0 } } },
+			{
+				$group: {
+					_id: {
+						id_job: '$job.id_job',
+						job: '$job.job',
+						chemical: '$chemicals.chemical',
+						unit: '$chemicals.unit'
+					},
+					qty_sent: { $sum: '$chemicals.shipped.quantity' },
+					work_order_ids: { $addToSet: '$_id' }
+				}
+			},
+			{
+				$project: {
+					_id: 0,
+					id_job: '$_id.id_job',
+					job: '$_id.job',
+					chemical: '$_id.chemical',
+					unit: '$_id.unit',
+					qty_sent: 1,
+					work_order_count: { $size: '$work_order_ids' }
+				}
+			},
+			{ $sort: { qty_sent: -1, job: 1, chemical: 1 } }
+		];
+		return { type: 'aggregate', payload: basePayload(pipeline), cleaned: '', rawLine: `HEURISTIC_AGG(app-data-intent:${intent.id})`, metadata };
+	}
+	if (intent.id === 'snf_invoice_chemical_quantities') {
+		const pipeline: Record<string, any>[] = [
+			buildAssistantDataIntentMatchStage(customerText, intent.dateField || 'date_created', dateWindow, ['customer', 'job.customer']),
+			{ $unwind: '$items_chemicals' },
+			{
+				$group: {
+					_id: {
+						id_job: '$id_job',
+						job: '$job',
+						chemical: '$items_chemicals.chemical',
+						unit: '$items_chemicals.unit'
+					},
+					quantity: { $sum: '$items_chemicals.quantity' },
+					price_total: { $sum: '$items_chemicals.price_total' },
+					invoice_ids: { $addToSet: '$_id' }
+				}
+			},
+			{
+				$project: {
+					_id: 0,
+					id_job: '$_id.id_job',
+					job: '$_id.job',
+					chemical: '$_id.chemical',
+					unit: '$_id.unit',
+					quantity: 1,
+					price_total: 1,
+					invoice_count: { $size: '$invoice_ids' }
+				}
+			},
+			{ $sort: { price_total: -1, quantity: -1, job: 1 } }
+		];
+		return { type: 'aggregate', payload: basePayload(pipeline), cleaned: '', rawLine: `HEURISTIC_AGG(app-data-intent:${intent.id})`, metadata };
+	}
+	if (intent.id === 'snf_planned_job_chemicals') {
+		const pipeline: Record<string, any>[] = [
+			buildAssistantDataIntentMatchStage(customerText, intent.dateField || 'date_job_created', dateWindow, ['customer', 'jca.customer']),
+			{ $unwind: '$planned_chemicals' },
+			{
+				$group: {
+					_id: {
+						id_job: '$_id',
+						job: '$job',
+						chemical: '$planned_chemicals.chemical',
+						unit: '$planned_chemicals.unit'
+					},
+					planned_quantity: { $sum: '$planned_chemicals.quantity' }
+				}
+			},
+			{
+				$project: {
+					_id: 0,
+					id_job: '$_id.id_job',
+					job: '$_id.job',
+					chemical: '$_id.chemical',
+					unit: '$_id.unit',
+					planned_quantity: 1
+				}
+			},
+			{ $sort: { planned_quantity: -1, job: 1 } }
+		];
+		return { type: 'aggregate', payload: basePayload(pipeline), cleaned: '', rawLine: `HEURISTIC_AGG(app-data-intent:${intent.id})`, metadata };
+	}
+	return null;
+}
+
 function isAssistantDeterministicHeuristicDirective(directive: AssistantMongoDirective | null): boolean {
-	return isAssistantSchemaHoursHeuristicDirective(directive);
+	return isAssistantSchemaHoursHeuristicDirective(directive)
+		|| isAssistantAppDataIntentHeuristicDirective(directive);
 }
 
 function buildAssistantHeuristicDirective(
@@ -6772,7 +7048,15 @@ function buildAssistantHeuristicDirective(
 	if (!normalizeOptionalString(message)) {
 		return null;
 	}
-	void collectionNames;
+	const appDataIntentDirective = resolveAssistantDeterministicHeuristicEnabled(
+		AI_ASSISTANT_HEURISTIC_ID_APP_DATA_INTENT,
+		appId
+	)
+		? buildAssistantAppDataIntentDirective(message, collectionNames, appId)
+		: null;
+	if (appDataIntentDirective) {
+		return appDataIntentDirective;
+	}
 	const schemaHoursDirective = resolveAssistantDeterministicHeuristicEnabled(
 		AI_ASSISTANT_HEURISTIC_ID_SCHEMA_HOURS_USER_TIME,
 		appId
@@ -7516,6 +7800,14 @@ function buildAssistantToolResultPayload(
 	const verification = toolResponse?.verification && typeof toolResponse.verification === 'object'
 		? toolResponse.verification
 		: undefined;
+	const directiveMetadata = directive.metadata && typeof directive.metadata === 'object' ? directive.metadata : {};
+	const mergedDebug = {
+		...(toolResponse?.debug && typeof toolResponse.debug === 'object' ? toolResponse.debug : {}),
+		...(normalizeOptionalString(directiveMetadata.intentId) ? { intentId: normalizeOptionalString(directiveMetadata.intentId) } : {}),
+		...(normalizeOptionalString(directiveMetadata.acknowledgementText) ? { acknowledgementText: normalizeOptionalString(directiveMetadata.acknowledgementText) } : {}),
+		...(normalizeOptionalString(directiveMetadata.recipeUsed) ? { recipeUsed: normalizeOptionalString(directiveMetadata.recipeUsed) } : {}),
+		...(Array.isArray(directiveMetadata.assumptions) && directiveMetadata.assumptions.length ? { assumptions: directiveMetadata.assumptions } : {})
+	};
 	const result: AiAssistantToolResult = {
 		type: directive.type === 'aggregate' ? 'mongo_agg' : 'mongo_read',
 		input: directivePayload,
@@ -7527,7 +7819,7 @@ function buildAssistantToolResultPayload(
 			columns: responseDisplay.columns,
 			truncated: responseDisplay.truncated,
 			verification,
-			debug: toolResponse?.debug && typeof toolResponse.debug === 'object' ? toolResponse.debug : undefined
+			debug: Object.keys(mergedDebug).length ? mergedDebug : undefined
 		}
 	};
 	return {
@@ -7726,9 +8018,13 @@ function buildAssistantDisplayLeadSummary(display: AiAssistantDisplayTable | nul
 function buildAssistantToolFallbackResponse(result: AiAssistantToolResult): string {
 	const rowCount = Math.max(0, Number(result.output.rowCount || 0));
 	const source = normalizeOptionalString(result.output.collection);
+	const debug = result.output.debug && typeof result.output.debug === 'object' ? result.output.debug : {};
+	const intentId = normalizeOptionalString((debug as any).intentId);
 	const lines: string[] = rowCount > 0
 		? [`I found ${rowCount === 1 ? '1 matching row' : `${rowCount} matching rows`}${source ? ` from ${source}` : ''}.`]
-		: [`The query ran successfully${source ? ` against ${source}` : ''}, but no matching rows were returned.`];
+		: [intentId
+			? `I checked the ${source || 'selected'} data for that request, but I did not find matching rows for the filters I used.`
+			: `I checked the data${source ? ` in ${source}` : ''}, but no matching rows were returned.`];
 	if (source) {
 		lines.push(`- Source: ${source}`);
 	}
@@ -7736,6 +8032,22 @@ function buildAssistantToolFallbackResponse(result: AiAssistantToolResult): stri
 	if (typeof result.output.total === 'number') {
 		lines.push(`- Total: ${result.output.total}`);
 	}
+	if (rowCount <= 0) {
+		const assumptions = Array.isArray((debug as any).assumptions)
+			? (debug as any).assumptions.map((entry: any) => normalizeOptionalString(entry)).filter(Boolean)
+			: [];
+		if (assumptions.length) {
+			lines.push(`- Assumptions: ${assumptions.slice(0, 3).join('; ')}`);
+		}
+		if (intentId === 'snf_job_chemical_shipments') {
+			lines.push('- I treated "sent" as shipped chemical quantity from completed/reviewed/closed work orders.');
+			lines.push('- If you meant billed quantities or dollars, ask for invoiced/billed chemicals instead.');
+		}
+		else if (intentId === 'snf_invoice_chemical_quantities') {
+			lines.push('- I treated the request as billed invoice chemical quantities and invoice totals.');
+			lines.push('- If you meant field shipments, ask for chemicals shipped/sent on work orders.');
+		}
+	}
 	const leadSummary = buildAssistantDisplayLeadSummary(result.output.display);
 	if (leadSummary) {
 		lines.push('');
@@ -8300,11 +8612,32 @@ function deriveAssistantStreamStatus(event: any): string | null {
 	return null;
 }
 
-function createAssistantStreamProgressHandler(progressTracker: CodexProgressTracker): CodexStreamStatusHandler {
+function normalizeAssistantStreamProgressStatus(status: string, dataMode = false): string {
+	const trimmed = normalizeOptionalString(status);
+	if (!trimmed || !dataMode) {
+		return trimmed;
+	}
+	const normalized = trimmed.toLowerCase();
+	if (normalized === 'planning') {
+		return 'Understanding your request';
+	}
+	if (normalized === 'drafting response') {
+		return 'Preparing the summary';
+	}
+	if (normalized === 'searching files' || normalized === 'finding files' || normalized === 'opening files' || normalized === 'scanning files') {
+		return 'Checking available data';
+	}
+	return trimmed;
+}
+
+function createAssistantStreamProgressHandler(
+	progressTracker: CodexProgressTracker,
+	isDataMode?: () => boolean
+): CodexStreamStatusHandler {
 	let lastStatus = '';
 	let lastSentAt = 0;
 	return (status: string) => {
-		const trimmed = normalizeOptionalString(status);
+		const trimmed = normalizeAssistantStreamProgressStatus(status, isDataMode?.() === true);
 		if (!trimmed) {
 			return;
 		}
@@ -16358,6 +16691,9 @@ function resolveCollectionOverrideWithContext(params: {
 		) {
 			const routePreferredName = normalizeAssistantCollectionOverrideName(routePreferred);
 			const requestedIsWorkOrder = isAssistantWorkOrderCollectionOverrideCandidate(requested);
+			if (shouldPreserveAssistantJobDomainCollectionForRoute(params.message, permissionView, routePreferredName, requested)) {
+				return null;
+			}
 			if (!(routePreferredName === 'orders' && requestedIsWorkOrder && hasAssistantWorkOrderAliasTerms(params.message))) {
 				return {
 					from: requested,
@@ -16484,6 +16820,33 @@ export function resolveCollectionOverrideWithContextForTesting(params: {
 	return resolveCollectionOverrideWithContext(params);
 }
 
+function shouldPreserveAssistantJobDomainCollectionForRoute(
+	message: string,
+	permissionView: string,
+	routePreferredName: string,
+	requestedCollection: string
+): boolean {
+	const route = normalizeOptionalString(permissionView).toLowerCase();
+	const requested = normalizeAssistantCollectionOverrideName(requestedCollection);
+	if (!route || routePreferredName !== 'jobs') {
+		return false;
+	}
+	if (!/\/(?:customer-info\/jobs|job\/list|jobs?)(?:\/|$)/.test(route)) {
+		return false;
+	}
+	const text = normalizeOptionalString(message).toLowerCase();
+	if (!text || !/\b(job|jobs|work\s*orders?|wos?)\b/.test(text)) {
+		return false;
+	}
+	if (requested === 'work-order-dynamics') {
+		return /\b(chemical|chemicals|sent|shipped|shipment|delivered|work\s*orders?|wos?)\b/.test(text);
+	}
+	if (requested === 'invoices') {
+		return /\b(invoice|invoices|billed|billing|revenue|charged|dollars?)\b/.test(text);
+	}
+	return requested === 'jobs';
+}
+
 function isAssistantWorkOrderCollectionOverrideCandidate(value: string): boolean {
 	const normalized = normalizeAssistantCollectionOverrideName(value);
 	return normalized === 'work-order-dynamics'

package/src/util/ai-runner-qa-tools.ts

@@ -258,6 +258,7 @@ export function buildResolveIORunnerLocalQaScript(): string {
 		'cleanup() {',
 		'  [ "${RUNNER_REUSED_READY:-0}" = "1" ] && return 0',
 		'  janitor_stop_heartbeat',
+		'  rm -f "$ARTIFACT_DIR/heartbeat.pid"',
 		'  janitor_update_manifest_status cleanup_started',
 		'  kill_tree "$SERVER_PID"',
 		'  kill_tree "$CLIENT_PID"',
@@ -267,6 +268,15 @@ export function buildResolveIORunnerLocalQaScript(): string {
 		'  rmdir "$LOCK_DIR" >/dev/null 2>&1 || true',
 		'}',
 		'trap cleanup EXIT',
+		'detach_keepalive() {',
+		'  janitor_update_manifest_status ready_keepalive',
+		'  janitor_write_cleanup_status ready_keepalive 0',
+		'  rmdir "$LOCK_DIR" >/dev/null 2>&1 || true',
+		'  trap - EXIT',
+		'  disown >/dev/null 2>&1 || true',
+		'  echo "ResolveIO AI runner QA keepalive detached at $CLIENT_URL; stop with $TOOLS_DIR/stop-local-qa.sh $PROJECT_ROOT."',
+		'  exit 0',
+		'}',
 		'probe_url() { node - "$1" <<\'RESOLVEIO_PROBE\'',
 		'const http = require("http");',
 		'const https = require("https");',
@@ -374,6 +384,7 @@ export function buildResolveIORunnerLocalQaScript(): string {
 		': > "$ARTIFACT_DIR/runner.log"',
 		'janitor_write_manifest',
 		'janitor_start_heartbeat',
+		'echo "$RUNNER_JANITOR_HEARTBEAT_PID" > "$ARTIFACT_DIR/heartbeat.pid"',
 		'janitor_check_resources || exit $?',
 		'if [ -d "$PROJECT_ROOT/server" ]; then',
 		'  SERVER_REQUIRED=1',
@@ -410,7 +421,7 @@ export function buildResolveIORunnerLocalQaScript(): string {
 		'    echo "ResolveIO AI runner QA local app ready at $CLIENT_URL";',
 		'    echo "$SERVER_PID" > "$ARTIFACT_DIR/server.pid";',
 		'    echo "$CLIENT_PID" > "$ARTIFACT_DIR/client.pid";',
-		'    if truthy "$KEEPALIVE"; then echo "ResolveIO AI runner QA keepalive enabled; server/client remain running until this process is stopped."; wait; fi;',
+		'    if truthy "$KEEPALIVE"; then detach_keepalive; fi;',
 		'    exit 0',
 		'    ;;',
 		'  2) echo "ResolveIO AI runner QA client process exited before $CLIENT_URL became ready. See $ARTIFACT_DIR/client.log"; exit 2 ;;',
@@ -483,7 +494,7 @@ export function buildResolveIORunnerLocalQaStopperScript(): string {
 		'}',
 		'janitor_update_manifest_status cleanup_started',
 		'killed_count=0',
-		'for pid_file in "$ARTIFACT_DIR/server.pid" "$ARTIFACT_DIR/client.pid"; do',
+'for pid_file in "$ARTIFACT_DIR/heartbeat.pid" "$ARTIFACT_DIR/server.pid" "$ARTIFACT_DIR/client.pid"; do',
 		'  [ -f "$pid_file" ] || continue',
 		'  pid="$(cat "$pid_file" 2>/dev/null || true)"',
 		'  kill_tree "$pid"',
@@ -693,7 +704,7 @@ export function buildResolveIORunnerQaToolsReadme(options: ResolveIORunnerQaTool
 		`This workspace reserves Angular QA client port ${port}; use \`$${clientUrlVar}\` instead of assuming 4200 is free.`,
 		'The local QA runner starts server/client, polls the reserved client URL, writes `qa-artifacts/server.log` and `qa-artifacts/client.log`, and fails fast on fatal startup/runtime errors.',
 		'The shared auth bootstrap first opens the exact localhost client origin, logs out any visible stale session, clears service workers/cache/IndexedDB/local/session storage, then calls `/login` and `/accessToken`, seeds `refreshToken`, `accessToken`, `user`, and `lastURL`, and writes `qa-artifacts/auth-bootstrap-result.json` plus a ready/failure screenshot.',
-		`For browser clickthrough work, start the runner once with \`${keepaliveVar}=true ${toolsDir}/run-local-qa.sh <project-root> &\` and reuse \`$${clientUrlVar}\` for all login/upload/screenshot retries. Do not restart Angular for auth failures.`,
+		`For browser clickthrough work, start the runner once with \`${keepaliveVar}=true ${toolsDir}/run-local-qa.sh <project-root>\`; it detaches after the app is ready, and later calls should reuse \`$${clientUrlVar}\` for all login/upload/screenshot retries. Do not restart Angular for auth failures.`,
 		'Do not run `npm run build-dev`, `ng build`, or another Angular compile while keepalive `ng serve` is running. If a full Angular build is required after browser QA, first run the staged `stop-local-qa.sh`, then build, then restart `run-local-qa.sh` for final browser proof.',
 		'Use desktop screenshots at 1920x1080 by default unless the task is explicitly mobile/responsive. Every screenshot must have a customer-facing caption.',
 		'For import/export/form-submit/data workflows, prove before/action/after with representative data and a concrete row/count/value assertion.',