freshcontext-mcp 0.3.19 → 0.3.21

package/docs/HUMAN_READABLE_OUTPUT_CONTRACT.md

@@ -0,0 +1,293 @@
+# Human-Readable Output Contract
+
+Status: implemented MVP contract.
+
+This document describes the reader-facing output layer over FreshContext Core decisions. The MVP is implemented as an additive Core helper and `evaluate_context` structured JSON field. It does not change Core behavior, ranking, decision labels, utility math, Worker behavior, package version, deployment state, or public site copy.
+
+FreshContext is not truth itself. FreshContext records why context was trusted, down-ranked, questioned, refreshed, watched, backgrounded, or excluded before an AI system uses it.
+
+## Purpose
+
+FreshContext Core already returns machine decisions, reasons, warnings, utility, freshness, confidence, Source Profile context, and provenance material. The human-readable output layer should make those results understandable without exposing every internal score first.
+
+The output should answer:
+
+- Can I use this context?
+- Why was this source treated this way?
+- What reached the model?
+- What was kept out?
+- Can another agent inherit this context safely?
+
+## Audiences
+
+- Normal readers need a short status, reason, and warning.
+- Analysts and buyers need an evidence table that shows why each source was treated differently.
+- Developers need a stable JSON shape for future SDK, API, MCP, and CLI formatting.
+- Multi-agent workflows need enough identity and judgment metadata for one agent to hand context to another without losing evidence boundaries.
+
+## Non-Goals
+
+This contract does not:
+
+- certify truth
+- provide professional guidance in legal, clinical, tax, employment, academic, or financial domains
+- change Core scoring or ranking
+- make utility control decision labels
+- wire adapters into Core
+- add `evaluate_source`
+- define a live hosted API response
+- replace Signal Contract v1
+- claim Ha-Pri v2 production enforcement
+
+## Decision Vocabulary
+
+FreshContext should keep the current Core machine decisions as the stable machine layer.
+
+| Machine decision | Reader label | Meaning | Human action | Agent action | Must not claim |
+| --- | --- | --- | --- | --- | --- |
+| `use_first` | Use first | Strong, current context for the task. | Read or place this near the top of the working context. | Prioritize in the context bundle. | This is guaranteed true. |
+| `cite_as_primary` | Primary source | Relevant, current, and traceable enough to use as main evidence. | Use as main evidence while applying normal review. | Use as primary citation evidence. | This source proves the claim by itself. |
+| `cite_as_supporting` | Supporting source | Useful evidence, but not enough to stand alone as the latest or strongest support. | Pair with a clearer, newer, or more authoritative source. | Include as supporting context, not sole evidence. | This is sufficient primary evidence. |
+| `use_as_background` | Background only | Relevant context, but not strong enough for current-evidence claims. | Use for framing, history, or orientation. | Keep lower in the context bundle. | This is current proof. |
+| `needs_verification` | Needs verification | Possibly useful, but timing, confidence, or traceability is uncertain. | Verify before relying on it. | Do not use as trusted primary context. | This source is false. |
+| `needs_refresh` | Needs refresh | Possibly useful, but too stale or date-uncertain for this source type. | Re-query or find a newer source. | Refresh retrieval before use. | This source is useless or false. |
+| `watch_only` | Watch only | Interesting signal, but not strong enough to prioritize. | Monitor or keep as weak signal. | Keep out of primary reasoning unless requested. | This is actionable evidence. |
+| `exclude` | Excluded | Failed, too weak, unsafe, or not useful enough for the final context bundle. | Keep out unless manually reviewed. | Do not pass to the model as useful context. | This is legally or factually invalid. |
+
+## Reader Card
+
+The Reader Card is for normal humans. It should be short and decision-first.
+
+Example:
+
+```txt
+Status: Primary source
+
+Why:
+Recent, directly relevant, and traceable enough for main evidence.
+
+Watch-outs:
+FreshContext does not certify truth.
+
+What FreshContext did:
+Ranked this source above weaker, stale, or unclear candidates before model use.
+```
+
+Recommended fields:
+
+- `status`
+- `why`
+- `watch_outs`
+- `what_freshcontext_did`
+
+The Reader Card should not lead with raw scores unless a technical user asks for them.
+
+The current MVP is the `readable` object returned inside each structured `evaluate_context` result:
+
+```json
+{
+  "decision": "cite_as_primary",
+  "label": "Cite as primary",
+  "readable": {
+    "label": "Primary source",
+    "summary": "This source is strong enough to use as main evidence.",
+    "why": [
+      "Strong semantic match and current freshness for arxiv.",
+      "source profile academic_research uses lenient date policy",
+      "intent profile citation_check selected"
+    ],
+    "action": "Use this as main evidence while preserving citation and provenance.",
+    "warnings": [
+      "FreshContext judges citation readiness and context usefulness; it does not certify truth."
+    ]
+  }
+}
+```
+
+`readable.why` is capped at five reasons to keep output readable and deterministic.
+
+The readable object translates Core decisions into user-facing language. It does not change ranking, decision labels, utility scoring, or source intake.
+
+## Analyst Evidence Table
+
+The Analyst Evidence Table is for buyers, reviewers, and smart non-technical readers who need to compare multiple sources.
+
+Recommended columns:
+
+| Column | Plain meaning |
+| --- | --- |
+| Decision | How FreshContext says this context should be treated. |
+| Source | Where the context came from. |
+| Usefulness | How helpful the context is for this question. |
+| Freshness | Whether the timing is current enough for this use. |
+| Confidence | How reliable the context signal appears. |
+| Provenance | Whether source identity and audit metadata are preserved. |
+| Reason | Short explanation of the treatment label. |
+| Warning | Non-advice or verification warning, if any. |
+
+Example row:
+
+```txt
+Primary source | arxiv.org/... | High | Current | High | Clear | Recent, direct academic source | Does not certify truth
+```
+
+## Developer JSON Contract
+
+This is a proposed future response shape for SDK, API, MCP, and CLI formatting. It is not a live API contract yet.
+
+```json
+{
+  "context_id": "ctx_...",
+  "decision": "cite_as_primary",
+  "reader_label": "Primary source",
+  "summary": "Recent, directly relevant source with clear provenance.",
+  "source": {
+    "id": "src_...",
+    "url": "https://example.com/source",
+    "type": "academic_research",
+    "title": "Example source"
+  },
+  "scores": {
+    "rank": 0.92,
+    "freshness": 87,
+    "utility": 81,
+    "confidence": "high"
+  },
+  "provenance": {
+    "published_at": "2026-06-01T00:00:00.000Z",
+    "retrieved_at": "2026-06-09T00:00:00.000Z",
+    "hash": "sha256:..."
+  },
+  "reasons": [
+    "Strong semantic match and current freshness for arxiv."
+  ],
+  "warnings": [
+    "FreshContext judges citation readiness and context usefulness; it does not certify truth."
+  ],
+  "handoff": {
+    "safe_for_agent_handoff": true,
+    "handoff_notes": []
+  }
+}
+```
+
+The JSON layer should preserve the current Core decision label while adding a reader label and summary. It should not rename the machine decision.
+
+## Multi-Agent Handoff Contract
+
+A multi-agent handoff should let Agent B understand what Agent A used, rejected, or questioned without re-reading the whole original prompt.
+
+Required fields to consider:
+
+- `context_id`
+- `source_id`
+- `decision`
+- `reader_label`
+- `source_profile`
+- `intent_profile`
+- `freshness_state`
+- `confidence_state`
+- `utility_state`
+- `provenance_hash`
+- `published_at`
+- `retrieved_at`
+- `judged_at`
+- `judged_by`
+- `handoff_safe`
+- `handoff_reason`
+- `reasons`
+- `warnings`
+- `excluded_context_refs`
+
+Example:
+
+```json
+{
+  "context_id": "ctx_123",
+  "source_id": "src_456",
+  "decision": "needs_verification",
+  "reader_label": "Needs verification",
+  "source_profile": "company_intel",
+  "intent_profile": "business_due_diligence",
+  "freshness_state": "unknown",
+  "confidence_state": "medium",
+  "utility_state": "partly useful",
+  "provenance_hash": "sha256:...",
+  "published_at": null,
+  "retrieved_at": "2026-06-09T00:00:00.000Z",
+  "judged_at": "2026-06-09T00:00:00.000Z",
+  "judged_by": "freshcontext-core",
+  "handoff_safe": false,
+  "handoff_reason": "Useful but missing source date; verify before primary use.",
+  "reasons": [
+    "published_at/content_date was invalid; cleared"
+  ],
+  "warnings": [
+    "FreshContext supports context triage only; it is not professional legal, tax, or financial guidance."
+  ],
+  "excluded_context_refs": []
+}
+```
+
+## Utility Language
+
+Utility means usefulness for the current question. It does not mean truth.
+
+Allowed wording:
+
+- High utility: useful for this question
+- Medium utility: partly useful
+- Low utility: weak fit for this question
+
+Forbidden wording:
+
+- true
+- verified truth
+- claims that accuracy is guaranteed
+- claims that a source has official approval
+- claims that FreshContext has settled the answer
+
+Utility can appear in explanations and reasons, but it must not be described as controlling default decision labels unless a future policy pass explicitly changes that behavior.
+
+## Provenance Language
+
+Provenance means traceable source identity and audit material. It does not mean magical truth.
+
+Allowed wording:
+
+- clear provenance
+- unclear provenance
+- source identity preserved
+- retrieval time recorded
+- source timestamp recorded
+- deterministic audit hash
+
+Forbidden wording:
+
+- absolute tamper resistance
+- truth certification claims
+- legal verification claims
+- outside audit claims
+- origin-authenticated unless a future signing model provides that guarantee
+
+## Forbidden Claims
+
+FreshContext output must not claim:
+
+- it determines truth
+- it proves correctness
+- it replaces human review
+- it is a legal, medical, tax, employment, academic, or investment advisor
+- it validates facts beyond the provided context metadata
+- it guarantees source authenticity
+- it has production Ha-Pri v2 enforcement unless that enforcement is actually implemented
+
+## Future Implementation Passes
+
+Suggested next passes:
+
+- Pass 14-D: review whether the Analyst Evidence Table should become a helper or stay documentation-only.
+- Pass 14-E: decide whether to add human-readable text lines to `evaluate_context`, or keep the readable layer JSON-only.
+- Later: design Diagnostic Mode on top of `why`, `warnings`, and replay mismatch evidence.
+
+The MVP is intentionally small: it translates existing judgment into readable output without changing the judgment itself.

package/docs/RELEASE_INTEGRITY.md

@@ -22,7 +22,7 @@ This document describes release hardening practices for future FreshContext pack
   - Confirm fresh consumer `npm audit --omit=dev` is clean.
 - Run a stale-claim scan across public docs and package-facing files.
 - Run a secret scan before sharing archives, diligence folders, or package artifacts.
-- Keep operational demo runbooks, buyer scripts, outreach plans, diligence checklists, and negotiation materials outside the public npm package.
+- Keep operational demo runbooks, buyer scripts, outreach plans, diligence checklists, and private commercial materials outside the public npm package.
 
 ## Package Exclusion Checks
 

package/docs/RELEASE_NOTES.md

@@ -1,8 +1,36 @@
-# FreshContext Release Notes
-
-## 0.3.19
-
-FreshContext 0.3.19 syncs the public MCP package with the new generic `evaluate_context` interface.
+# FreshContext Release Notes
+
+## 0.3.21
+
+FreshContext 0.3.21 adds provenance readiness and readable handoff safety for judged context.
+
+### Provenance Readiness
+
+- Adds a Core `provenance_readiness` sidecar that classifies caller-provided context as `complete`, `partial`, `incomplete`, `unknown`, or `derived`.
+- Keeps provenance readiness additive: it does not fetch sources, verify truth, change ranking, change utility scoring, or change decision-label policy.
+- Preserves stable structured `evaluate_context` output while adding provenance readiness to each result.
+
+### Public Contract and Boundary Gates
+
+- Adds compatibility coverage for pre-provenance `evaluate_context` payloads.
+- Locks Core public imports, package fixture behavior, and the `freshcontext-mcp/core` subpath surface.
+- Audits the adapter boundary so Core remains the judgment layer, while the 21 reference tools remain optional source-intake adapters.
+
+### Readable Handoff Safety
+
+- Adds `readable.handoff.safe_for_agent_handoff` and `readable.handoff.reason` to structured readable output.
+- Derives handoff safety only from the existing decision and `provenance_readiness`.
+- Does not add multi-agent orchestration, batch handoff counts, new MCP tools, or adapter orchestration.
+
+### Release Gate
+
+- Adds stress coverage for ugly provenance, scoring, decision, readable output, and handoff edge cases.
+- Pins the policy that minimal title-only legacy input is valid but needs verification.
+- Confirms MCP smoke remains at 22 tools and package/server metadata align at 0.3.21 for this release prep.
+
+## 0.3.19
+
+FreshContext 0.3.19 syncs the public MCP package with the new generic `evaluate_context` interface.
 
 ### Context Evaluation Front Door
 

package/docs/SIGNAL_CONTRACT.md

@@ -1,9 +1,33 @@
 # FreshContext Signal Contract v1
 
-FreshContext Signal Contract v1 defines the Core shape for a retrieved signal before it is ranked, wrapped, stored, or passed to an agent workflow.
+FreshContext Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context that should be judged before it reaches a model.
+
+In plain terms:
+
+```text
+candidate context -> Signal Contract v1 -> FreshContext judgment -> decision-ready context
+```
+
+The Signal Contract is live product architecture. It is used by Core normalization, `evaluate_context`, bring-your-own-context demos, reference adapter signal paths, and future batch validation.
+
+Do not rename this with future-signal terminology. Future context signals, control signals, provenance confidence signals, and richer decision metadata are optional future layers on top of this stable input shape. They are not replacements for Signal Contract v1 and are not required fields today.
 
 It is an additive Core API. It does not change MCP tool schemas, Worker runtime behavior, D1 schema, Store scoring, feeds, or deployment behavior.
 
+Provenance readiness is an output-side judgment over this signal material. It can warn about weak source identity or missing timing metadata without adding new required input fields.
+
+## Batch Validation Harness
+
+Source checkouts include a small validation harness for testing larger Signal Contract v1 batches:
+
+```bash
+npm run batch:validate -- examples/batches/signal-contract-v1.academic.json
+```
+
+The harness reads caller-provided JSON, evaluates it through Core, summarizes status/date/decision counts, and prints a structured evidence block. It does not add required fields to the Signal Contract and does not fetch, crawl, scan folders, or call reference adapters.
+
+Replay output includes concise decision explanations and small reason-code lists for top results and human-review mismatches. These are reporting aids for auditability: they surface whether relevance, freshness, date confidence, status, utility, score normalization, or Source Profile behavior influenced a treatment label. They do not change Core scoring, ranking, normalization, or decision thresholds, and they do not certify truth.
+
 ## Contract Version
 
 ```ts
@@ -18,7 +42,7 @@ contract_version: "freshcontext.signal.v1"
 
 ## Input Shape
 
-`FreshContextSignalInput` accepts the common fields used by adapters, agents, ranking, and future Store wiring:
+`FreshContextSignalInput` accepts the common fields used by adapters, agents, ranking, `evaluate_context`, and future Store wiring:
 
 ```ts
 interface FreshContextSignalInput {
@@ -40,6 +64,20 @@ interface FreshContextSignalInput {
 
 `published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias.
 
+Minimal caller-provided input usually looks like:
+
+```json
+{
+  "title": "Example source",
+  "content": "Candidate context text...",
+  "source": "https://example.com/source",
+  "source_type": "official_docs",
+  "published_at": "2026-06-01T00:00:00.000Z",
+  "retrieved_at": "2026-06-09T00:00:00.000Z",
+  "semantic_score": 0.92
+}
+```
+
 ## Normalized Output
 
 `normalizeSignal(input, options?)` returns a `FreshContextSignal`:
@@ -73,6 +111,156 @@ interface FreshContextSignal {
 - `metadata` is shallow-copied so normalization does not mutate caller-owned objects.
 - `reasons` records meaningful normalization changes.
 
+## Examples
+
+These examples are intentionally small. They show the current contract shape, not future optional metadata.
+
+### Valid Candidate Signals
+
+Academic research:
+
+```json
+{
+  "title": "A fresh retrieval-augmented generation benchmark",
+  "content": "The paper reports a 2026 benchmark for retrieval-augmented generation systems.",
+  "source": "https://arxiv.org/abs/2606.00001",
+  "source_type": "arxiv",
+  "published_at": "2026-06-01T09:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.94,
+  "metadata": {
+    "profile": "academic_research"
+  }
+}
+```
+
+Official docs:
+
+```json
+{
+  "title": "API changelog",
+  "content": "The official changelog documents the current API behavior.",
+  "source": "https://docs.example.com/changelog",
+  "source_type": "official_docs",
+  "published_at": "2026-06-08T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.88
+}
+```
+
+Jobs/opportunities:
+
+```json
+{
+  "title": "AI tools engineer",
+  "content": "A current remote role for an AI tools engineer.",
+  "source": "https://jobs.example.com/ai-tools-engineer",
+  "source_type": "jobs",
+  "published_at": "2026-06-07T08:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.86
+}
+```
+
+Market/finance:
+
+```json
+{
+  "title": "Company quarterly update",
+  "content": "The company reported current quarter revenue and guidance.",
+  "source": "https://investors.example.com/q2-update",
+  "source_type": "finance",
+  "published_at": "2026-06-09T07:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.83
+}
+```
+
+Social pulse:
+
+```json
+{
+  "title": "Developer discussion",
+  "content": "Developers are discussing setup friction and recent adoption.",
+  "source": "https://news.ycombinator.com/item?id=123456",
+  "source_type": "hackernews",
+  "published_at": "2026-06-09T11:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.71
+}
+```
+
+### Invalid Or Risky Candidate Signals
+
+Missing date:
+
+```json
+{
+  "title": "Relevant source with no date",
+  "content": "Useful candidate context, but no publication timestamp is available.",
+  "source": "https://example.com/no-date",
+  "source_type": "official_docs",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Invalid timestamp:
+
+```json
+{
+  "title": "Invalid date source",
+  "content": "Candidate context with malformed date metadata.",
+  "source": "https://example.com/bad-date",
+  "source_type": "official_docs",
+  "published_at": "not-a-date",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Meaningfully future-dated timestamp:
+
+```json
+{
+  "title": "Future-dated source",
+  "content": "Candidate context whose publication timestamp is after retrieval time.",
+  "source": "https://example.com/future-date",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T12:06:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Failed/error-looking content:
+
+```json
+{
+  "title": "Blocked source",
+  "content": "[Error] upstream timeout",
+  "source": "https://example.com/blocked",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.91
+}
+```
+
+Out-of-range semantic score:
+
+```json
+{
+  "title": "Overscored source",
+  "content": "Candidate context with an out-of-range relevance score.",
+  "source": "https://example.com/overscored",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 1.7
+}
+```
+
 ## Relationship to Existing Core Types
 
 The signal contract does not replace existing Core types:
@@ -87,3 +275,13 @@ The contract gives these surfaces a shared signal vocabulary without requiring S
 ## Boundary
 
 Signal Contract v1 does not determine truth, certify data, or provide legal, medical, tax, or financial advice. It provides normalized context metadata for freshness, provenance, relevance, and workflow review.
+
+## Future Metadata Boundary
+
+Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals may later improve decisions such as `cite_as_primary`, `needs_refresh`, `needs_verification`, or `exclude`.
+
+Those are roadmap metadata layers. They should remain optional until tests prove they improve decisions. The public input contract should stay boring and stable:
+
+```text
+title + content + source + source_type + published_at + retrieved_at + semantic_score
+```

package/package-script-guard.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { join } from "node:path";
 
 const SOURCE_CHECKOUT_MESSAGE = [
   "This npm script is for the FreshContext source checkout.",
@@ -45,6 +46,17 @@ const commands = {
     args: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
     passThroughArgs: true,
   },
+  "batch:validate": {
+    required: ["examples/validate-signal-batch.ts"],
+    command: "tsx",
+    args: ["examples/validate-signal-batch.ts"],
+    passThroughArgs: true,
+  },
+  "core:fixture": {
+    required: ["scripts/pack-core-fixture.mjs", "dist/core/index.js"],
+    command: "node",
+    args: ["scripts/pack-core-fixture.mjs"],
+  },
   "smoke:stdio": {
     required: ["scripts/smoke-stdio.mjs"],
     command: "node",
@@ -93,12 +105,22 @@ const commands = {
       "tests/arxivSignals.test.ts",
       "tests/arxivDecisionIntegration.test.ts",
       "tests/core.test.ts",
+      "tests/haPriV2GoldenVectors.test.ts",
+      "tests/signalContractExamples.test.ts",
+      "tests/batchValidationHarness.test.ts",
       "tests/rank.test.ts",
       "tests/workerEnvelope.test.ts",
+      "tests/packageScriptGuard.test.mjs",
+      "tests/corePackageFixture.test.mjs",
+      "tests/readableOutput.test.ts",
+      "tests/provenanceReadiness.test.ts",
+      "tests/adapterNetworkBoundary.test.ts",
+      "tests/workerRouteSecurity.test.ts",
       "tests/workerCoreEnvelopeParity.test.ts",
       "tests/coreEnvelopeOptions.test.ts",
       "tests/mathSpine.test.ts",
       "tests/coreApiContract.test.ts",
+      "tests/coreSubpathExport.test.mjs",
       "tests/corePipeline.test.ts",
       "tests/decision.test.ts",
       "tests/evaluateContextTool.test.ts",
@@ -124,13 +146,47 @@ if (!hasSourceCheckoutFiles) {
   process.exit(0);
 }
 
+function resolveCommand(command, args) {
+  if (command === "node") return { command: process.execPath, args };
+
+  const localNodeEntrypoints = {
+    tsx: join("node_modules", "tsx", "dist", "cli.mjs"),
+    tsc: join("node_modules", "typescript", "bin", "tsc"),
+  };
+  const nodeEntrypoint = localNodeEntrypoints[command];
+  if (nodeEntrypoint && existsSync(nodeEntrypoint)) {
+    return { command: process.execPath, args: [nodeEntrypoint, ...args] };
+  }
+
+  const localBin = process.platform === "win32"
+    ? join("node_modules", ".bin", `${command}.cmd`)
+    : join("node_modules", ".bin", command);
+
+  if (existsSync(localBin)) return { command: localBin, args };
+  if (process.platform === "win32" && !command.endsWith(".cmd")) {
+    return { command: `${command}.cmd`, args };
+  }
+  return { command, args };
+}
+
+function validatePassThroughArgs(args) {
+  for (const arg of args) {
+    if (arg.includes("\0")) {
+      console.error("FreshContext package script arguments cannot contain null bytes.");
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
 const args = [
   ...config.args,
-  ...(config.passThroughArgs ? process.argv.slice(3) : []),
+  ...(config.passThroughArgs ? validatePassThroughArgs(process.argv.slice(3)) : []),
 ];
-const child = spawnSync(config.command, args, {
+const invocation = resolveCommand(config.command, args);
+const child = spawnSync(invocation.command, invocation.args, {
   stdio: "inherit",
-  shell: process.platform === "win32",
+  shell: false,
 });
 
 if (child.error) {