c64bridge 0.5.1 → 0.6.0

package/dist/rag/retriever.js

@@ -3,9 +3,24 @@ C64 Bridge - Local RAG Retriever
 GPL-2.0-only
 */
 import { cosineSimilarity } from "./embeddings.js";
+import { listKnowledgeResources } from "./knowledgeIndex.js";
 const BASIC_SIGNAL_RE = /(^\s*\d{1,5}\s)|\b(PRINT|POKE|GOTO|GOSUB|RESTORE|READ|DATA|INPUT|CHR\$|TI\$|TAB\()/im;
 const ASM_SIGNAL_RE = /(^\s*(?:[A-Z_][\w]*:)?\s*(?:\.?[A-Z]{2,4})\b)|\$[0-9A-F]{2,4}/im;
 const PROVENANCE_COMMENT_RE = /^\s*<!--\s*Source:\s*(.*?)\s*-->\s*/i;
+// Build a mapping from file paths to resource URIs
+function buildPathToUriMap() {
+    const resources = listKnowledgeResources();
+    const map = new Map();
+    for (const resource of resources) {
+        if (resource.relativePath) {
+            // Normalize the path for matching
+            const normalizedPath = resource.relativePath.replace(/\\/g, "/");
+            map.set(normalizedPath, resource.uri);
+        }
+    }
+    return map;
+}
+const PATH_TO_URI_MAP = buildPathToUriMap();
 export class LocalRagRetriever {
     constructor(model, opts) {
         this.model = model;
@@ -78,7 +93,9 @@ export class LocalRagRetriever {
         if (!normalized || normalized === "other")
             push(this.other);
         candidates.sort((a, b) => b.score - a.score);
-        return candidates.slice(0, topK).map((candidate) => ({
+        // Apply duplicate suppression and diversity
+        const deduplicated = deduplicateAndDiversify(candidates, topK);
+        return deduplicated.map((candidate) => ({
             snippet: candidate.snippet,
             origin: candidate.origin,
             uri: candidate.uri,
@@ -86,14 +103,82 @@ export class LocalRagRetriever {
             sourcePath: candidate.record.sourcePath,
             sourceUrl: candidate.record.sourceUrl,
             sourceRepoUrl: candidate.record.sourceRepoUrl,
-            license: candidate.record.license,
             licenseSpdxId: candidate.record.licenseSpdxId,
-            licenseName: candidate.record.licenseName,
-            licenseUrl: candidate.record.licenseUrl,
             attribution: candidate.record.attribution,
         }));
     }
 }
+function deduplicateAndDiversify(candidates, topK) {
+    // Step 1: Remove near-duplicates based on snippet similarity
+    const results = [];
+    const seenSnippets = new Set();
+    for (const candidate of candidates) {
+        // Normalize snippet for comparison (lowercase, trim whitespace)
+        const normalizedSnippet = candidate.snippet
+            .toLowerCase()
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 100); // Compare first 100 chars
+        // Skip if we've seen this snippet before
+        if (seenSnippets.has(normalizedSnippet)) {
+            continue;
+        }
+        // Check for high similarity with existing results
+        let isDuplicate = false;
+        for (const existing of results) {
+            const existingNormalized = existing.snippet
+                .toLowerCase()
+                .replace(/\s+/g, " ")
+                .trim()
+                .slice(0, 100);
+            // Simple Jaccard similarity on words
+            const words1 = new Set(normalizedSnippet.split(/\s+/));
+            const words2 = new Set(existingNormalized.split(/\s+/));
+            const intersection = new Set([...words1].filter((w) => words2.has(w)));
+            const union = new Set([...words1, ...words2]);
+            const similarity = intersection.size / union.size;
+            if (similarity > 0.85) {
+                isDuplicate = true;
+                break;
+            }
+        }
+        if (!isDuplicate) {
+            results.push(candidate);
+            seenSnippets.add(normalizedSnippet);
+        }
+        // Stop if we have enough results
+        if (results.length >= topK) {
+            break;
+        }
+    }
+    // Step 2: Ensure diversity in origins/resources
+    // If we have fewer results than topK, try to add more from different origins
+    if (results.length < topK && results.length < candidates.length) {
+        const usedOrigins = new Set(results.map((r) => r.origin || r.uri || "unknown"));
+        const remaining = candidates.filter((c) => !results.includes(c));
+        for (const candidate of remaining) {
+            const candidateOrigin = candidate.origin || candidate.uri || "unknown";
+            // Prefer candidates from different origins
+            if (!usedOrigins.has(candidateOrigin)) {
+                results.push(candidate);
+                usedOrigins.add(candidateOrigin);
+                if (results.length >= topK) {
+                    break;
+                }
+            }
+        }
+        // Fill remaining slots if still under topK
+        for (const candidate of remaining) {
+            if (!results.includes(candidate)) {
+                results.push(candidate);
+                if (results.length >= topK) {
+                    break;
+                }
+            }
+        }
+    }
+    return results.slice(0, topK);
+}
 function extractSnippetAndOrigin(text) {
     const match = PROVENANCE_COMMENT_RE.exec(text);
     if (!match) {
@@ -107,9 +192,30 @@ function extractSnippetAndOrigin(text) {
     };
 }
 function deriveUri(record, origin) {
+    // If origin is already a c64:// URI, use it
     if (origin && origin.startsWith("c64://")) {
         return origin;
     }
+    // Try to map the file path from origin to a resource URI
+    if (origin) {
+        // Extract the file path (before any '#' anchor)
+        const filePath = origin.split("#")[0];
+        const resourceUri = PATH_TO_URI_MAP.get(filePath);
+        if (resourceUri) {
+            // Preserve any anchor/section from the original origin
+            const anchor = origin.includes("#") ? "#" + origin.split("#")[1] : "";
+            return resourceUri + anchor;
+        }
+    }
+    // Try to map the source path from the record
+    if (record.sourcePath) {
+        const normalizedPath = record.sourcePath.replace(/\\/g, "/");
+        const resourceUri = PATH_TO_URI_MAP.get(normalizedPath);
+        if (resourceUri) {
+            return resourceUri;
+        }
+    }
+    // Fallback to source URLs
     if (record.sourceUrl) {
         return record.sourceUrl;
     }

package/dist/tools/audio.js

@@ -191,8 +191,12 @@ const musicGenerateArgsSchema = objectSchema({
         waveform: stringSchema({
             description: "Waveform for playback.",
             enum: ["pulse", "saw", "tri", "noise"],
-            default: "pulse",
+            default: "tri",
         }),
+        preset: optionalSchema(stringSchema({
+            description: "Optional musical preset to influence timing/expression.",
+            enum: ["classic", "expression"],
+        }), "classic"),
     },
     additionalProperties: false,
 });
@@ -474,7 +478,7 @@ export const audioModule = defineToolModule({
             description: "Trigger a SID voice with configurable waveform, pulse width, and ADSR envelope. See c64://specs/sid.",
             summary: "Resolves note or frequency, clamps parameters, and writes the SID voice registers.",
             inputSchema: sidNoteOnArgsSchema.jsonSchema,
-            tags: ["sid", "control", "music"],
+            tags: ["sid", "control", "music", "pal-ntsc"],
             prerequisites: ["sid_volume"],
             examples: [
                 { name: "Note on", description: "Voice 1 C4 triangle", arguments: { voice: 1, note: "C4", waveform: "tri" } },
@@ -511,12 +515,16 @@ export const audioModule = defineToolModule({
                         });
                     }
                     const detailRecord = toRecord(result.details) ?? {};
-                    return textResult(`Started SID voice ${voice}${parsed.note ? ` with note ${parsed.note.toUpperCase()}` : ""}.`, {
+                    const systemNote = parsed.system
+                        ? `Using ${parsed.system} timing.`
+                        : "Using default PAL timing. For NTSC, pass system: 'NTSC'. Check $02A6 memory location to verify system.";
+                    return textResult(`Started SID voice ${voice}${parsed.note ? ` with note ${parsed.note.toUpperCase()}` : ""}. ${systemNote}`, {
                         success: true,
                         voice,
                         note: parsed.note ?? null,
                         frequencyHz: parsed.frequencyHz ?? null,
                         system: parsed.system ?? "PAL",
+                        systemReminder: "$02A6 contains PAL/NTSC flag (1=NTSC, 0=PAL)",
                         waveform: parsed.waveform ?? "pulse",
                         pulseWidth: parsed.pulseWidth,
                         envelope: {
@@ -699,10 +707,11 @@ export const audioModule = defineToolModule({
             inputSchema: musicGenerateArgsSchema.jsonSchema,
             relatedResources: ["c64://specs/sid"],
             relatedPrompts: ["sid-music"],
-            tags: ["sid", "music", "generator"],
+            tags: ["sid", "music", "generator", "pal-ntsc"],
             prerequisites: ["sid_volume"],
             examples: [
-                { name: "C major", description: "C4 arpeggio", arguments: { root: "C4", pattern: "0,4,7", steps: 8, tempoMs: 120, waveform: "pulse" } },
+                { name: "C major", description: "C4 arpeggio (triangle)", arguments: { root: "C4", pattern: "0,4,7", steps: 8, tempoMs: 120, waveform: "tri" } },
+                { name: "Expressive C major", description: "C4 arpeggio with phrasing", arguments: { root: "C4", pattern: "0,4,7", steps: 8, preset: "expression" } },
             ],
             workflowHints: [
                 "Offer as a quick inspiration loop when the user wants to hear something immediately; explain how to tweak pattern or tempo.",
@@ -713,11 +722,13 @@ export const audioModule = defineToolModule({
                     const intervals = parseIntervals(parsed.pattern);
                     const timeline = [];
                     let timestamp = 0;
+                    const expressiveDurations = [250, 180, 180, 400];
                     for (let i = 0; i < parsed.steps; i += 1) {
                         const iv = intervals[i % intervals.length];
                         const note = transposeNote(parsed.root, iv);
-                        timeline.push({ t: timestamp, note });
-                        timestamp += parsed.tempoMs;
+                        const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
+                        timeline.push({ t: timestamp, note, durationMs });
+                        timestamp += durationMs;
                     }
                     ctx.logger.info("Scheduling SID arpeggio", {
                         root: parsed.root,
@@ -735,14 +746,15 @@ export const audioModule = defineToolModule({
                                 await ctx.client.sidNoteOn({
                                     voice: 1,
                                     note,
-                                    waveform: parsed.waveform,
+                                    waveform: (parsed.waveform ?? "tri"),
                                     pulseWidth: 0x0800,
                                     attack: 1,
-                                    decay: 2,
-                                    sustain: 8,
-                                    release: 3,
+                                    decay: 7,
+                                    sustain: 15,
+                                    release: 0,
                                 });
-                                await sleep(parsed.tempoMs);
+                                const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
+                                await sleep(durationMs);
                             }
                             await ctx.client.sidNoteOff(1);
                         }
@@ -757,7 +769,8 @@ export const audioModule = defineToolModule({
                         intervals,
                         steps: parsed.steps,
                         tempoMs: parsed.tempoMs,
-                        waveform: parsed.waveform,
+                        waveform: parsed.waveform ?? "tri",
+                        preset: parsed.preset ?? "classic",
                         timeline,
                     });
                 }

package/dist/tools/developer.js

@@ -140,6 +140,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "list"],
+            examples: [
+                { name: "List configs", description: "Enumerate configuration categories", arguments: {} },
+            ],
             workflowHints: [
                 "Run first to enumerate categories before reading or writing specific settings; summarise the top-level sections for the user.",
             ],
@@ -171,6 +174,10 @@ export const developerModule = defineToolModule({
             inputSchema: configGetArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "read"],
+            examples: [
+                { name: "Get audio config", description: "Read audio category", arguments: { category: "Audio" } },
+                { name: "Get volume", description: "Read specific setting", arguments: { category: "Audio", item: "Volume" } },
+            ],
             workflowHints: [
                 "Use after config_list to fetch details; restate category/item so the user can cross-check values before changes.",
             ],
@@ -203,6 +210,9 @@ export const developerModule = defineToolModule({
             inputSchema: configSetArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "write"],
+            examples: [
+                { name: "Set volume", description: "Adjust audio volume", arguments: { category: "Audio", item: "Volume", value: 75 } },
+            ],
             workflowHints: [
                 "Confirm the user-supplied value before writing; mention whether a reboot is required for the change to take effect.",
             ],
@@ -243,6 +253,9 @@ export const developerModule = defineToolModule({
             inputSchema: configBatchSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "write"],
+            examples: [
+                { name: "Batch update", description: "Update multiple settings", arguments: { Audio: { Volume: 80, DACMode: "stereo" } } },
+            ],
             workflowHints: [
                 "Use when multiple categories must be updated together; remind the user to review validation errors closely.",
             ],
@@ -283,6 +296,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "flash"],
+            examples: [
+                { name: "Load from flash", description: "Restore saved configuration", arguments: {} },
+            ],
             workflowHints: [
                 "Use when the user wants to revert to saved flash configuration; warn that unsaved RAM changes are discarded.",
             ],
@@ -316,6 +332,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "flash"],
+            examples: [
+                { name: "Save to flash", description: "Persist current config", arguments: {} },
+            ],
             workflowHints: [
                 "Run after configuration changes the user wants to persist; mention that flash writes take a moment.",
             ],
@@ -349,6 +368,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["config", "reset"],
+            examples: [
+                { name: "Reset config", description: "Restore factory defaults", arguments: {} },
+            ],
             workflowHints: [
                 "Confirm with the user before wiping settings; note that the firmware must restart to apply defaults fully.",
             ],
@@ -382,6 +404,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["diagnostics", "version"],
+            examples: [
+                { name: "Get version", description: "Check firmware version", arguments: {} },
+            ],
             workflowHints: [
                 "Run when the user wonders which firmware build is active; include API and FPGA versions if available.",
             ],
@@ -410,6 +435,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["diagnostics", "info"],
+            examples: [
+                { name: "Get hardware info", description: "Query hardware status", arguments: {} },
+            ],
             workflowHints: [
                 "Use to answer hardware capability questions; highlight serials, board revisions, or temperature if present.",
             ],
@@ -438,6 +466,9 @@ export const developerModule = defineToolModule({
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["debug"],
+            examples: [
+                { name: "Read debug register", description: "Check $D7FF value", arguments: {} },
+            ],
             workflowHints: [
                 "Read the register when debugging DMA or cartridge interactions; translate the hex value into context for the user.",
             ],
@@ -474,6 +505,9 @@ export const developerModule = defineToolModule({
             inputSchema: debugWriteArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap"],
             tags: ["debug"],
+            examples: [
+                { name: "Write debug register", description: "Set $D7FF to $42", arguments: { value: "42" } },
+            ],
             workflowHints: [
                 "Confirm with the user before writing arbitrary values; mention side effects on cartridge or DMA behaviour.",
             ],

package/dist/tools/graphics.js

@@ -273,7 +273,7 @@ export const graphicsModule = defineToolModule({
             inputSchema: spriteArgsSchema.jsonSchema,
             relatedResources: ["c64://specs/vic"],
             relatedPrompts: ["graphics-demo", "assembly-program"],
-            tags: ["sprite", "assembly"],
+            tags: ["sprite", "assembly", "pal-ntsc"],
             prerequisites: ["upload_and_run_asm"],
             examples: [
                 {
@@ -380,12 +380,12 @@ export const graphicsModule = defineToolModule({
         },
         {
             name: "create_petscii_image",
-            description: "Create PETSCII art from prompts or text, optionally run it on the C64, and return metadata. See c64://specs/basic and c64://specs/vic.",
-            summary: "Synthesises PETSCII art, generates a BASIC program, and uploads it unless dry-run is requested.",
+            description: "Create PETSCII art from prompts or text, optionally run it on the C64, and return metadata including PETSCII codes and glyphs. See c64://specs/basic, c64://specs/vic, and c64://specs/charset.",
+            summary: "Synthesises PETSCII art, generates a BASIC program with preview metadata (petsciiCodes, glyphs, dimensions), and uploads it unless dry-run is requested.",
             inputSchema: petsciiImageArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/basic", "c64://specs/vic"],
+            relatedResources: ["c64://specs/basic", "c64://specs/vic", "c64://specs/charset"],
             relatedPrompts: ["graphics-demo", "basic-program"],
-            tags: ["petscii", "basic"],
+            tags: ["petscii", "basic", "pal-ntsc"],
             prerequisites: ["upload_and_run_basic"],
             examples: [
                 {
@@ -396,6 +396,7 @@ export const graphicsModule = defineToolModule({
             ],
             workflowHints: [
                 "Trigger when the user provides creative prompts; clarify whether you ran the art or left it as a dry run.",
+                "Response includes petsciiCodes array and glyphs for character-level inspection.",
                 "Provide follow-up suggestions like saving the PRG or capturing the screen after rendering.",
             ],
             async execute(args, ctx) {

package/dist/tools/memory.js

@@ -79,7 +79,7 @@ export const memoryModule = defineToolModule({
             relatedResources: ["c64://context/bootstrap", "c64://specs/basic"],
             relatedPrompts: ["memory-debug", "basic-program", "assembly-program"],
             tags: ["screen", "memory"],
-            prerequisites: ["upload_and_run_basic"],
+            prerequisites: [],
             examples: [
                 {
                     name: "Capture screen",

package/dist/tools/pollValidator.js

@@ -0,0 +1,256 @@
+/*
+C64 Bridge - An MCP Server for the Commodore 64 Ultimate
+Copyright (C) 2025 Christian Gleissner
+
+Licensed under the GNU General Public License v2.0 or later.
+See <https://www.gnu.org/licenses/> for details.
+*/
+/**
+ * Load poll configuration from environment variables with defaults.
+ */
+export function loadPollConfig() {
+    // In test environments with mock target, use shorter timeouts to avoid interfering with test screen queues
+    const isTestMode = process.env.C64_TEST_TARGET === "mock" || process.env.NODE_ENV === "test";
+    const defaultMaxMs = isTestMode ? 100 : 2000;
+    const defaultIntervalMs = isTestMode ? 30 : 200;
+    const maxMs = parseInt(process.env.C64BRIDGE_POLL_MAX_MS ?? String(defaultMaxMs), 10);
+    const intervalMs = parseInt(process.env.C64BRIDGE_POLL_INTERVAL_MS ?? String(defaultIntervalMs), 10);
+    return {
+        maxMs: Number.isFinite(maxMs) && maxMs > 0 ? maxMs : defaultMaxMs,
+        intervalMs: Number.isFinite(intervalMs) && intervalMs > 0 ? intervalMs : defaultIntervalMs,
+    };
+}
+/**
+ * Wait for a specified duration.
+ */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Compute SHA-1 hash of screen content for change detection.
+ */
+/**
+ * Compute fast 32-bit CRC32 checksum of buffer for change detection.
+ */
+function computeCrc32(buffer) {
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < buffer.length; i++) {
+        crc ^= buffer[i];
+        for (let j = 0; j < 8; j++) {
+            crc = (crc >>> 1) ^ (crc & 1 ? 0xEDB88320 : 0);
+        }
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+/**
+ * Compare two Uint8Arrays for equality.
+ */
+function buffersEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Concatenate multiple Uint8Arrays into a single buffer.
+ */
+function concatBuffers(...buffers) {
+    const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const buf of buffers) {
+        result.set(buf, offset);
+        offset += buf.length;
+    }
+    return result;
+}
+/**
+ * Extract BASIC error information from screen text.
+ * Looks for patterns like "?SYNTAX ERROR" or "SYNTAX ERROR IN 120".
+ */
+function extractBasicError(screen) {
+    const upperScreen = screen.toUpperCase();
+    // Check if ERROR appears on screen
+    if (!upperScreen.includes("ERROR")) {
+        return null;
+    }
+    // Try to match "?ERROR_TYPE ERROR" or "ERROR_TYPE ERROR IN LINE"
+    const errorMatch = /\?([A-Z\s]+)\s+ERROR(?:\s+IN\s+(\d+))?/i.exec(screen);
+    if (errorMatch) {
+        const errorType = errorMatch[1]?.trim().replace(/\s+/g, " ");
+        const lineStr = errorMatch[2];
+        const line = lineStr ? parseInt(lineStr, 10) : undefined;
+        return {
+            message: errorType,
+            line: Number.isFinite(line) ? line : undefined,
+        };
+    }
+    // Fallback: just "ERROR" appears
+    return { message: "UNKNOWN ERROR" };
+}
+/**
+ * Poll for BASIC program outcome by detecting errors on screen.
+ * First waits for RUN or ERROR to appear, then continues polling for errors.
+ */
+async function pollBasicOutcome(client, logger, config) {
+    const startTime = Date.now();
+    let pollCount = 0;
+    let runDetected = false;
+    logger.debug("Starting BASIC outcome polling", { maxMs: config.maxMs, intervalMs: config.intervalMs });
+    while (Date.now() - startTime < config.maxMs) {
+        pollCount++;
+        try {
+            const screen = await client.readScreen();
+            const upperScreen = screen.toUpperCase();
+            // Check if RUN or ERROR appeared (indicating execution started or failed)
+            if (!runDetected && (upperScreen.includes("RUN") || upperScreen.includes("ERROR"))) {
+                runDetected = true;
+                logger.debug("Program execution detected", { pollCount, elapsed: Date.now() - startTime });
+            }
+            // Check for errors
+            const errorInfo = extractBasicError(screen);
+            if (errorInfo) {
+                logger.debug("BASIC error detected", { errorInfo, pollCount, elapsed: Date.now() - startTime });
+                return {
+                    status: "error",
+                    type: "BASIC",
+                    message: errorInfo.message,
+                    line: errorInfo.line,
+                };
+            }
+            // If we detected RUN and no error yet, continue polling
+            if (runDetected) {
+                // Continue polling for a bit to catch any delayed errors
+                // but if we've been polling for a while without errors, consider it successful
+            }
+        }
+        catch (error) {
+            logger.debug("Failed to read screen during BASIC polling", { error, pollCount });
+        }
+        await delay(config.intervalMs);
+    }
+    logger.debug("BASIC polling completed without errors", { pollCount, elapsed: Date.now() - startTime });
+    return {
+        status: "ok",
+        type: "BASIC",
+    };
+}
+/**
+ * Poll for Assembly program outcome by detecting hardware and screen activity.
+ * Monitors VIC-II, SID, CIA, jiffy clock, screen memory, and low memory (zero page + stack)
+ * to determine if program is alive or crashed.
+ * First waits for RUN to appear, then monitors for activity across multiple memory regions.
+ */
+async function pollAsmOutcome(client, logger, config) {
+    const startTime = Date.now();
+    let pollCount = 0;
+    let runDetected = false;
+    logger.debug("Starting ASM outcome polling with hardware monitoring", { maxMs: config.maxMs, intervalMs: config.intervalMs });
+    // Wait for RUN to appear first
+    while (Date.now() - startTime < config.maxMs && !runDetected) {
+        try {
+            const screen = await client.readScreen();
+            const upperScreen = screen.toUpperCase();
+            if (upperScreen.includes("RUN") || upperScreen.includes("ERROR")) {
+                runDetected = true;
+                logger.debug("RUN detected, starting 100ms stabilization", { elapsed: Date.now() - startTime });
+                // Wait 100ms for stabilization as per spec
+                await delay(100);
+                break;
+            }
+        }
+        catch (error) {
+            logger.debug("Failed to read screen while waiting for RUN", { error });
+        }
+        await delay(config.intervalMs);
+    }
+    // If RUN never appeared, assume instant execution (success)
+    if (!runDetected) {
+        logger.debug("RUN never detected, assuming instant execution");
+        return {
+            status: "ok",
+            type: "ASM",
+        };
+    }
+    // Now poll hardware regions to detect activity
+    let prevIoSignature = null;
+    let prevJiffyClock = null;
+    let alive = false;
+    const pollDeadline = Date.now() + config.maxMs;
+    while (Date.now() < pollDeadline && !alive) {
+        pollCount++;
+        try {
+            // Read I/O regions in optimized batches as per comment #3466803675
+            // All of $D000-$DFFF in a single call (covers VIC-II, SID, CIA1, CIA2)
+            const ioRegions = await client.readMemoryRaw(0xD000, 0x1000); // $D000-$DFFF
+            // Read low memory through screen RAM in a single call: $0000-$07E7
+            // This covers zero page, stack, jiffy clock ($00A0-$00A2), and screen memory
+            const lowMemAndScreen = await client.readMemoryRaw(0x0000, 0x7E8); // $0000-$07E7
+            // Extract jiffy clock for separate comparison (at offset $00A0 in the buffer)
+            const jiffyClock = lowMemAndScreen.slice(0xA0, 0xA3);
+            // Concatenate all regions and compute signature
+            const combinedBuffer = concatBuffers(ioRegions, lowMemAndScreen);
+            const ioSignature = computeCrc32(combinedBuffer);
+            // Check for any activity
+            if (prevIoSignature !== null && ioSignature !== prevIoSignature) {
+                logger.debug("Hardware or screen activity detected", {
+                    pollCount,
+                    elapsed: Date.now() - startTime,
+                    signatureChanged: true
+                });
+                alive = true;
+                break;
+            }
+            if (prevJiffyClock !== null && !buffersEqual(jiffyClock, prevJiffyClock)) {
+                logger.debug("Jiffy clock advanced", {
+                    pollCount,
+                    elapsed: Date.now() - startTime,
+                    clockChanged: true
+                });
+                alive = true;
+                break;
+            }
+            prevIoSignature = ioSignature;
+            prevJiffyClock = jiffyClock;
+        }
+        catch (error) {
+            logger.debug("Failed to read memory during ASM polling", { error, pollCount });
+        }
+        await delay(config.intervalMs);
+    }
+    if (alive) {
+        logger.debug("ASM program alive - hardware or screen progressing", { pollCount, elapsed: Date.now() - startTime });
+        return {
+            status: "ok",
+            type: "ASM",
+        };
+    }
+    // No activity detected - consider it crashed
+    logger.debug("ASM program crashed - no VIC/CIA/TI/screen progression", { pollCount, elapsed: Date.now() - startTime });
+    return {
+        status: "crashed",
+        type: "ASM",
+        reason: "no VIC/CIA/TI/screen progression within window",
+    };
+}
+/**
+ * Main polling function that polls for program outcome.
+ *
+ * @param type - Type of program (BASIC or ASM)
+ * @param client - C64 client for screen reading
+ * @param logger - Logger for debug output
+ * @param config - Optional poll configuration (uses environment defaults if not provided)
+ * @returns Promise resolving to poll result
+ */
+export async function pollForProgramOutcome(type, client, logger, config) {
+    const pollConfig = config ?? loadPollConfig();
+    logger.debug("Starting program outcome polling", { type, maxMs: pollConfig.maxMs, intervalMs: pollConfig.intervalMs });
+    // Poll for program outcome based on type
+    if (type === "BASIC") {
+        return pollBasicOutcome(client, logger, pollConfig);
+    }
+    return pollAsmOutcome(client, logger, pollConfig);
+}