Routing hygiene for agent harnesses, structured-output fidelity, OpenRouter hardening, shortfall semantic signals

[veerareddyvishal144]

Summary

Found while benchmarking Lynkr tier routing against openrouter/auto on Terminal-Bench-core 0.1.1 (Terminus agent via LiteLLM, 80 tasks, ~1,200 calls per run). Every change is gated or scoped so Claude Code, Cursor and OpenCode keep their current behaviour unless a flag is set. Final numbers with these changes: 39/80 for $1.28 vs auto 44/80 for $4.72 on the same VM and evening.

Request / response fidelity

• Forward the client's output_format / response_format to every provider (json_schema where the host supports it, json_object otherwise). Lynkr dropped both, so structured-output clients never got schema enforcement.
• Never run the XML tool-call extractor on a JSON-object reply. It mangled command text containing <...> and flipped stop_reason to tool_use.
• Structured-output requests bypass the response cache. Harnesses retry a failed parse with the identical conversation; a cache hit returned the same bad reply every time.
• Remove server-side STANDARD_TOOLS injection from all provider invokers. A tool-less request stays tool-less. Injecting 12 Claude Code tool schemas turned chat / structured clients into tool-calling agents (+~2.5k tokens per call, write access to the host workspace). The OpenAI-compat router's IDE_SAFE_TOOLS injection is left untouched (tied to CLIENT_TOOL_MAPPINGS for Codex) — follow-up.
• FMT_GUARD_ENABLED=false opt-out for the markdown format guard (its "use fenced code blocks" instruction contradicts raw-JSON clients).

Routing on the ask, not the wrapper

• harness-envelope: recognise instruction-schema harness prompts (fixed preamble + JSON schema + Instruction: block) and expose the instruction as the ask for every turn. Complexity analyser, intent scorer, agentic detector, kNN query and window scorer use it. Later user turns are terminal output and previously drove force / risk / text scoring (62 mid-session COMPLEX→MEDIUM demotions in one run).
• client-profiles: terminus profile (tool-less by design) with prompt-pattern detection; tool-less profiles excluded from side-request detection.
• agentic-detector: drop solve from the autonomous regex — "solving command-line tasks" boilerplate pinned every request to REASONING.
• FORCE_TIER_PATTERNS=false, RISK_TIER_ESCALATION=false opt-outs for the keyword escalators.
• kNN: LYNKR_KNN_ENABLED=false skips the query and its embedding call; picks are validated against configured TIER_* models (the index remembered a decommissioned model and sent 81 calls to it).
• embeddings: cap input at 5000 chars (nomic-embed-text's 2048-token context), surface Ollama's error body, retry once with halved text on input-too-long instead of degrading the provider for 60s.

Provider plumbing and verification

• [ModelCheck] warning when the served model differs from the tier's requested model (live incident: TIER_*=zai:glm-5.3-flash silently served by ZAI_MODEL=glm-5.2 for two full runs).
• Z.AI: unknown tier model ids pass through instead of falling back to the default model.
• OpenRouter: per-model provider pin, per-model reasoning effort, strict json_schema for hosts that honour it, usage.include for provider-reported cached / reasoning tokens and cost, per-model upstream timeout with failover down the pinned list before tier-fallback climbs, per-model output cap, [ProviderCheck] warning when an unpinned host served. Replies converted in the invoker with cache_read mapped from prompt_tokens_details.cached_tokens.
• Fireworks: per-model reasoning effort map, keep thinking enabled for models that reject thinking:disabled, response_format forwarding.
• OpenAI-compatible: reasoning_effort knob and response_format forwarding.
• Baidu Qianfan: clamp max_tokens to 12288 (hard provider limit).

Shortfall: semantic requirement + Jev telemetry (second commit)

• Shortfall's requirement vector came from the structural complexity dimensions only and was nearly constant on task-description prompts (0.11–0.34 across 77 Terminal-Bench tasks), so cheapest-covering always picked the cheapest model. shortfall.liftRequirement now lifts each head with the anchor intent score (interpolated between tier profiles) and the Jev tier probabilities (probability-weighted profile); never lowers. Replay: requirement median 0.15 → 0.61, agreement with the anchor+Jev pick 51/61.
• Jev verdicts were null on 100% of served telemetry rows while the judge re-tiered ~36% of fresh routes. Two gaps: the window wrapper stores the verdict as _jev (reader only knew jev/analysis.jev) and the forced-provider hop never carried it. jevFields reads _jev, api/router.js stamps req.body._jev, the reconstituted routingResult sets jev. Verified live: verdict, confidence, probabilities and judge model now land on every row.
• New test/shortfall-semantic.test.js.

Declarative routing, outcome attribution, operator tooling (third/fourth commits)

• Signals → decisions as config (config/routing.json, validated, hot-reloaded). Default = one legacy decision, so nothing changes until edited; config/routing.example.json shows a Terminus-oriented policy. AND/OR/NOT rules, priority, per-decision tier/effort/hosts/plugins, observe vs enforce mode, full trace.
• Turn-outcome attribution (src/routing/outcomes.js): progress / no_progress / regression / provider_error / tool_error / missing, with a model-attributable flag; environment noise never yields a reward. Recorded per request (prev_turn_outcome).
• Per-decision reasoning effort honoured by the OpenRouter/Fireworks invokers.
• lynkr route --preview explains every signal and decision for a request without calling a provider; lynkr audit <session> prints the per-turn ledger. Optional X-Lynkr-Decision* headers.
• Corpus regression gate: 77 signal-snapshot fixtures replayed through the pure decision step in test:unit.
• Evaluation records in model-capabilities.json outrank overrides/seeds; calibrate-capabilities --apply writes them. scripts/cache-probe.js measures prompt-cache behaviour per host.

Test plan

• npm run test:unit: 1562 pass / 6 fail on this branch and on main (the 6 are pre-existing, environment-dependent: Jev LRU, TencentDB launcher, downgrade gate, task-ledger).
• Live: Terminus harness end-to-end through Lynkr on OpenRouter (Friendli glm-5.3-flash cheap tier, DeepSeek official strong tier): two full 80-task runs, 0 wrong-model warnings, 0 harness parse failures, failover drill (forced timeout → next host → tier climb) verified.
• Requests that carry their own tools still forward them (probed: tool_use block returned).

New flags are documented in .env.example. Happy to split this into smaller PRs (tool-injection removal / structured output / harness awareness / OpenRouter hardening) if preferred.

🤖 Generated with Claude Code

[github-actions]

🔍 OpenCodeReview found 10 issue(s) in this PR.

• ✅ Successfully posted inline: 10 comment(s)

[github-actions]

The backup file write is not validated before overwriting the config. If copyFileSync fails (e.g., permission issues), the config could be partially overwritten or lost. Add a check after copyFileSync to ensure the backup exists before proceeding with the rewrite.

[github-actions]

The _INPUT_LENGTH_RE regex at line 184 is overly broad and could match false positives. The pattern context length|input length|too long|exceeds? (the )?(maximum|context)|maximum context would incorrectly match valid messages containing these words. For example, "too long" appears in many contexts unrelated to errors. Consider making the regex more specific by anchoring to error contexts (e.g., case sensitivity, surrounding keywords like "error", "rejected", or requiring specific error message patterns from known providers).

Suggestion:

Suggested change

	const _INPUT_LENGTH_RE = /context length|input length|too long|exceeds? (the )?(maximum|context)|maximum context/i;
	const _INPUT_LENGTH_RE = /\b(context|input)\s+length\s+\b(exceeds?|too long)\b|\bmaximum\s+(context|length)\b|\binput\s+too\s+long\b/i;

[github-actions]

At line 2266, body._tierModel is accessed without null checking. When body._tierModel is falsy, the expression (body._tierModel ? requestedModel : null) correctly returns null, but if _tierModel is an empty string or 0, it will use requestedModel (the original value). This could lead to unexpected behavior. Better to explicitly check typeof body._tierModel === 'string' && body._tierModel to ensure it's a valid non-empty string.

[github-actions]

In src/orchestrator/index.js, the JSON detection check startsWith("{") && endsWith("}") is fragile and can be bypassed by strings containing JSON anywhere within them. For example, a string like "Here is the JSON: {"key": "value"}" would incorrectly skip extraction. A more robust approach would be to try parsing with JSON.parse() in a try-catch block, or check for a more specific pattern.

Suggestion:

Suggested change

	const _bt = block.text.trim();
	if (_bt.startsWith("{") && _bt.endsWith("}")) continue;
	const _bt = block.text.trim();
	try {
	JSON.parse(_bt); continue; // Valid JSON object
	} catch {}
	// Only try to parse first/last char if trim didn't change the string
	if (_bt === block.text && _bt.startsWith("{") && _bt.endsWith("}")) continue;

[github-actions]

In src/orchestrator/index.js, there's duplicated logic for JSON detection on two separate code paths (lines 2318-2319 and 2346-2347). This could be extracted into a helper function like isJsonReply(content) to avoid duplication.

Suggestion:

Suggested change

	if (toolCalls.length === 0 && typeof message.content === "string" && message.content.trim()
	&& !(message.content.trim().startsWith("{") && message.content.trim().endsWith("}"))) {
	const isJsonReply = (text) => {
	const trimmed = text.trim();
	if (trimmed === text && trimmed.startsWith("{") && trimmed.endsWith("}")) return true;
	try { JSON.parse(trimmed); return true; } catch {}
	return false;
	};
	// Then use: !isJsonReply(message.content)

[github-actions]

In src/routing/complexity-analyzer.js, both shouldForceCloud and shouldForceReasoning extract content using extractContent(payload) which could return '' (empty string) if payload has no messages. The regex patterns might match unexpected empty content. Consider adding an explicit check for empty content before pattern matching.

Suggestion:

Suggested change

	if (process.env.FORCE_TIER_PATTERNS === "false") return false;
	const content = extractContent(payload);
	if (process.env.FORCE_TIER_PATTERNS === "false") return false;
	const content = extractContent(payload);
	if (!content || !content.trim()) return false;

[github-actions]

In src/routing/index.js, the check if (knnResult && process.env.LYNKR_KNN_ENABLED === 'false') is redundant when the outer code already checks config.routing?.knnEnabled !== false && process.env.LYNKR_KNN_ENABLED !== 'false'. The inner check will never be true unless LYNKR_KNN_ENABLED changes between checks (which shouldn't happen). This nested check is defensive but unnecessary.

Suggestion:

Suggested change

	if (knnResult && process.env.LYNKR_KNN_ENABLED === 'false') {
	knnResult = null;
	}
	// This check is redundant given the outer condition already checks LYNKR_KNN_ENABLED
	// Consider removing or adding a comment explaining why it's needed

[github-actions]

In src/routing/index.js, the kNN tier validation code has duplicated logic in two try-catch blocks (one for success, one for error handling). The same model set construction code appears twice. This could be extracted into a helper function to avoid duplication.

Suggestion:

Suggested change

	const _sel = getModelTierSelector();
	const _allowed = new Set();
	for (const _t of TIER_ORDER) for (const _m of (_sel.getModelsForTier(_t) || [])) _allowed.add(`${_m.provider}:${_m.model}`);
	const getModelSetFromTiers = () => {
	const _sel = getModelTierSelector();
	const _allowed = new Set();
	for (const _t of TIER_ORDER) for (const _m of (_sel.getModelsForTier(_t) || [])) _allowed.add(`${_m.provider}:${_m.model}`);
	return _allowed;
	};
	// Then use: const _allowed = getModelSetFromTiers();

[github-actions]

In src/routing/shortfall.js, the liftRequirement function uses default parameters (anchorScore = null, jev = null) which is good. However, it doesn't validate that the input req object actually has the expected properties (HEADS), which could cause issues if an unexpected object is passed.

Suggestion:

Suggested change

	function liftRequirement(req, { anchorScore = null, jev = null } = {}, tierProfiles = null) {
	function liftRequirement(req, { anchorScore = null, jev = null } = {}, tierProfiles = null) {
	if (!req || typeof req !== 'object') return { req: {}, lift: { anchor: null, jev: null, applied: [] } };

[github-actions]

The liftRequirement function uses Array.includes() to track which lifts were applied ('anchor', 'jev'). This is inefficient and could be simplified by just counting the number of successful lifts instead of maintaining an array.

Suggestion:

Suggested change

	for (const h of HEADS) {
	if (a && a[h] > out[h]) { out[h] = a[h]; if (!applied.includes('anchor')) applied.push('anchor'); }
	if (j && j[h] > out[h]) { out[h] = j[h]; if (!applied.includes('jev')) applied.push('jev'); }
	const appliedSet = new Set();
	for (const h of HEADS) {
	if (a && a[h] > out[h]) { out[h] = a[h]; appliedSet.add('anchor'); }
	if (j && j[h] > out[h]) { out[h] = j[h]; appliedSet.add('jev'); }
	out[h] = Math.round(Math.max(0, Math.min(1, out[h])) * 1000) / 1000;
	}
	const applied = [...appliedSet];

[github-actions]

package.json update: Added test/shortfall-semantic.test.js to test:unit. No dependency conflicts or duplicate declarations found. All tools referenced in scripts (eslint, pino-pretty) are declared in devDependencies.

[github-actions]

Unsanitized file paths: The script reads user-supplied paths (--model=run-dir, --out) and writes to them without validation.

Suggestion:

Suggested change

	const v = next(); const eq = v.indexOf('=');
	out.models.push(eq > 0 ? { spec: v.slice(0, eq), runDir: expand(v.slice(eq + 1)) } : { spec: v, runDir: null });
	// Validate runDir exists and is accessible before using
	if (m.runDir && !fs.existsSync(m.runDir)) die(`--model run-dir does not exist: ${m.runDir}`);

[github-actions]

Inconsistent error messages: --help prints usage before exit, but validation errors via die() don't. Users encountering errors may not know valid arguments.

Suggestion:

Suggested change

	else die(`unknown arg ${a}`);
	else { console.error(`unknown arg: ${a}`); console.error('Run with --help for usage'); die(''); }

[github-actions]

Hardcoded .env paths: The script assumes .env is in process.cwd() or os.homedir(). This may fail in containerized or different working directory contexts.

Suggestion:

Suggested change

	const srcEnv = fs.existsSync(path.join(process.cwd(), '.env')) ? path.join(process.cwd(), '.env') : path.join(os.homedir(), '.env');
	// Add --env-path flag or look for .env relative to ROOT, then cwd, then homedir
	const envPaths = [path.join(ROOT, '.env'), path.join(process.cwd(), '.env'), path.join(os.homedir(), '.env')];

[github-actions]

Repeated string pattern: fs.existsSync(path.join(process.cwd(), '.env')) ? path.join(process.cwd(), '.env') : path.join(os.homedir(), '.env') appears twice and should be extracted.

Suggestion:

Suggested change

	const srcEnv = fs.existsSync(path.join(process.cwd(), '.env')) ? path.join(process.cwd(), '.env') : path.join(os.homedir(), '.env');
	function findEnvPath() {
	const cwd = path.join(process.cwd(), '.env');
	if (fs.existsSync(cwd)) return cwd;
	return path.join(os.homedir(), '.env');
	}

[github-actions]

The terminus profile's prompt pattern matches the HARNESS_PREAMBLE_RES pattern in harness-envelope.js. This creates tight coupling between client detection and harness parsing logic. Consider unifying these patterns or moving to a shared configuration file.

[github-actions]

Same dynamic require pattern here - could cause circular dependency issues if the module loading order changes.

[github-actions]

The harness prompt detection pattern /You are an AI assistant tasked with solving command-line tasks/i is very broad and may match non-harness prompts from various providers. Consider making it more specific to your actual harness system.

Suggestion:

Suggested change

	const HARNESS_PREAMBLE_RES = [
	/You are an AI assistant tasked with solving command-line tasks/i,
	/"title":\s*"CommandBatchResponse"/,
	];
	const HARNESS_PREAMBLE_RES = [
	// Match more specific harness identifiers to avoid false positives
	/You are an AI assistant.*?command-line tasks.*?harness/i,
	/"title":\s*"CommandBatchResponse"/,
	];

[github-actions]

The kNN tier validation loop creates a Set and iterates all tiers every request. If TIER_ORDER has many tiers/models, this could add latency to every routed request.

[github-actions]

Same dynamic require pattern here - could cause circular dependency issues if the module loading order changes.

[github-actions]

The audit script reads from a SQLite database file located in the current working directory (.lynkr/telemetry.db) without verifying file permissions or ownership. If the directory has overly permissive permissions, unauthorized users could read sensitive telemetry data including cost, latency, model decisions, and error information.

Suggestion:

Suggested change

	const dbPath = path.resolve(process.cwd(), '.lynkr', 'telemetry.db');
	if (!fs.existsSync(dbPath)) { console.error(`no telemetry db at ${dbPath}`); process.exit(2); }
	// Verify database file has appropriate restrictive permissions (e.g., owner-only access)
	const dbPath = path.resolve(process.cwd(), '.lynkr', 'telemetry.db');
	const dbStats = fs.statSync(dbPath);
	if (dbStats.mode & 0o444 || dbStats.mode & 0o222) {
	console.error('database file has insecure permissions');
	process.exit(2);
	}

[github-actions]

Both CLI scripts call process.exit() without returning from the main() function. While this works, it's inconsistent and could cause issues if the functions are called from tests or other modules.

Suggestion:

Suggested change

	if (!fs.existsSync(dbPath)) { console.error(`no telemetry db at ${dbPath}`); process.exit(2); }
	if (!fs.existsSync(dbPath)) {
	console.error(`no telemetry db at ${dbPath}`);
	return 2;
	}

[github-actions]

JSON.stringify is used for terminal output without any post-processing to sanitize sensitive data that could leak into the output object.

Suggestion:

Suggested change

	if (json) { console.log(JSON.stringify(rows, null, 2)); return; }
	// Sanitize or exclude sensitive fields from output
	const sanitizedRows = rows.map(r => {
	const { ...rest } = r;
	// Remove or redact sensitive fields if needed
	return rest;
	});
	console.log(JSON.stringify(sanitizedRows, null, 2));

[github-actions]

The audit script computes cached percentage using integer arithmetic that could produce confusing results for edge cases (e.g., when cached > input tokens).

Suggestion:

Suggested change

	console.log(`\n cost $${cost.toFixed(4)} in ${inTok} (cached ${cached}, ${inTok ? Math.round(100 * cached / (inTok + cached)) : 0}%) out ${outTok} errors ${errs}\n`);
	// Add comment explaining the calculation or use clearer logic
	console.log(`\n cost $${cost.toFixed(4)} in ${inTok} (cached ${cached}, cached share: ${inTok + cached ? Math.round(100 * cached / (inTok + cached)) : 0}%) out ${outTok} errors ${errs}\n`);

[github-actions]

The route script reads request payloads from files or stdin without validating file size limits. A user could provide an extremely large JSON file (e.g., >100MB) that would exhaust available memory when loaded into memory with fs.readFileSync.

Suggestion:

Suggested change

	const raw = file === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(file, 'utf8');
	// Set a reasonable file size limit (e.g., 10MB) to prevent memory exhaustion
	const MAX_FILE_SIZE = 10 * 1024 * 1024;
	const stats = fs.statSync(file);
	if (stats.size > MAX_FILE_SIZE) {
	console.error('input file exceeds maximum size limit (10MB)');
	process.exit(2);
	}
	const raw = fs.readFileSync(file, 'utf8');

[github-actions]

The LYNKR_ROUTING_CONFIG environment variable is resolved directly via path.resolve() without sanitization. If this env var is user-controllable, it could enable path traversal attacks. Validate the resolved path stays within the expected directory.

Suggestion:

Suggested change

	function configPath() {
	return process.env.LYNKR_ROUTING_CONFIG ? path.resolve(process.env.LYNKR_ROUTING_CONFIG) : DEFAULT_PATH;
	}
	function configPath() {
	const envPath = process.env.LYNKR_ROUTING_CONFIG;
	if (!envPath) return DEFAULT_PATH;
	const resolved = path.resolve(envPath);
	// Validate resolved path stays within allowed directory
	const allowedDir = path.resolve(__dirname, '..', '..', 'config');
	if (!resolved.startsWith(allowedDir)) {
	logger.warn({ path: resolved }, '[RoutingConfig] invalid config path — using default');
	return DEFAULT_PATH;
	}
	return resolved;
	}

[github-actions]

The interpolation formula (s - a) / (b - a) risks division by zero if two tier midpoints have the same value. Add a guard to handle this edge case before division.

Suggestion:

Suggested change

	for (let i = 0; i < pts.length - 1; i++) {
	const [a, va] = pts[i], [b, vb] = pts[i + 1];
	if (s >= a && s <= b) {
	const f = (s - a) / (b - a);
	for (let i = 0; i < pts.length - 1; i++) {
	const [a, va] = pts[i], [b, vb] = pts[i + 1];
	if (s >= a && s <= b) {
	const diff = b - a;
	const f = diff === 0 ? 0 : (s - a) / diff;

[github-actions]

The interpolation formula (s - a) / (b - a) risks division by zero if two tier midpoints have the same value. Add a guard to handle this edge case before division.

Suggestion:

Suggested change

	for (let i = 0; i < pts.length - 1; i++) {
	const [a, va] = pts[i], [b, vb] = pts[i + 1];
	if (s >= a && s <= b) {
	const f = (s - a) / (b - a);
	for (let i = 0; i < pts.length - 1; i++) {
	const [a, va] = pts[i], [b, vb] = pts[i + 1];
	if (s >= a && s <= b) {
	const diff = b - a;
	const f = diff === 0 ? 0 : (s - a) / diff;

[github-actions]

The harnessAskFromPayload module is required inside two evaluator functions. While Node.js caches modules, this creates unnecessary require calls and could cause circular dependency issues. Move the require to the top of the file.

Suggestion:

Suggested change

	harness(ctx) {
	const { harnessAskFromPayload } = require('./harness-envelope');
	const { harnessAskFromPayload } = require('./harness-envelope');
	const EVALUATORS = {
	harness(ctx) {

[github-actions]

The harnessAskFromPayload module is required inside two evaluator functions. While Node.js caches modules, this creates unnecessary require calls and could cause circular dependency issues. Move the require to the top of the file.

Suggestion:

Suggested change

	harness(ctx) {
	const { harnessAskFromPayload } = require('./harness-envelope');
	const { harnessAskFromPayload } = require('./harness-envelope');
	const EVALUATORS = {
	harness(ctx) {

[github-actions]

The audit command checks file existence with fs.existsSync() before opening the database, which is good. However, if the database file exists but is empty or has no schema, the Database constructor may still fail. Add more robust error handling around the Database instantiation.

[github-actions]

The 'better-sqlite3' package is required at runtime but not verified before use. If this package is not installed in the current environment, the command will crash with a module loading error. Consider adding a try/catch around the require or adding it to package.json dependencies explicitly.

[github-actions]

Environment variables LOG_LEVEL='silent' and LOG_FILE_ENABLED='false' are set to suppress all logging. While this reduces noise in the preview output, it may also suppress important error diagnostics from the routing module if unexpected issues occur during evaluation.

[github-actions]

New test files are added to the test:unit script: test/shortfall-semantic.test.js, test/routing-decisions.test.js, test/routing-corpus.test.js, and test/switch-gate-grounding.test.js. These correspond to new routing-related source files introduced in the PR. Ensure these test files exist and are properly implemented before merging.

Suggestion:

Suggested change

"test:unit": "LYNKR_KNN_DIR=/tmp/lynkr-test-knn DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com LOG_FILE_ENABLED=false node --test test/routing.test.js test/hybrid-routing-integration.test.js test/retry-logic.test.js test/sse-transformer.test.js test/passthrough-stream.test.js test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js test/azure-openai-config.test.js test/azure-openai-format-conversion.test.js test/azure-openai-routing.test.js test/azure-openai-streaming.test.js test/azure-openai-error-resilience.test.js test/azure-openai-integration.test.js test/openai-integration.test.js test/atlas-integration.test.js test/toon-compression.test.js test/gcf-compression.test.js test/llamacpp-integration.test.js test/resilience.test.js test/telemetry-routing.test.js test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js test/memory/distiller.test.js test/memory/distiller-freeze.test.js test/memory/wiki.test.js test/memory/skills-cache.test.js test/memory/tencentdb-launcher.test.js test/distill.test.js test/large-payload.test.js test/prompt-cache-injection.test.js test/risk-analyzer.test.js test/interaction-block.test.js test/preflight.test.js test/token-reduction.test.js test/session-affinity.test.js test/cache-state.test.js test/cache-switch-cost.test.js test/lens-recommendations.test.js test/model-registry-cost.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js test/init.test.js test/tool-call-response-metadata.test.js test/degradation.test.js test/routing-telemetry-columns.test.js test/sticky-routing.test.js test/knn-ambiguous-escalate.test.js test/deescalator.test.js test/client-profiles.test.js test/strip-internal-fields.test.js test/complexity-tool-subtraction.test.js test/bandit.test.js test/routing-propensity.test.js test/reward-pipeline.test.js test/knn-cold-start.test.js test/calibration.test.js test/feedback-loop.test.js test/session-fingerprint.test.js test/side-request-guards.test.js test/verifier.test.js test/intent-score.test.js test/difficulty-classifier.test.js test/classifier-setup.test.js test/usage-stats.test.js test/loop-guard.test.js test/moonshot-model-mapping.test.js test/baidu-model-mapping.test.js test/tenant-policy-ingress-parity.test.js test/decide.test.js test/embeddings-degradation.test.js test/health-probe.test.js test/stuck-detector.test.js test/onnx-embedder.test.js test/ope.test.js test/hierarchical-budget.test.js test/token-rate-limit.test.js test/otel-export.test.js test/mcp-broker.test.js test/compression-budget.test.js test/gpt-utils.test.js test/dedup-observe-only.test.js test/context-window-header.test.js test/token-budget-auto.test.js test/opencode-setup.test.js test/auth-mode-first-party.test.js test/harness-envelope.test.js test/task-ledger.test.js test/jev-router.test.js test/jev-routing.test.js test/force-patterns.test.js test/upstream-fidelity.test.js test/tool-schema-compression.test.js test/passthrough-route.test.js test/quota-ledger.test.js test/shortfall-semantic.test.js test/routing-decisions.test.js test/routing-corpus.test.js test/switch-gate-grounding.test.js",

Verify that the corresponding test files exist in the `test/` directory and contain valid test cases.

[github-actions]

The findRunRoot function doesn't verify that directory entries are actually directories before checking for results.json inside them. If a file with a nested path exists, this could throw an error. Add a directory check to be safe.

Suggestion:

Suggested change

	function findRunRoot(dir) {
	if (fs.existsSync(path.join(dir, 'results.json'))) return dir;
	const subs = fs.readdirSync(dir).filter((d) => fs.existsSync(path.join(dir, d, 'results.json'))).sort().reverse();
	return subs.length ? path.join(dir, subs[0]) : null;
	}
	function findRunRoot(dir) {
	if (fs.existsSync(path.join(dir, 'results.json'))) return dir;
	const subs = fs.readdirSync(dir).filter((d) => fs.statSync(path.join(dir, d)).isDirectory() && fs.existsSync(path.join(dir, d, 'results.json'))).sort().reverse();
	return subs.length ? path.join(dir, subs[0]) : null;
	}

[github-actions]

Hardcoded environment variable 'FORCE_TIER_PATTERNS' is used directly in the logic. Consider centralizing this in routing-config.js or using a shared constants file for environment variable names to maintain consistency across the codebase.

[github-actions]

Harness detection is implemented in multiple places: client-profiles.js uses promptPatterns for pattern detection, while harness-envelope.js uses matchHarness() and isHarnessPrompt(). Consider whether these should share a common implementation or at least use consistent pattern sets.

[github-actions]

Variables _structuralReq and _lifted are declared with underscores suggesting internal use, but they are only used for telemetry logging. If they're needed only for observability, consider using a more descriptive naming convention or documenting why these intermediate values are needed.

[github-actions]

The signal merging on line 120 is shallow: signals: { ...DEFAULT_CONFIG.signals, ...(raw.signals || {}) }. This means if you try to override a signal with nested properties (e.g., { anchor: { type: 'anchor_score', extra_option: true } }), you would lose nested properties from DEFAULT_CONFIG. Since the current schema only uses simple { type, ...options } patterns without nested structures, this works today but could break with future schema changes.

Suggestion:

Suggested change

	const merged = { ...DEFAULT_CONFIG, ...raw, signals: { ...DEFAULT_CONFIG.signals, ...(raw.signals || {}) } };
	// Consider a deep merge utility if nested signal options are ever needed
	const merged = { ...DEFAULT_CONFIG, ...raw, signals: { ...DEFAULT_CONFIG.signals, ...(raw.signals || {}) } };

[github-actions]

Add a _clear() function call at application shutdown or periodically to drain _state entries that have exceeded max_switches_per_session but haven't hit TTL yet. This prevents memory growth from long-lived but inactive sessions.

Suggestion:

Suggested change

	const TTL_MS = 6 * 60 * 60 * 1000;
	const _state = new Map(); // sessionId -> { ts, floor, switches, lastSwitchTurn }
	const _pinnedProviders = openRouterBody._pinnedProviders; delete openRouterBody._pinnedProviders;
	const _schemaOkFn = openRouterBody._schemaOk; delete openRouterBody._schemaOk;
	const _timeoutMs = openRouterBody._timeoutMs; delete openRouterBody._timeoutMs;
	// ... request code ...
	// Restore ALL deleted properties to avoid mutating original body
	if (_pinnedProviders) openRouterBody._pinnedProviders = _pinnedProviders;
	if (_schemaOkFn) openRouterBody._schemaOk = _schemaOkFn;
	if (_timeoutMs) openRouterBody._timeoutMs = _timeoutMs;

[github-actions]

The config/routing.json uses camelCase for signal keys (e.g., tool_count, turn, risk) but config/routing.example.json uses snake_case variants. In src/routing/signals.js, signals are accessed using camelCase keys. This inconsistency in the example config could lead to confusion when using it as a template.

[github-actions]

The config/routing.json anchor_bands uses exclusive-high ranges (e.g., SIMPLE: [0, 20] means 0 ≤ score < 20). This is documented implicitly in anchorBandFor() which uses s >= lo && s < hi. Consider adding a comment in the config file to make this contract explicit for future maintainers.

[github-actions]

The config/routing.json defines a tool_count signal but the complexity signal's bandwidth assignment (line 130 in signals.js) doesn't use it. The signal keys in both config files should be documented to match the signal handlers in src/routing/signals.js.

[github-actions]

build-routing-corpus.js parses JSON files synchronously on line 36. For large directories, consider parallel parsing with Promise.all or streaming JSON parsing.

[github-actions]

Duplicate logic across multiple scripts: findRunRoot() and expand() are repeated in calibrate-capabilities.js, build-complexity-exemplars.js, build-routing-corpus.js, eval-complexity-signal.js, and validate-grounding.js. Extract these into a shared utility module.

[github-actions]

In anchorRequirement() and jevRequirement(), loadProfiles().tierProfiles is accessed without checking if tierProfiles was explicitly passed as null. If tierProfiles is undefined, loadProfiles() is called which may return null tierProfiles in the error path. Consider adding explicit null checks.

[github-actions]

In session_phase and complexity evaluators, ctx.payload?.messages is accessed without ensuring ctx.payload exists. Although optional chaining (?.) is used, accessing .filter on an undefined result of ctx.payload?.messages could still fail if the property structure is unexpected. Ensure ctx.payload is checked before accessing messages.

[github-actions]

The complexity evaluator synchronously reads the exemplars file. While cached, this blocks the event loop during initialization. Consider migrating to fs.promises for non-blocking startup.

[github-actions]

The global _state Map stores per-session state but relies solely on TTL for cleanup. Long-running processes without active sessions may accumulate stale entries. Consider exposing a periodic cleanup interval or explicit eviction mechanism for production use.

[github-actions]

In engineFields, nested property access like src.engine?.cascade?.triggered uses optional chaining but may still fail if intermediate objects exist but are null. Ensure all levels are properly guarded.

[github-actions]

Hardcoded database path '.lynkr/telemetry.db' may fail in different deployment environments. Consider adding an environment variable override (e.g., LYNKR_TELEMETRY_DB_PATH) or config option similar to how routing.json is handled.

Suggestion:

Suggested change

	const dbPath = path.resolve(process.cwd(), '.lynkr', 'telemetry.db');
	const dbPath = process.env.LYNKR_TELEMETRY_DB_PATH || path.resolve(process.cwd(), '.lynkr', 'telemetry.db');

[github-actions]

Using JSON.stringify on potentially untrusted data in output could expose unexpected data. The tool reads from telemetry database which is controlled, but consider document output if telemetry could contain user-provided fields.

[github-actions]

JSON.parse() called on user input without structural validation. Consider adding a schema validator to prevent prototype pollution or malformed payloads from causing unexpected behavior.

Suggestion:

Suggested change

	try { payload = JSON.parse(raw); } catch (e) { console.error(`not JSON: ${e.message}`); process.exit(2); }
	try { payload = JSON.parse(raw); if (!payload || typeof payload !== 'object') { throw new Error('payload must be an object'); } } catch (e) { console.error(`invalid JSON: ${e.message}`); process.exit(2); }

[github-actions]

Multiple hardcoded .env file paths (cwd then homedir) may be unexpected in containerized environments. Consider adding an environment variable override for consistency with other config paths.

Suggestion:

Suggested change

	const envPath = fs.existsSync(path.join(process.cwd(), '.env')) ? path.join(process.cwd(), '.env') : path.join(require('os').homedir(), '.env');
	const envPath = process.env.LYNKR_DOTENV_PATH || (fs.existsSync(path.join(process.cwd(), '.env')) ? path.join(process.cwd(), '.env') : path.join(require('os').homedir(), '.env'));

[github-actions]

The key prev is used in decisions but the actual signal type is prev_outcome (see src/routing/signals.js line 136). This creates a mismatch between the config schema and the signal registry.

Suggestion:

Suggested change

	"prev": {
	"type": "prev_outcome"
	},
	"prev_outcome": {
	"type": "prev_outcome"
	}

[github-actions]

Inconsistent null comparison: a != null should use strict equality !== null to align with the codebase conventions.

Suggestion:

Suggested change

	console.log(`${model.padEnd(34)} ${String(host).padEnd(12)} ${String(a.ms).padStart(8)} ${String(b.ms).padStart(8)} ${String(b.cached).padStart(7)} ${String(hit).padStart(5)} ${a.cost != null ? a.cost.toFixed(6).padStart(9) : ' -'} ${b.cost != null ? b.cost.toFixed(6).padStart(9) : ' -'} ${note}`);
	console.log(`${model.padEnd(34)} ${String(host).padEnd(12)} ${String(a.ms).padStart(8)} ${String(b.ms).padStart(8)} ${String(b.cached).padStart(7)} ${String(hit).padStart(5)} ${a.cost !== null ? a.cost.toFixed(6).padStart(9) : ' -'} ${b.cost !== null ? b.cost.toFixed(6).padStart(9) : ' -'} ${note}`);

[github-actions]

The lynkr.kill() cleanup only runs if spawnSync completes. If the tb command throws an exception (not a non-zero exit), the orphaned Lynkr process may not be terminated. Consider wrapping the tb spawn in a try-finally to ensure cleanup.

Suggestion:

Suggested change

	const r = spawnSync(tb, ['run', '--dataset', opts.dataset, '--agent', 'terminus', '--model', 'anthropic/claude-sonnet-4-5',
	'--n-concurrent-trials', String(opts.concurrency), '--output-path', outDir], {
	try {
	const r = spawnSync(tb, ['run', '--dataset', opts.dataset, '--agent', 'terminus', '--model', 'anthropic/claude-sonnet-4-5',
	'--n-concurrent-trials', String(opts.concurrency), '--output-path', outDir], {
	env: { ...process.env, ANTHROPIC_API_BASE: `http://localhost:${opts.port}`, ANTHROPIC_API_KEY: 'lynkr-calibration' },
	stdio: ['ignore', fs.openSync(path.join(outDir, 'tb-stdout.log'), 'a'), fs.openSync(path.join(outDir, 'tb-stdout.log'), 'a')],
	maxBuffer: 1 << 26,
	});
	// process r.status as before
	} finally {
	lynkr.kill();
	}

[github-actions]

Inconsistent use of null comparison operators. Line 28 uses == null and != null while the codebase otherwise uses strict equality. This is inconsistent with the strict equality requirement in the code standards.

Suggestion:

Suggested change

	scores.forEach((s, i) => { if (s == null) return; (labels[i] ? neg : pos).push(s); });
	scores.forEach((s, i) => { if (s === null) return; (labels[i] ? neg : pos).push(s); });

[github-actions]

Inconsistent use of null comparison operators in logging output.

Suggestion:

Suggested change

	console.log(`${p.padEnd(12)} ${a1 == null ? ' n/a' : a1.toFixed(3).padStart(15)} ${a2 == null ? ' n/a' : a2.toFixed(3).padStart(10)} ${s.filter((x) => x != null).length}/${rows.length}`);
	console.log(`${p.padEnd(12)} ${a1 === null ? ' n/a' : a1.toFixed(3).padStart(15)} ${a2 === null ? ' n/a' : a2.toFixed(3).padStart(10)} ${s.filter((x) => x !== null).length}/${rows.length}`);

[github-actions]

The openRouterBody.provider object is modified in place during the fallback loop without restoring previous values between iterations. This means that when trying the next provider, the loop reuses provider settings from the previous attempt. The provider should be reset before each iteration to ensure correct behavior.