mobile-debug-mcp 0.33.0 → 0.35.0

package/test/unit/observe/system-trace-android.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import { AndroidTraceNative } from '../../../src/observe/system-trace-android.js'
+import type { execCmd } from '../../../src/utils/exec.js'
+
+async function run() {
+  const calls: Array<{ args: string[]; timeout: number | undefined }> = []
+  let failure = '', processes = ''
+  const execute: typeof execCmd = async (_cmd, args, options = {}) => {
+    calls.push({ args, timeout: options.timeout })
+    assert.equal(args[0], '-s'); assert.equal(args[1], 'serial with spaces')
+    if (failure && args.join(' ').includes(failure)) return { exitCode: null, stdout: '', stderr: 'ACTION_TIMEOUT' }
+    let out = ''
+    if (args.includes('--help')) return { exitCode: 1, stdout: '', stderr: 'Usage: perfetto --background-wait --config' }
+    if (args.includes('getprop')) out = '36'
+    if (args.includes('--list_categories')) out = ' sched - Scheduling\n input - Input\n gfx - Graphics'
+    if (args.join(' ').includes('YQ==')) out = 'a'
+    if (args.join(' ').includes('for pid')) out = processes
+    if (args.includes('stat')) out = '1024'
+    return { exitCode: 0, stdout: out, stderr: '' }
+  }
+  const native = new AndroidTraceNative(execute)
+  const remote = '/data/misc/perfetto-traces/mcp-62a51510-c303-4a1b-af0e-f97cc976d740.perfetto-trace'
+  assert.equal((await native.capabilities('serial with spaces')).supported, true)
+  for (const probe of ['--help', '--query', 'getprop', '--list_categories', 'test -w', 'YQ==']) {
+    failure = probe
+    assert.equal((await native.capabilities('serial with spaces')).supported, false, probe)
+  }
+  failure = ''
+  await native.start('serial with spaces', remote, 1001, ['sched', 'input'])
+  assert.equal(calls.at(-1)!.timeout, 35000)
+  assert.ok(calls.at(-1)!.args.join(' ').includes('--background-wait -c -'))
+  assert.equal(await native.find('serial with spaces', remote), null)
+  processes = '123 456'
+  assert.deepEqual(await native.find('serial with spaces', remote), { pid: 123, startTime: '456' })
+  assert.ok(calls.at(-1)!.args.join(' ').includes('stat=$(cat "$p/stat" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }'), 'Unreadable process identity must fail closed')
+  processes = '123 456\n999 888'
+  await assert.rejects(() => native.find('serial with spaces', remote), /IDENTITY_UNAVAILABLE/)
+  const previous = calls.length
+  await assert.rejects(() => native.stop('serial with spaces', remote, { pid: 0, startTime: '4' }))
+  await assert.rejects(() => native.start('serial with spaces', '/tmp/other; killall perfetto', 1000, []))
+  assert.equal(calls.length, previous)
+  await native.stop('serial with spaces', remote, { pid: 123, startTime: '456' })
+  const signal = calls.at(-1)!.args.join(' ')
+  assert.ok(signal.indexOf('awk') < signal.indexOf('kill -TERM'))
+  assert.ok(signal.indexOf('grep -Fx') < signal.indexOf('kill -TERM'))
+  assert.ok(!signal.includes('killall'))
+  failure = 'pull'
+  await assert.rejects(() => native.pull('serial with spaces', remote, '/tmp/fixture'), /ACTION_TIMEOUT/)
+  assert.equal(calls.at(-1)!.timeout, 30000)
+  console.log('Android Perfetto adapter probes, targeting, guards and deadlines: PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/system-trace.test.ts

@@ -0,0 +1,166 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { SystemTraceSessions, type TraceClock } from '../../../src/observe/system-trace.js'
+import { TRACE_MAX_BYTES, traceConfig, type TraceNative, type TraceCapabilities, type TraceProcess } from '../../../src/observe/system-trace-android.js'
+
+function fixture() {
+  let now = 1000000
+  let failStart = '', failStop = '', failPull = '', failRemove = '', failFind = ''
+  let supported = true, empty = false, oversized = false, stuck = false
+  let starts = 0, stops = 0, pulls = 0, removes = 0
+  const processes = new Map<string, TraceProcess>()
+  const pending = new Map<any, () => void>()
+  const time: TraceClock = { wall: () => now, mono: () => now, sleep: async ms => { now += ms },
+    schedule(fn) { const id = {} as any; pending.set(id, fn); return id }, clear: id => { pending.delete(id) } }
+  const native: TraceNative = {
+    async capabilities(device) { return { supported, backend: 'perfetto', device: { platform: 'android', id: device }, prerequisites: {}, reasons: [], enabled_sources: ['sched', 'input'], unavailable_categories: [], limitations: [] } as TraceCapabilities },
+    async start(_d, remote) { starts++; processes.set(remote, { pid: starts + 100, startTime: String(starts) }); if (failStart) throw new Error(failStart) },
+    async find(_d, remote) { if (failFind) throw new Error(failFind); return processes.get(remote) ?? null },
+    async stop(_d, remote) { stops++; if (failStop) throw new Error(failStop); if (!stuck) processes.delete(remote) },
+    async pull(_d, _r, local) { pulls++; await fs.writeFile(local, empty ? '' : 'perfetto-fixture'); if (oversized) await fs.truncate(local, TRACE_MAX_BYTES + 1); if (failPull) throw new Error(failPull) },
+    async remove() { removes++; if (failRemove) throw new Error(failRemove) }
+  }
+  const sessions = new SystemTraceSessions(native, time)
+  const files: string[] = []
+  return { sessions, native, time, processes, pending, files,
+    tick(ms: number) { now += ms }, get counts() { return { starts, stops, pulls, removes } },
+    flags(v: { start?: string; stop?: string; pull?: string; remove?: string; find?: string; supported?: boolean; empty?: boolean; oversized?: boolean; stuck?: boolean }) {
+      failStart = v.start ?? ''; failStop = v.stop ?? ''; failPull = v.pull ?? ''; failRemove = v.remove ?? ''; failFind = v.find ?? ''
+      supported = v.supported ?? true; empty = v.empty ?? false; oversized = v.oversized ?? false; stuck = v.stuck ?? false
+    },
+    async cleanup() { await sessions.shutdown(); await Promise.all(files.map(file => fs.rm(path.dirname(file), { recursive: true, force: true }))) }
+  }
+}
+async function run() {
+  const f = fixture()
+  try {
+    const a = await f.sessions.start('a', 1001)
+    assert.equal(a.state, 'recording')
+    assert.equal(a.capture_completed_at_ms, null)
+    await assert.rejects(() => f.sessions.start('a'), /TRACE_BUSY/)
+    const b = await f.sessions.start('b')
+    const end = await f.sessions.link(a.trace_id, { platform: 'android', id: 'a' }, 'journey-a')
+    await assert.rejects(() => f.sessions.link(a.trace_id, { platform: 'android', id: 'b' }, 'wrong'), /TRACE_NOT_FOUND/)
+    await assert.rejects(() => f.sessions.link(a.trace_id, { platform: 'ios', id: 'a' }, 'wrong'), /TRACE_NOT_FOUND/)
+    const [stop, again] = await Promise.all([f.sessions.control(a.trace_id, 'stop'), f.sessions.control(a.trace_id, 'stop')])
+    assert.equal(stop.state, 'completed'); assert.deepEqual(stop, again)
+    f.files.push(stop.artifact!.path)
+    assert.equal((await end()).coverage, 'partial') // another call stopped capture during the linked journey
+    assert.deepEqual(stop.correlation_ids, ['journey-a'])
+    assert.equal((await fs.stat(stop.artifact!.path)).mode & 0o777, 0o600)
+    assert.equal((await f.sessions.control(a.trace_id, 'cancel')).artifact?.path, stop.artifact?.path)
+    assert.equal(f.counts.pulls, 1)
+    assert.equal((await f.sessions.control(b.trace_id, 'cancel')).state, 'cancelled')
+    assert.equal(f.counts.pulls, 1)
+    const expired = await f.sessions.start('c', 1000)
+    f.tick(1001)
+    const duration = await f.sessions.control(expired.trace_id, 'status')
+    assert.equal(duration.completion_reason, 'duration_limit'); f.files.push(duration.artifact!.path)
+    f.tick(600001)
+    await assert.rejects(() => f.sessions.control(a.trace_id, 'status'), /TRACE_NOT_FOUND/)
+    await assert.rejects(() => f.sessions.control('previous-server', 'stop'), /TRACE_NOT_FOUND/)
+  } finally { await f.cleanup() }
+
+  for (const failure of ['start', 'stop', 'pull', 'remove', 'find', 'empty', 'oversized'] as const) {
+    const f = fixture()
+    try {
+      if (failure === 'start') f.flags({ start: 'ACTION_TIMEOUT' })
+      const a = await f.sessions.start('a')
+      if (failure === 'start') {
+        assert.equal(a.reason, 'ACTION_TIMEOUT'); assert.equal(a.state, 'failed'); assert.equal(a.cleanup.status, 'complete')
+        assert.equal(f.processes.size, 0); continue
+      }
+      f.flags(failure === 'empty' || failure === 'oversized' ? { [failure]: true } : { [failure]: 'ACTION_TIMEOUT' })
+      const stop = await f.sessions.control(a.trace_id, 'stop')
+      assert.equal(stop.state, 'failed', failure); assert.equal(stop.cleanup.status, 'failed', failure)
+      if (stop.artifact) f.files.push(stop.artifact.path)
+      if (failure === 'pull' || failure === 'empty' || failure === 'oversized') assert.equal(stop.artifact, null)
+      f.flags({})
+      const retry = await f.sessions.control(a.trace_id, 'stop')
+      assert.equal(retry.state, 'completed', failure); assert.equal(retry.cleanup.status, 'complete')
+      if (!f.files.includes(retry.artifact!.path)) f.files.push(retry.artifact!.path)
+    } finally { await f.cleanup() }
+  }
+  const reuse = fixture()
+  try {
+    const a = await reuse.sessions.start('a')
+    const [remote, process] = [...reuse.processes.entries()][0]
+    reuse.processes.set(remote, { ...process, startTime: '999999' })
+    const result = await reuse.sessions.control(a.trace_id, 'stop')
+    assert.equal(result.reason, 'TRACE_STOP_FAILED'); assert.equal(reuse.counts.stops, 0)
+    reuse.processes.delete(remote)
+    assert.equal((await reuse.sessions.control(a.trace_id, 'cancel')).state, 'cancelled')
+  } finally { await reuse.cleanup() }
+  const cap = fixture()
+  try {
+    cap.flags({ supported: false })
+    assert.equal((await cap.sessions.start('a')).reason, 'TRACE_UNSUPPORTED'); assert.equal(cap.counts.starts, 0)
+    cap.flags({})
+    await Promise.all(['a', 'b', 'c', 'd'].map(d => cap.sessions.start(d)))
+    await assert.rejects(() => cap.sessions.start('e'), /TRACE_BUSY/)
+    await cap.sessions.shutdown(); assert.equal(cap.processes.size, 0)
+    await assert.rejects(() => cap.sessions.start('e'), /TRACE_BUSY/)
+  } finally { await cap.cleanup() }
+  const timer = fixture()
+  try {
+    const a = await timer.sessions.start('timer', 1000)
+    timer.tick(1000)
+    for (const callback of timer.pending.values()) callback()
+    const ended = await timer.sessions.control(a.trace_id, 'status')
+    assert.equal(ended.state, 'completed'); assert.equal(ended.completion_reason, 'duration_limit')
+    timer.files.push(ended.artifact!.path)
+  } finally { await timer.cleanup() }
+  const stuck = fixture()
+  try {
+    const a = await stuck.sessions.start('stuck')
+    stuck.flags({ stuck: true })
+    const failed = await stuck.sessions.control(a.trace_id, 'stop')
+    assert.equal(failed.reason, 'ACTION_TIMEOUT'); assert.equal(failed.artifact, null)
+    assert.equal(stuck.counts.pulls, 0)
+    stuck.flags({})
+    assert.equal((await stuck.sessions.control(a.trace_id, 'cancel')).cleanup.status, 'complete')
+  } finally { await stuck.cleanup() }
+  const natural = fixture()
+  try {
+    const a = await natural.sessions.start('natural')
+    natural.native.stop = async (_device, remote) => { natural.processes.delete(remote); throw new Error('PROCESS_ALREADY_EXITED') }
+    assert.equal((await natural.sessions.control(a.trace_id, 'cancel')).state, 'cancelled')
+  } finally { await natural.cleanup() }
+  const interrupted = fixture()
+  try {
+    const a = await interrupted.sessions.start('journey')
+    const finish = await interrupted.sessions.link(a.trace_id, { platform: 'android', id: 'journey' }, 'j')
+    interrupted.flags({ find: 'DEVICE_DISCONNECTED' })
+    assert.equal((await finish()).coverage, 'partial')
+    interrupted.flags({})
+  } finally { await interrupted.cleanup() }
+  const racing = fixture()
+  let release!: () => void
+  const gate = new Promise<void>(resolve => { release = resolve })
+  const originalCapabilities = racing.native.capabilities
+  racing.native.capabilities = async device => { await gate; return originalCapabilities(device) }
+  const starting = racing.sessions.start('race')
+  const closing = racing.sessions.shutdown()
+  release()
+  assert.equal((await starting).reason, 'TRACE_BUSY')
+  assert.deepEqual(await closing, [])
+  assert.equal(racing.counts.starts, 0)
+  const retention = fixture()
+  try {
+    const first = await retention.sessions.start('retention')
+    await retention.sessions.control(first.trace_id, 'cancel')
+    for (let n = 0; n < 100; n++) {
+      const next = await retention.sessions.start('retention')
+      await retention.sessions.control(next.trace_id, 'cancel')
+    }
+    await assert.rejects(() => retention.sessions.control(first.trace_id, 'status'), /TRACE_NOT_FOUND/)
+  } finally { await retention.cleanup() }
+  // Wire bytes decode independently to protect actual proto field numbers/limits.
+  const config = traceConfig(1001, ['sched', 'input'])
+  assert.ok(config.includes(Buffer.from('linux.ftrace')))
+  assert.ok(config.includes(Buffer.from([0x18, 0xe9, 0x07]))) // TraceConfig.duration_ms = 3
+  assert.ok(config.includes(Buffer.from([0x50, 0x80, 0x80, 0x80, 0x10]))) // max_file_size_bytes = 10
+  console.log('system trace session lifecycle: PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/quality/architecture.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { architectureGraph } from '../../../scripts/architecture-graph.mjs'
+import { checkArchitecture } from '../../../scripts/check-architecture.mjs'
+
+const root = await mkdtemp(path.join(tmpdir(), 'mcp-architecture-'))
+try {
+  const files: Record<string, string> = {
+    'package.json': JSON.stringify({ type: 'module' }),
+    'tsconfig.json': JSON.stringify({ compilerOptions: {
+      module: 'NodeNext', moduleResolution: 'NodeNext', target: 'ES2022',
+      paths: { '@server/*': ['./src/server/*'] }
+    }, include: ['src/**/*.ts'] }),
+    'src/server/entry.ts': 'export const value = 1',
+    'src/contracts/bad.ts': "export { value } from '@server/entry.js'",
+    'src/interact/entry.ts': "export const load = () => import('../server/entry.js')",
+    'src/interact/adjustment/control-values.ts': "import { spawn } from 'node:child_process'; export const native = spawn",
+    'src/cycle/a.ts': "export { b } from './b.js'; export const a = 1",
+    'src/cycle/b.ts': "export const b = () => import('./a.js')",
+    'src/type-cycle/a.ts': "import type { B } from './b.js'; export interface A { b: B }",
+    'src/type-cycle/b.ts': "import { type A } from './a.js'; export interface B { a: A }",
+    'src/import-equals.ts': "import entry = require('./server/entry.js'); export { entry }",
+    'src/require.ts': "export const load = () => require('./server/entry.js')"
+  }
+  for (const [file, code] of Object.entries(files)) {
+    const target = path.join(root, file)
+    await mkdir(path.dirname(target), { recursive: true })
+    await writeFile(target, code)
+  }
+  const config = path.join(root, 'tsconfig.json')
+  const graph = await architectureGraph(config)
+  const edge = (source: string, target: string) => graph.find(item => item.source === source && item.target === target)
+  assert(edge('src/contracts/bad.ts', 'src/server/entry.ts'), 'Resolve aliased re-exports to .ts sources')
+  assert(edge('src/interact/entry.ts', 'src/server/entry.ts'), 'Resolve literal dynamic .js imports')
+  assert(edge('src/require.ts', 'src/server/entry.ts'), 'Resolve literal require calls')
+  assert(edge('src/interact/adjustment/control-values.ts', 'node:child_process'), 'Include Node builtins')
+  assert.deepEqual(edge('src/type-cycle/b.ts', 'src/type-cycle/a.ts')?.importKinds, ['type'])
+  assert(edge('src/import-equals.ts', 'src/server/entry.ts'), 'Resolve import-equals require syntax')
+  const rejected = spawnSync(process.execPath, ['scripts/check-architecture.mjs', config], { encoding: 'utf8' })
+  assert.equal(rejected.status, 1, rejected.stderr)
+  assert(rejected.stderr.includes('Production runtime dependencies must be cycle-free'))
+  const results = checkArchitecture(graph)
+  assert(results.every(result => result.violations.length > 0), 'Every rule must reject its deliberately broken fixture')
+  const cycles = JSON.stringify(results.at(-1)?.violations)
+  assert(cycles.includes('src/cycle/a.ts'), 'Catch a cycle through a re-export and dynamic import')
+  assert(!cycles.includes('src/type-cycle'), 'Type-only cycles are not runtime cycles')
+  assert(checkArchitecture([]).every(result => result.violations.length > 0), 'An empty graph must fail closed')
+
+  await writeFile(path.join(root, 'src/nonliteral.ts'), 'export const load = (name: string) => import(name)')
+  await assert.rejects(architectureGraph(config), /Nonliteral dependency/)
+  await rm(path.join(root, 'src/nonliteral.ts'))
+  await writeFile(path.join(root, 'src/unresolved.ts'), "import './missing.js'")
+  await assert.rejects(architectureGraph(config), /Unresolved dependency/)
+  console.log('PASS architecture negative controls: NodeNext, aliases, re-exports, dynamic/require imports, pure boundaries, runtime cycles, type-only cycles, empty and unresolved graphs')
+} finally {
+  await rm(root, { recursive: true, force: true })
+}

package/test/unit/quality/code-quality.test.ts

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict'
+import { measure, compare } from '../../../scripts/code-quality.mjs'
+
+const file = 'src/interact/quality-fixture.ts'
+const inspect = (code: string) => measure(file, code)
+const has = (findings: Awaited<ReturnType<typeof inspect>>, rule: string) => findings.some(f => f.rule === rule)
+const baseline = (findings: Awaited<ReturnType<typeof inspect>>) => findings.map(({ line: _line, ...entry }) => ({ ...entry, reason: 'Test legacy exception' }))
+
+async function main() {
+  assert.deepEqual(await inspect('export const twice = (value: number) => value * 2'), [])
+  const hugeClass = await inspect(`export class Huge {\n${Array.from({ length: 301 }, (_, i) => `field${i} = ${i}`).join('\n')}\n}`)
+  assert(has(hugeClass, 'class-lines'))
+  const hugeFunction = await inspect(`export function work() {\n${Array.from({ length: 81 }, (_, i) => `console.log(${i})`).join('\n')}\n}`)
+  assert(has(hugeFunction, 'max-lines-per-function'))
+  assert(has(await inspect(`export const work = () => {\n${'console.log(1)\n'.repeat(81)}}`), 'max-lines-per-function'))
+  const hugeFile = await inspect(Array.from({ length: 501 }, (_, i) => `export const value${i} = ${i}`).join('\n'))
+  assert(has(hugeFile, 'max-lines'))
+  assert(!has(await inspect(`// A comment\n${'\n// comment\n'.repeat(600)}export const x = 1`), 'max-lines'))
+  const complex = await inspect(`export function decide(value: number) { ${'if(value) console.log(value);'.repeat(21)} }`)
+  assert(has(complex, 'complexity'))
+  assert(has(await inspect('export function nested(x: boolean) { if(x){if(x){if(x){if(x){if(x){console.log(x)}}}}} }'), 'max-depth'))
+  assert(has(await inspect("import { value } from '../server/tool-handlers.js'"), 'import-boundary'))
+  assert(has(await inspect("export { value } from '../server/common.js'"), 'import-boundary'))
+  assert(has(await inspect("type Args = import('../server/common.js').ToolCallArgs"), 'import-boundary'))
+  assert(has(await inspect("const transport = require('../server/common.js')"), 'import-boundary'))
+  assert(has(await inspect('/* eslint complexity: \"off\" */\nexport const value = 1'), 'inline-suppression'))
+  assert(!has(await inspect("import type { Value } from '../contracts/value.js'"), 'import-boundary'))
+  assert(has(await inspect('// eslint-disable\nexport const x = 1'), 'inline-suppression'))
+  assert(has(await inspect('// eslint-disable-next-line complexity\nexport function f() {}'), 'inline-suppression'))
+  const any = await inspect('export function legacy(value: any) { return value }')
+  assert(has(any, 'explicit-any'))
+  assert.deepEqual(compare(any, baseline(any)), [])
+  assert(compare(any, []).some(e => e.includes('explicit-any')))
+  const grown = await inspect('export function legacy(value: any): any { return value }')
+  assert(compare(grown, baseline(any)).some(e => e.includes('explicit-any')))
+  const renamed = await inspect('export function replacement(value: any) { return value }')
+  assert(compare(renamed, baseline(any)).length >= 2, 'renames do not inherit debt')
+  const moved = any.map(f => ({ ...f, file: 'src/interact/moved.ts' }))
+  assert(compare(moved, baseline(any)).length >= 2, 'moves do not inherit debt')
+  assert(compare([], baseline(any)).some(e => e.includes('obsolete')))
+  assert(compare(any, baseline(grown)).some(e => e.includes('Lower baseline')))
+  assert(compare(any, [...baseline(any), ...baseline(any)]).some(e => e.includes('Duplicate')))
+  assert(compare(any, [{ ...baseline(any)[0], reason: '' }]).some(e => e.includes('Invalid')))
+  const collision = await inspect('function same(x: number) {return x} function same(x: number) {return x}')
+  assert(has(collision, 'duplicate-symbol'))
+  assert(compare(collision, baseline(collision)).some(e => e.includes('duplicate-symbol')), 'identity collisions cannot be baseline exceptions')
+  const suppressed = await inspect('// eslint-disable max-lines-per-function\n'+`function huge(){\n${'console.log(1)\n'.repeat(81)}}`)
+  assert(has(suppressed, 'max-lines-per-function'), 'inline directives cannot hide metrics')
+  const typeDebt = await inspect('type First = any; type Second = number')
+  const shiftedTypeDebt = await inspect('type First = number; type Second = any')
+  assert(compare(shiftedTypeDebt, baseline(typeDebt)).length >= 2, 'unrelated type declarations cannot offset each other')
+  const java = await measure('src/debugger/java/Fixture.java', 'int field;\n'.repeat(501))
+  assert(has(java, 'max-lines'))
+  assert.deepEqual(await measure('src/debugger/java/Fixture.java', '// comment\n'.repeat(501)), [])
+  assert(!has(await inspect('class Accessor { get value() { return 1 } set value(value: number) { console.log(value) } }'), 'duplicate-symbol'))
+  console.log('PASS structural metrics, debt ratchet, boundaries and suppression protection')
+}
+main().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/quality/interaction_boundaries.test.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { readdir, readFile } from 'node:fs/promises'
+import { measure } from '../../../scripts/code-quality.mjs'
+
+// Refactored interaction services must meet defaults even if someone adds a legacy allowance.
+const legacy = new Set(['android.ts', 'ios.ts', 'conditional-action.ts', 'classify.ts'])
+async function sourceFiles(directory = ''): Promise<string[]> {
+  const entries = await readdir(`src/interact/${directory}`, { withFileTypes: true })
+  const paths: string[] = []
+  for (const entry of entries) {
+    const relative = directory ? `${directory}/${entry.name}` : entry.name
+    if (entry.isDirectory()) paths.push(...await sourceFiles(relative))
+    else if (relative.endsWith('.ts') && !legacy.has(relative)) paths.push(relative)
+  }
+  return paths
+}
+const files = await sourceFiles()
+const baseline = JSON.parse(await readFile('scripts/code-quality-baseline.json', 'utf8')) as Array<{ file: string }>
+for (const file of files) {
+  const path = `src/interact/${file}`
+  assert.deepEqual(await measure(path, await readFile(path, 'utf8')), [], `${path} must meet default structural and typing limits`)
+  assert(!baseline.some(entry => entry.file === path), `${path} cannot inherit legacy exceptions`)
+}
+console.log(`PASS default quality limits and no legacy exceptions across ${files.length} interaction modules`)

package/test/unit/server/conditional_actions.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
 import { ToolsObserve } from '../../../src/observe/index.js'
-import { ToolsNetwork } from '../../../src/network/index.js'
+import { ToolsNetwork } from '../../../src/observe/network/index.js'
 import { deriveSnapshotMetadata, getSnapshotSessionId, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
 import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
 import { runWithBudget } from '../../../src/utils/operation-budget.js'

package/test/unit/server/conditional_schema.test.ts

@@ -1,8 +1,8 @@
 import assert from 'node:assert/strict'
 import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
 import { toolDefinitions } from '../../../src/server/tool-definitions.js'
-import { conditionalTools, validateExpectedState } from '../../../src/server/condition-schema.js'
-import { journeySchema } from '../../../src/server/journey-schema.js'
+import { conditionalTools, validateExpectedState } from '../../../src/server/schemas/condition-schema.js'
+import { journeySchema } from '../../../src/server/schemas/journey-schema.js'
 
 const provider = new AjvJsonSchemaValidator()
 const expectedState = { snapshotSessionId: 'session-fixture', snapshotRevision: 1 }

package/test/unit/server/debugger-response.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { debuggerResponse } from '../../../src/server/handlers/debugger-response.js'
+import { handleDebugger } from '../../../src/server/handlers/debugger-handlers.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/debugger-schema.js'
+import { debuggerSessions } from '../../../src/debugger/sessions.js'
+import { DebuggerError } from '../../../src/debugger/worker.js'
+import { diagnostic } from '../../../src/debugger/diagnostics.js'
+
+const baseline = ['capabilities', 'attach', 'state']
+const payload = {
+  success: false, debug_session_id: 'session', device: { id: 'device' }, target: { pid: 42 }, capabilities: { locals: true },
+  state: 'paused', captured_at_ms: 123, reason: null, stop: { stop_id: 'stop', thread_id: 'thread' },
+  limitations: ['SHALLOW_LOCALS'], cleanup: { status: 'failed', remaining_resources: ['forward:tcp:123'] },
+  error: { code: 'DEBUGGER_CLEANUP_FAILED', retryable: false, diagnostic: diagnostic('cleanup', 'operation_failed') },
+  execution_state: 'unknown', result: { frames: [{ frame_id: 'frame' }], truncated: true, availability: 'unknown' },
+  breakpoints: [], events: [], next_cursor: 4, overflow: true, timed_out: false, future_field: { preserve: true }
+}
+const expected = structuredClone(payload) as Record<string, unknown>
+for (const key of ['device', 'target', 'capabilities']) delete expected[key]
+const before = structuredClone(payload)
+for (const tool of debuggerTools) {
+  const contract = debuggerContracts[tool.name]
+  assert.deepEqual(tool.inputSchema.properties.responseMode, { type: 'string', enum: ['compact', 'debug'], default: 'debug' })
+  const shape = contract.schema.shape
+  assert.equal(shape.responseMode.parse(undefined), 'debug')
+  for (const mode of ['compact', 'debug']) assert.equal(shape.responseMode.parse(mode), mode)
+  assert.equal(shape.responseMode.safeParse('full').success, false)
+  assert.deepEqual(debuggerResponse(contract.command, 'debug', payload), payload)
+  assert.deepEqual(debuggerResponse(contract.command, 'compact', payload), baseline.includes(contract.command) ? payload : expected)
+  const success = { ...payload, success: true, error: undefined, cleanup: { status: 'pending', remaining_resources: ['jdi_worker'] } }
+  assert.deepEqual(debuggerResponse(contract.command, 'compact', success), baseline.includes(contract.command) ? success : { ...expected, success: true, error: undefined, cleanup: success.cleanup })
+  const noSession = { ...payload, debug_session_id: null }
+  assert.deepEqual(debuggerResponse(contract.command, 'compact', noSession), noSession)
+}
+assert.deepEqual(payload, before, 'projection must not mutate nested or shared objects')
+
+// This self-running test has its own process; restore the singleton seam in finally.
+const original = debuggerSessions.command
+try {
+  debuggerSessions.command = async (_id, _command, args) => {
+    assert.ok(!Object.hasOwn(args!, 'responseMode'), 'presentation input must not reach worker')
+    return { ...payload, success: true } as unknown as Awaited<ReturnType<typeof original>>
+  }
+  for (const mode of [undefined, 'debug', 'compact']) {
+    const response = await handleDebugger('get_debugger_locals', { debugSessionId: 'session', stopId: 'stop', frameId: 'frame', ...(mode ? { responseMode: mode } : {}) })
+    assert.equal(response.isError, undefined)
+    assert.deepEqual(JSON.parse(response.content[0].text), { ...(mode === 'compact' ? expected : payload), success: true })
+  }
+  for (const code of ['DEBUGGER_STALE_REFERENCE', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_WORKER_FAILED', 'DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED']) {
+    debuggerSessions.command = async () => { throw new DebuggerError(code, diagnostic('command', 'unknown')) }
+    for (const responseMode of ['compact', 'debug']) {
+      const response = await handleDebugger('resume_debugger', { debugSessionId: 'absent', stopId: 'old', responseMode })
+      const value = JSON.parse(response.content[0].text)
+      assert.equal(response.isError, true)
+      assert.equal(value.error.code, code)
+      assert.equal(Object.hasOwn(value, 'capabilities'), responseMode === 'debug')
+      assert.equal(value.debug_session_id, 'absent')
+    }
+  }
+  const invalid = await handleDebugger('detach_debugger', { debugSessionId: 'session', responseMode: 'full' })
+  assert.equal(JSON.parse(invalid.content[0].text).error.code, 'INVALID_ARGUMENT')
+} finally { debuggerSessions.command = original }
+console.log('PASS debugger response defaults, exact retention, failures, immutable projection and argument isolation')

package/test/unit/server/system-trace.test.ts

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+import { systemTraces } from '../../../src/observe/system-trace.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { AndroidManage } from '../../../src/manage/index.js'
+import { withEvidence, bindSystemTrace, bindEvidenceDevice } from '../../../src/observe/evidence.js'
+
+const parse = (r: any) => JSON.parse(r.content[0].text)
+async function run() {
+  const originalLink = systemTraces.link, originalStart = systemTraces.start, originalControl = systemTraces.control
+  const originalApp = AndroidManage.prototype.startApp
+  const id = '62a51510-c303-4a1b-af0e-f97cc976d740'
+  let dispatched = 0, starts = 0
+  _setDeviceListersForTests({ listAndroidDevices: async () => [{ id: 'trace-device', platform: 'android', osVersion: '16', simulator: true, model: 'fixture' }] })
+  try {
+    for (const name of ['get_system_trace_capabilities', 'start_system_trace', 'get_system_trace_status', 'stop_system_trace', 'cancel_system_trace']) {
+      const tool = toolDefinitions.find(t => t.name === name)
+      assert.ok(tool); assert.equal(tool.inputSchema.additionalProperties, false)
+    }
+    assert.equal(toolDefinitions.find(t => t.name === 'run_journey').inputSchema.properties.systemTraceId.format, 'uuid')
+    for (const args of [ {}, { platform: 'android', extra: true }, { platform: 'android', expectedState: {} }, { platform: 'android', durationMs: 0 }, { platform: 'android', durationMs: 1000.5 }, { platform: 'android', durationMs: 120001 } ]) {
+      const r = await handleToolCall('start_system_trace', args)
+      assert.equal(r.isError, true); assert.equal(parse(r).error.code, 'INVALID_ARGUMENT')
+    }
+    systemTraces.start = async () => { starts++; throw new Error('must not run') }
+    const ios = await handleToolCall('start_system_trace', { platform: 'ios' })
+    assert.equal(parse(ios).error.code, 'UNSUPPORTED_PLATFORM'); assert.equal(starts, 0)
+    assert.equal(parse(await handleToolCall('get_system_trace_capabilities', { platform: 'ios' })).supported, false)
+    for (const name of ['stop_system_trace', 'cancel_system_trace', 'get_system_trace_status']) {
+      assert.equal(parse(await handleToolCall(name, { traceId: id, deviceId: 'wrong' })).error.code, 'INVALID_ARGUMENT')
+      assert.equal(parse(await handleToolCall(name, { traceId: id })).error.code, 'TRACE_NOT_FOUND')
+    }
+    AndroidManage.prototype.startApp = async () => { dispatched++; return { appStarted: true } as any }
+    const journey = { platform: 'android', deviceId: 'trace-device', systemTraceId: id, steps: [{ id: 'start', type: 'start_app', appId: 'com.android.settings', verificationMode: 'none' }] }
+    const rejected = await handleToolCall('run_journey', journey)
+    assert.equal(rejected.isError, true); assert.equal(dispatched, 0)
+    let correlation = ''
+    systemTraces.link = async (trace, device, cid) => {
+      assert.equal(trace, id); assert.equal(device.id, 'trace-device'); correlation = cid
+      return async () => ({ trace_id: trace, coverage: 'covered', clock_alignment: 'unknown' })
+    }
+    const result = parse(await handleToolCall('run_journey', journey))
+    assert.equal(result.success, true, JSON.stringify(result)); assert.equal(dispatched, 1)
+    assert.equal(result.evidence.trace_context.trace_id, id)
+    assert.equal(result.evidence.trace_context.supported, true)
+    assert.equal(result.evidence.correlation_id, correlation)
+    assert.equal(result.steps[0].result.evidence.trace_context.trace_id, id)
+    assert.equal(result.steps[0].result.evidence.correlation_id, correlation)
+    assert.equal(result.system_trace.coverage, 'covered')
+    const plain = parse(await handleToolCall('run_journey', { ...journey, systemTraceId: undefined }))
+    assert.deepEqual(plain.evidence.trace_context, { supported: false, trace_id: null, markers: [] })
+    const [linked, independent] = await Promise.all([
+      withEvidence({ journey: true }, async () => { bindSystemTrace(id); bindEvidenceDevice({ platform: 'android', id: 'trace-device' }); return withEvidence({ action: true }, async () => {}) }),
+      withEvidence({ journey: true }, async () => {})
+    ])
+    assert.equal(linked.result.evidence.trace_context.trace_id, id)
+    assert.equal(independent.evidence.trace_context.trace_id, null)
+    console.log('system trace tool contracts and journey evidence: PASS')
+  } finally {
+    systemTraces.link = originalLink; systemTraces.start = originalStart; systemTraces.control = originalControl
+    AndroidManage.prototype.startApp = originalApp; _resetDeviceListersForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/tool_definitions_parity.test.ts

@@ -0,0 +1,8 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { toolDefinitions } from '../../../src/server/tool-definitions.js'
+
+// Captured before structural refactoring: changes require an intentional contract review.
+const baseline = JSON.parse(await readFile(new URL('../../fixtures/contracts/tool-definitions.json', import.meta.url), 'utf8'))
+assert.deepEqual(toolDefinitions, baseline, 'Public tool order, schemas, defaults and descriptions must remain compatible')
+console.log('PASS public tool-definition compatibility baseline')