Warn when compiled output is stale

[williamthorsen]

Problem

When developing the MCP server locally, it's easy to modify source files in packages/mcp/src/ and forget to rebuild before starting a new Claude Code session. The server runs from packages/mcp/dist/esm/cli.js, so stale compiled output means tool behavior doesn't match the source — and nothing alerts the user.

This caused a real issue in #157 where init_run returned a run ID format ({projectSlug}.{timestamp}) that didn't match the current source code's format ({timestamp} only), because the running server was built from an older version.

Proposed solution

Add a staleness check that warns once per session when the compiled output is older than the source files.

Detection logic

Compare the most recent mtime across src/**/*.ts against the mtime of dist/esm/cli.js. If any source file is newer than the compiled output, the build is stale.

Dev vs production: Resolve src/ relative to the server's own file location (../../src/ from dist/esm/). If src/ doesn't exist (published package), skip silently — the feature activates only in local development.

Warning delivery

Prepend a warning to the first tool call response in each session. Module-level let hasWarned = false persists for the session's lifetime (stdio process = one session).

⚠️ MCP server build is stale — source files are newer than compiled output. Run `pnpm run ws compile` in packages/mcp/ to rebuild.

Implementation approach

• packages/mcp/src/staleness.ts (new) — isBuildStale(compiledFileUrl?) with recursive mtime comparison. Optional parameter enables testing without mocking import.meta.url.
• packages/mcp/src/server.ts (modify) — wrapHandler() factory applied to all 5 tool registrations. prependWarning() helper mutates the first text content entry.

Key design decisions

1. Module-level boolean, not protocol-level session tracking — stdio transport means one process = one session.
2. Warning in tool response, not MCP logging — tool responses are guaranteed visible in Claude's context.
3. Silent in production — the src/ directory check means the feature is a no-op from a published package.
4. Fail-safe — any staleness detection error returns false, never blocks tool execution.

Acceptance criteria

• When source files are newer than compiled output, the first tool call in a session includes a staleness warning
• Subsequent tool calls in the same session do not repeat the warning
• When compiled output is up to date, no warning appears
• When running from a published package (no src/ directory), no warning appears
• Staleness detection errors are silently swallowed — never block tool execution
• Unit tests cover: stale detection, fresh detection, missing src directory, detection error handling

[williamthorsen]

Implementation plan

Files to create

packages/mcp/src/staleness.ts

Export a single async function:

export async function isBuildStale(compiledFileUrl?: string): Promise<boolean>

Logic:

1. Resolve compiledFileUrl ?? import.meta.url to a filesystem path via fileURLToPath()
2. Navigate from dist/esm/ up to the package root: resolve(dirname(compiledFilePath), '../../src')
3. If src/ doesn't exist → return false (published package, not dev)
4. stat() the sentinel file dist/esm/cli.js to get the reference mtime
5. Recursively walk src/ looking for any .ts file with mtimeMs > referenceMs
6. Outer try/catch: any error → return false (fail-safe)

The optional compiledFileUrl parameter makes this testable without mocking import.meta.url — tests pass in a URL pointing to a controlled temp directory.

Internal helper (not exported):

async function hasNewerFile(dir: string, referenceMs: number): Promise<boolean>

Recursively walks with readdir(dir, { withFileTypes: true }), checks .ts files' mtimeMs, short-circuits on first match.

packages/mcp/src/__tests__/staleness.test.ts

Tests for isBuildStale() (real filesystem, temp directories):

Test case	Setup	Expected
Stale: source newer than dist	srcMtime = now, distMtime = now - 10s	true
Fresh: dist newer than source	srcMtime = now - 10s, distMtime = now	false
Missing src/ (published pkg)	Only dist/esm/cli.js, no src/ directory	false
Missing cli.js (error path)	src/*.ts exists but no cli.js	false
Nested source files	src/tools/deep.ts newer than cli.js	true
Non-.ts files ignored	src/readme.md newer, all .ts files older	false

Test helper: createFakePackage({ srcMtime, distMtime }) creates a temp directory mirroring the package layout (src/*.ts, dist/esm/cli.js, dist/esm/staleness.js) with controlled mtimes via utimes(). Returns a file:// URL for the fake staleness.js.

Tests for warning delivery (protocol-level, mocked isBuildStale):

Use vi.mock('../staleness.js') to control isBuildStale() and vi.resetModules() + dynamic import('../server.js') to get fresh hasWarned state between tests.

Test case	Setup	Expected
Warning prepended when stale	Mock isBuildStale → true, call tool	Response text starts with ⚠️ warning
Warning appears only once	Mock isBuildStale → true, call 2 tools	First response has warning, second doesn't
No warning when fresh	Mock isBuildStale → false, call tool	No warning in response

Uses InMemoryTransport.createLinkedPair() + Client pattern from protocol.test.ts.

Files to modify

packages/mcp/src/server.ts

Add imports:

import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import { isBuildStale } from './staleness.js';

Add module-level state and helpers (before createServer()):

let hasWarned = false;

const STALE_BUILD_WARNING =
  '⚠️ MCP server build is stale — source files are newer than compiled output. Run `pnpm run ws compile` in packages/mcp/ to rebuild.\n\n';

Add wrapHandler() function — wraps a tool callback to prepend a one-time staleness warning:

function wrapHandler<F extends (...args: never[]) => CallToolResult | Promise<CallToolResult>>(handler: F): F {
  const wrapped = async (...args: unknown[]): Promise<CallToolResult> => {
    const result: CallToolResult = await handler(...(args as Parameters<F>));
    if (!hasWarned && (await isBuildStale())) {
      hasWarned = true;
      prependWarning(result);
    }
    return result;
  };
  return wrapped as F;
}

Add prependWarning() helper — mutates the result to prepend warning text to the first text content entry. Uses runtime narrowing because CallToolResult.content is a complex SDK union type (matches existing pattern in helpers.ts).

Wrap all 5 tool handler callbacks:

// Before:
server.registerTool('init_run', { ... }, async (args) => { ... });

// After:
server.registerTool('init_run', { ... }, wrapHandler(async (args) => { ... }));

Apply to: init_run, emit_event, register_artifact, complete_run, get_run_state.

Verification

1. pnpm run ws typecheck in packages/mcp/ — strict TypeScript passes
2. pnpm run ws lint in packages/mcp/ — no lint violations
3. pnpm run ws test in packages/mcp/ — all tests pass (existing + new)
4. Manual: touch a source file in packages/mcp/src/, start a Claude Code session, call any MCP tool → see the staleness warning in the first response only

[williamthorsen]

Insight from orchestrated run 20260304-065040Z:

The MCP phase_completed event validator only accepts completed|skipped|failed|in_progress|approved as valid status values. needs_manual_review — which is a valid run status — is rejected at the event level. During this run, it had to be encoded in the data field instead.

Consider extending the phase_completed event validator to include needs_manual_review as a valid status, since it's a natural outcome for review phases.