simorisc

#!/usr/bin/env python3
"""simorisc — Object RISC instruction-set simulator.

Loads an .orx binary per CONTRACT.md Section 1, sets up the initial task
state per Section 2, and executes Object RISC instructions with the
architectural semantics of Volume II. Implements the firmware primitives
TaskExit (0x001), ObjAlloc (0x100), ObjFree (0x101), ObjDerive (0x103),
InstallHandler (0x200), and ConsoleWrite (0x320). Every other CALL
primitive returns R2 = ENOSYS.

Multi-CPU mode (`--processors N`) instantiates N CPUs sharing a crossbar.
The same .orx is loaded onto each CPU; they branch on R7 (PROCID).
Each CPU also receives a "service" object: O4 = my own (full caps),
O5..O5+N-2 = the other CPUs' service objects (R+S only). SEND through a
remote object reference is queued to the home CPU's inbox; that CPU
dispatches the registered handler when its main task is idle (one task
per CPU at a time).

The simulator models architectural ISA semantics, not microarchitecture:
no pipeline, no caches, no real TLB. Architectural delay slots ARE
honoured (branch decision committed before the delay-slot instruction
executes). Cross-CPU OL/OS access is dispatched synchronously through
the home CPU's local descriptor table.
"""

import argparse
import colorsys
import re
import select
import struct
import sys
import time
from dataclasses import dataclass, field
from typing import Dict, List, Optional, Tuple

# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------

MAGIC = b"ORISC\x00\x00\x00"

# Capability bits (Volume III): R W X S V M C reserved (LSB to MSB).
CAP_R = 1 << 0
CAP_W = 1 << 1
CAP_X = 1 << 2
CAP_S = 1 << 3
CAP_V = 1 << 4
CAP_M = 1 << 5
CAP_C = 1 << 6

# Trap cause codes (Volume II Section 13).
CAUSE_EXTERNAL_INTERRUPT= 0x01
CAUSE_BUS_ERROR_I       = 0x02
CAUSE_BUS_ERROR_D       = 0x03
CAUSE_ADDR_MISALIGN_I   = 0x04
CAUSE_ADDR_MISALIGN_D   = 0x05
CAUSE_TLB_MISS_I        = 0x06
CAUSE_TLB_MISS_D        = 0x07
CAUSE_PAGE_PERMISSION   = 0x08
CAUSE_ARITH_OVERFLOW    = 0x09
CAUSE_RESERVED_INSTR    = 0x0A
CAUSE_PRIV_INSTR        = 0x0B
CAUSE_BREAKPOINT        = 0x0C
CAUSE_NULL_DEREF        = 0x10
CAUSE_STALE_REF         = 0x11
CAUSE_BOUNDS            = 0x12
CAUSE_CAP_VIOLATION     = 0x13
CAUSE_SEND_OVERFLOW     = 0x14
CAUSE_FIRMWARE_CALL     = 0x20
CAUSE_RESERVED_CALL     = 0x21

CAUSE_NAMES = {
    CAUSE_EXTERNAL_INTERRUPT: "external-interrupt",
    CAUSE_BUS_ERROR_I:    "bus-error-i",
    CAUSE_BUS_ERROR_D:    "bus-error-d",
    CAUSE_ADDR_MISALIGN_I:"address-misaligned-i",
    CAUSE_ADDR_MISALIGN_D:"address-misaligned-d",
    CAUSE_TLB_MISS_I:     "tlb-miss-i",
    CAUSE_TLB_MISS_D:     "tlb-miss-d",
    CAUSE_PAGE_PERMISSION:"page-permission",
    CAUSE_ARITH_OVERFLOW: "arithmetic-overflow",
    CAUSE_RESERVED_INSTR: "reserved-instruction",
    CAUSE_PRIV_INSTR:     "privileged-instruction",
    CAUSE_BREAKPOINT:     "breakpoint",
    CAUSE_NULL_DEREF:     "null-dereference",
    CAUSE_STALE_REF:      "stale-reference",
    CAUSE_BOUNDS:         "bounds-violation",
    CAUSE_CAP_VIOLATION:  "capability-violation",
    CAUSE_SEND_OVERFLOW:  "send-buffer-overflow",
    CAUSE_FIRMWARE_CALL:  "firmware-call",
    CAUSE_RESERVED_CALL:  "reserved-call",
}

# Standard firmware error codes (Volume VI Section 2.4).
ERR_OK       = 0
ERR_EINVAL   = 1
ERR_ENOMEM   = 2
ERR_EPERM    = 3
ERR_ENOSYS   = 4
ERR_EBUSY    = 5
ERR_ENOENT   = 6
ERR_ETIMEOUT = 7
ERR_EFAULT   = 8
ERR_EAGAIN   = 9
ERR_ESTALE   = 10
ERR_EREMOTE  = 11

# Type tags reserved by the contract loader.
TAG_CODE        = 0x4100
TAG_STACK       = 0x4101
TAG_DATA        = 0x4102
TAG_SERVICE     = 0x4103
TAG_TASK        = 0x4104   # task object (Volume VI Section 4)
TAG_INPUT_SINK  = 0x4105   # Phase 60 step 3 — host-input-event sink
TAG_FRAMEBUFFER = 0x4106   # Phase 60 — host-display-backed pixel object
                           # (was 0x4104, which collided with TAG_TASK;
                           # the free paths branch on `== TAG_TASK`, so a
                           # framebuffer was misclassified as a task)

# Task lifecycle states (Volume VI Section 4.2). Internal numbering;
# returned by TaskQuery in the low 8 bits of the packed state word.
TASK_STATE_NEW       = 0
TASK_STATE_RUNNABLE  = 1
TASK_STATE_RUNNING   = 2
TASK_STATE_SUSPENDED = 3
TASK_STATE_BLOCKED   = 4   # parked on IPC; not yet used
TASK_STATE_EXITED    = 5

# Service object layout: 64 bytes, present on every CPU in multi-CPU mode.
SERVICE_OBJ_SIZE = 64

# Privilege modes (Volume II Section 13). Numerically ordered: a check
# `cpu.mode >= MODE_SUPERVISOR` admits both supervisor and firmware.
MODE_USER       = 0
MODE_SUPERVISOR = 1
MODE_FIRMWARE   = 2
MODE_NAMES = {0: "user", 1: "supervisor", 2: "firmware"}

# Control register numbers (Volume V Section 2.10). Registers 0–7 are
# accessible from supervisor mode; 8 and above are firmware-only. Only a
# subset is materialised in this simulator — see CPU._ctrl_read/_write.
CTRL_STATUS   = 0
CTRL_CAUSE    = 1
CTRL_EPC      = 2
CTRL_BADVADDR = 3
CTRL_CONTEXT  = 4
CTRL_COUNT    = 5
CTRL_COMPARE  = 6
CTRL_PROCID   = 7
CTRL_VECBASE  = 8
CTRL_SV_MAX   = 7   # any ctrl > this requires firmware mode

# Trap-vector offsets per Volume II Appendix B. The vector base lives in
# the VECBASE control register; on a trap delivery the CPU jumps to
# `VECBASE + CAUSE_VECTOR_OFFSET[cause]`. Each vector is 64 bytes
# (16 instructions) — enough for a short trampoline that branches out to
# a longer handler. Causes not listed here can't be delivered to a
# vector and fall back to the fatal-trap path (current behaviour).
CAUSE_VECTOR_OFFSET = {
    0x00: 0x000,  # reset (synthetic; never raised at runtime)
    0x01: 0x040,  # external-interrupt
    0x02: 0x080,  # bus-error-i
    0x03: 0x0C0,  # bus-error-d
    0x04: 0x100,  # address-misaligned-i
    0x05: 0x140,  # address-misaligned-d
    0x06: 0x180,  # tlb-miss-i
    0x07: 0x1C0,  # tlb-miss-d
    0x08: 0x200,  # page-permission
    0x09: 0x240,  # arithmetic-overflow
    0x0A: 0x280,  # reserved-instruction
    0x0B: 0x2C0,  # privileged-instruction
    0x0C: 0x300,  # breakpoint
    0x10: 0x400,  # null-dereference
    0x11: 0x440,  # stale-reference
    0x12: 0x480,  # bounds-violation
    0x13: 0x4C0,  # capability-violation
    0x14: 0x500,  # send-buffer-overflow
    0x20: 0x800,  # firmware-call (CALL)
    0x21: 0x840,  # reserved-call
}

# ---------------------------------------------------------------------------
# Object descriptor and reference layout
# ---------------------------------------------------------------------------

@dataclass
class Descriptor:
    """An object descriptor in a CPU's local object table.

    We don't model the 32-byte on-the-wire layout from Volume III Section
    3.2 here; we keep the architecturally observable state in Python form
    and rely on the generation-counter semantics to make accesses
    cache-coherent (Volume III Section 4)."""
    storage: bytearray
    length: int
    generation: int
    type_tag: int
    max_caps: int
    flags: int = 0
    live: bool = True
    send_handler_ref: int = 0
    send_handler_off: int = 0
    send_handler_va:  int = 0   # populated by InstallHandler from object's mapping
    objstore: bool = False      # if True, storage is OR-typed (OREFLD/OREFST only)
    # Receive-queue mode: when set by ReceiveQueueAttach, incoming SENDs are
    # appended here instead of dispatching a handler task. queue_max_depth
    # bounds the queue length; arrivals beyond it are dropped.
    queue: Optional[List] = None
    queue_max_depth: int = 0
    # Phase 60 — host-display backing.  Set on TAG_FRAMEBUFFER objects
    # by primitive_ObjAllocFramebuffer.  fb_dirty is toggled by
    # ObjStoreBytes; the --display worker repaints when it sees the
    # flag set, then clears it.  fb_width/fb_height let the worker
    # build a Tk PhotoImage of the right shape.
    fb_width:  int = 0
    fb_height: int = 0
    fb_dirty:  bool = False
    # Phase 60 step 3 — host-input-event sink.  Set on TAG_INPUT_SINK
    # objects allocated via primitive_ObjAllocInputSink.
    # input_kind: 0 = keyboard, 1 = pointer.
    input_kind: int = -1


def make_ref(generation: int, home: int, index: int, caps: int) -> int:
    """Pack a 64-bit object reference per Volume III Section 2.1.

       63       48 47    40 39          16 15  8 7 0
       generation  home pr  local idx     caps  rsv
    """
    assert 0 <= generation < (1 << 16)
    assert 0 <= home < (1 << 8)
    assert 0 <= index < (1 << 24)
    assert 0 <= caps < (1 << 8)
    return ((generation & 0xFFFF) << 48) | \
           ((home       & 0xFF)   << 40) | \
           ((index      & 0xFFFFFF) << 16) | \
           ((caps       & 0xFF)   << 8)


def ref_generation(ref: int) -> int:  return (ref >> 48) & 0xFFFF
def ref_home(ref: int)       -> int:  return (ref >> 40) & 0xFF
def ref_index(ref: int)      -> int:  return (ref >> 16) & 0xFFFFFF
def ref_caps(ref: int)       -> int:  return (ref >>  8) & 0xFF


# ---------------------------------------------------------------------------
# Tasks (Volume VI Section 4)
# ---------------------------------------------------------------------------

@dataclass
class Task:
    """A swappable execution context. The CPU's per-task fields
    (general/object registers, PC, mode, the supervisor-visible control
    registers, and the address-space mappings) are mirrored here so the
    scheduler can save out the running task and load another in.

    Per-CPU state (descriptor table, inbox, request/response queues,
    cycle counter, VECBASE) lives on the CPU, not the task. VECBASE
    is firmware-installed once per CPU and shared by every task."""
    descriptor_idx: int             # index in cpu.descriptors for the task ref
    code_ref:  int = 0              # original code object (kept for restart/debug)
    stack_ref: int = 0              # original stack object
    state:     int = TASK_STATE_NEW
    exit_code: Optional[int] = None

    # Saved register file. CPU's gpr/opr/etc. become these on context-in.
    gpr: List[int] = field(default_factory=lambda: [0]*32)
    opr: List[int] = field(default_factory=lambda: [0]*16)
    hi:  int = 0
    lo:  int = 0
    pc:  int = 0
    next_pc: int = 0

    # Privilege state — current mode and whatever ERET / trap delivery
    # has stashed so far. Each task's traps are private to it.
    mode:        int = MODE_SUPERVISOR
    saved_mode:  int = MODE_SUPERVISOR
    saved_pc:    int = 0
    cause_reg:   int = 0
    badvaddr_reg: int = 0

    # Address space. Each task carries its own virtual-address layout;
    # the CPU's `mappings` list IS the running task's layout.
    mappings: List[Tuple[int,int,int,int,int]] = field(default_factory=list)

    # Tasks parked in TaskWait on this one. When this task transitions to
    # EXITED, every entry's R3 is filled with the exit code, R2 with OK,
    # and the waiter is moved BLOCKED → RUNNABLE. The list is then
    # cleared (waiters can't double-collect).
    waiters: List['Task'] = field(default_factory=list)

    # Phase 45d: remote callers waiting on this task via TASK_WAIT_REQ.
    # Each entry is (waiter_pid, trans_id); on EXITED we send a
    # TASK_WAIT_RESP back to each. Cleared after the responses go out.
    remote_waiters: List[Tuple[int, int]] = field(default_factory=list)

    # IPC blocked_on saved with this task. When the current task hits
    # a blocking primitive (ReceiveQueuePoll on an empty queue, remote
    # OL/OS waiting on a response) and there's another runnable task
    # we'd like to schedule, save the BlockedSignal here so the
    # scheduler can switch in the runnable task and process this
    # task's unblock condition asynchronously. Phase 36.
    blocked_on: Optional['BlockedSignal'] = None


# ---------------------------------------------------------------------------
# Trap exception
# ---------------------------------------------------------------------------

class Trap(Exception):
    def __init__(self, cause: int, faulting_pc: int, detail: str = "",
                 bad_vaddr: int = 0):
        self.cause = cause
        self.faulting_pc = faulting_pc
        self.bad_vaddr = bad_vaddr & 0xFFFFFFFF
        self.detail = detail
        super().__init__(f"trap {CAUSE_NAMES.get(cause, hex(cause))} @ "
                         f"0x{faulting_pc:08x}: {detail}")


class TaskExitSignal(Exception):
    """Raised by primitive_TaskExit; caught by the System scheduler."""
    def __init__(self, code: int):
        self.code = code


class BlockedSignal(Exception):
    """Base class for "hold the CPU at this instruction" signals. Two
    subclasses cover the cases we currently need; both are caught at the
    instruction-dispatch site (CALL or OL/OS) and observed by the
    scheduler to suspend and later resume the CPU."""
    pass


class BlockedOnQueue(BlockedSignal):
    """Raised by ReceiveQueuePoll when its target queue is empty and the
    timeout is non-zero. The scheduler holds the CPU at the CALL until
    the queue receives a message (or timeout expires); on resume it
    populates registers per Volume VI Section 6 and advances PC."""
    def __init__(self, descriptor_idx: int, timeout: int):
        self.descriptor_idx = descriptor_idx
        # timeout: -1 = infinite; otherwise number of scheduler ticks remaining
        self.timeout = timeout


class BlockedOnQueueSet(BlockedSignal):
    """Raised by WaitAnyQueue (#0x206) when EVERY queue in the listed set
    is empty. The scheduler holds the CPU at the CALL until ANY listed
    queue receives a message, then returns ERR_OK and advances PC — a
    pure readiness wait, no message delivery (mirror of BlockedOnQueue
    but for a set, and it never pops). `deadline` (absolute wall-clock
    time.time() seconds, or None) optionally bounds the wait: once
    time.time() >= deadline with no queue ready, _try_unblock_queue_set
    resumes the CALL with ERR_ETIMEOUT instead of ERR_OK. The bound is
    WALL-CLOCK, not scheduler ticks (unlike BlockedOnQueue), so it fires
    correctly even while the WM is parked and other tasks run, and a
    requested microsecond delay maps straight to real time.

    `descriptor_indices` is the set of local descriptor indices resolved
    (and validated) at primitive-entry time. The WM owns every queue in
    the set (home == self) and is single-threaded while blocked, so the
    set can't be mutated under us; the wake/unblock checks still re-probe
    each descriptor defensively before reading its queue."""
    def __init__(self, descriptor_indices, deadline=None):
        self.descriptor_indices = descriptor_indices
        self.deadline = deadline


class BlockedOnResponse(BlockedSignal):
    """Raised by remote OL/OS instructions after queueing an OBJ_READ_REQ
    or OBJ_WRITE_REQ on the home CPU. The scheduler holds the CPU at the
    OL/OS instruction until a matching response arrives; on resume it
    either writes the loaded value into the destination register
    (`OBJ_READ_RESP` with flags=OK), no-ops (`OBJ_WRITE_RESP` with
    flags=OK), or raises a Trap (any non-OK flags)."""
    def __init__(self, trans_id: int, *, target_reg: Optional[int] = None,
                 width: int = 0, signed: bool = False, is_write: bool = False):
        self.trans_id = trans_id
        self.target_reg = target_reg
        self.width = width
        self.signed = signed
        self.is_write = is_write


class BlockedOnExitWait(BlockedSignal):
    """Set by primitive_TaskExit when the exiting task was the only
    runnable task but other tasks remain BLOCKED (e.g., a shell
    parked on RecvQueuePoll waiting for a key). The CPU stays alive
    so _process_requests can answer in-flight OBJ_READ_REQs from
    the just-finished task's data segment, and so _wake_blocked_tasks
    can promote a blocked task once its condition fires; the
    blocked-but-runnable branch in run() then context-switches into
    it. There's no "unblock" condition tied to this signal — it's a
    sentinel, not a wait — so _try_unblock returns False and the
    blocked-but-runnable branch is the only path that consumes it."""
    pass


class BlockedOnTaskWait(BlockedSignal):
    """Phase 45d. Raised by primitive_TaskWait when the target ref's
    home is a different CPU. The caller queues a TASK_WAIT_REQ on the
    home and parks here until the matching TASK_WAIT_RESP arrives;
    on resume R2 receives the status word, R3 the exit code (when
    status == OK), and PC advances past the CALL."""
    def __init__(self, trans_id: int):
        self.trans_id = trans_id


class BlockedOnTaskQuery(BlockedSignal):
    """Phase 45d. Raised by primitive_TaskQuery for remote refs. On
    response R2 = status, R3 = packed state word; PC advances."""
    def __init__(self, trans_id: int):
        self.trans_id = trans_id


class BlockedOnTaskKill(BlockedSignal):
    """Phase 45d. Raised by primitive_TaskKill for remote refs. On
    response R2 = status; no other GPRs touched; PC advances."""
    def __init__(self, trans_id: int):
        self.trans_id = trans_id


class BlockedOnObjFetch(BlockedSignal):
    """Phase 45e. Raised by primitive_ObjFetchBytes when the source ref
    is remote. The CALL holds PC until the matching OBJ_READ_RESP
    arrives; on resume the response data is copied into the local
    destination descriptor at (dst_idx, dst_off..dst_off+byte_count),
    R2 = ERR_OK or remote-fault-derived ERR_*, R3 = bytes copied,
    PC advances. On a remote-side fault flag we never end up writing
    the destination — caller sees R3 = 0."""
    def __init__(self, trans_id: int, dst_idx: int, dst_off: int,
                 byte_count: int):
        self.trans_id = trans_id
        self.dst_idx = dst_idx
        self.dst_off = dst_off
        self.byte_count = byte_count


class BlockedOnObjStore(BlockedSignal):
    """Phase 59 (Object RISC Vol VI #0x109). Raised by
    primitive_ObjStoreBytes when the destination ref is remote.
    The CALL holds PC until the matching OBJ_WRITE_RESP arrives;
    on resume R2 = ERR_OK / ERR_*, R3 = byte_count on OK or 0 on
    fault, PC advances.  Mirror of BlockedOnObjFetch for the write
    direction — used by the WM's glyph renderer to push bitmap-font
    rows to a remote framebuffer in a single wire RTT."""
    def __init__(self, trans_id: int, byte_count: int):
        self.trans_id = trans_id
        self.byte_count = byte_count


# ---------------------------------------------------------------------------
# Wire-level packet format (Volume IV §3, §4)
# ---------------------------------------------------------------------------
#
# Every packet is:
#   header (8 bytes) | payload (length × 4 bytes) | checksum (4 bytes)
#
# The header layout (Volume IV §3.1) is:
#   src_pid (8) | dst_pid (8) | type (8) | flags (8) | trans_id (16) | length (16)
# where length is the number of payload words (not bytes), big-endian throughout.
# The trailing checksum is the bitwise XOR of every header and payload word.
#
# Message types are taken from Volume IV §4. Phase 1 implements only
# SEND_DELIVER (0x20) on the wire; Phase 2 will add OBJ_READ_REQ/RESP (0x10/11)
# and OBJ_WRITE_REQ/RESP (0x12/13) so that remote OL/OS likewise flow as
# real packets.

# Packet type codes.
PKT_OBJ_READ_REQ    = 0x10
PKT_OBJ_READ_RESP   = 0x11
PKT_OBJ_WRITE_REQ   = 0x12
PKT_OBJ_WRITE_RESP  = 0x13
PKT_SEND_DELIVER    = 0x20
PKT_SEND_ACK        = 0x21
PKT_DESC_REQ        = 0x30
PKT_DESC_RESP       = 0x31
PKT_DESC_FORWARD    = 0x32
PKT_DESC_INVALIDATE = 0x33
# Phase 45d — remote task primitives. The home CPU is the source of truth
# for a task's state; remote callers exchange these request/response
# packets to invoke TaskWait/Query/Kill across CPU boundaries. Status
# travels in the response payload (rather than the flags byte) because
# the architectural Task API uses ERR_* codes that don't all map to the
# 6-bit RESP_* fault codes used by OL/OS responses.
PKT_TASK_WAIT_REQ   = 0x40
PKT_TASK_WAIT_RESP  = 0x41
PKT_TASK_QUERY_REQ  = 0x42
PKT_TASK_QUERY_RESP = 0x43
PKT_TASK_KILL_REQ   = 0x44
PKT_TASK_KILL_RESP  = 0x45
# Phase 60 follow-up — headless host-input injection.  A test harness
# (fake_terminal) sends this to a WM's CPU to deliver a keyboard/pointer
# event into that CPU's local TAG_INPUT_SINK, exactly as the Tk display
# worker does for live input.  payload = [kind, w0, w1, w2, w3] where
# kind 0=keyboard ([code, mods, 0, 0]), 1=pointer ([evt, xy, btn, state]).
PKT_HOST_INPUT      = 0x50
PKT_LINK_FLOW_CREDIT= 0xF0
PKT_LINK_ERROR      = 0xF1
PKT_LINK_HEARTBEAT  = 0xFE
PKT_LINK_RESET      = 0xFF


def pack_packet(src_pid: int, dst_pid: int, msg_type: int, flags: int,
                trans_id: int, payload_words: List[int]) -> bytes:
    """Build a wire-format packet per Volume IV §3.1 + §3.2."""
    length_words = len(payload_words)
    header_bytes = struct.pack(">BBBBHH",
                               src_pid & 0xFF, dst_pid & 0xFF,
                               msg_type & 0xFF, flags & 0xFF,
                               trans_id & 0xFFFF, length_words & 0xFFFF)
    payload_bytes = b''.join(struct.pack(">I", w & 0xFFFFFFFF)
                             for w in payload_words)
    # Checksum = XOR of header and payload words (header is two 32-bit words).
    h0, h1 = struct.unpack(">II", header_bytes)
    chk = h0 ^ h1
    for w in payload_words:
        chk ^= w & 0xFFFFFFFF
    return header_bytes + payload_bytes + struct.pack(">I", chk & 0xFFFFFFFF)


def unpack_packet(data: bytes) -> Dict:
    """Parse a wire-format packet and validate its size/checksum.
    Returns dict with src_pid, dst_pid, type, flags, trans_id, payload (list of words).
    Raises ValueError on malformed input."""
    if len(data) < 12:
        raise ValueError(f"packet too short: {len(data)} bytes")
    src, dst, mtype, flags, trans_id, length_words = \
        struct.unpack(">BBBBHH", data[:8])
    expected_total = 8 + length_words * 4 + 4
    if len(data) != expected_total:
        raise ValueError(
            f"packet length mismatch: header says {length_words} payload "
            f"words, total bytes {len(data)} != expected {expected_total}")
    payload_bytes = data[8:8 + length_words * 4]
    payload_words = list(struct.unpack(f">{length_words}I", payload_bytes)
                         if length_words else [])
    h0, h1 = struct.unpack(">II", data[:8])
    chk = h0 ^ h1
    for w in payload_words:
        chk ^= w
    expected_chk = struct.unpack(">I", data[-4:])[0]
    if (chk & 0xFFFFFFFF) != expected_chk:
        raise ValueError(
            f"checksum mismatch: computed {chk:#010x}, "
            f"packet says {expected_chk:#010x}")
    return {
        "src_pid": src, "dst_pid": dst, "type": mtype, "flags": flags,
        "trans_id": trans_id, "payload": payload_words,
    }


def build_send_deliver(src_pid: int, dst_pid: int, trans_id: int,
                       recipient_ref: int, int_payload: List[int],
                       or_payload: List[int]) -> bytes:
    """Construct a SEND_DELIVER packet (Volume IV §4.2) from an in-memory
    PendingSend's contents. Object references travel low-half-first
    (Volume IV §4.1)."""
    payload: List[int] = []
    payload.append(recipient_ref & 0xFFFFFFFF)
    payload.append((recipient_ref >> 32) & 0xFFFFFFFF)
    for w in int_payload[:4]:
        payload.append(w & 0xFFFFFFFF)
    for ref in or_payload[:4]:
        payload.append(ref & 0xFFFFFFFF)
        payload.append((ref >> 32) & 0xFFFFFFFF)
    return pack_packet(src_pid, dst_pid, PKT_SEND_DELIVER, 0, trans_id, payload)


def parse_send_deliver(packet: Dict) -> Tuple[int, List[int], List[int]]:
    """Inverse of build_send_deliver. Returns (recipient_ref, int_payload, or_payload)."""
    if packet["type"] != PKT_SEND_DELIVER:
        raise ValueError(f"expected SEND_DELIVER ({PKT_SEND_DELIVER:#x}), "
                         f"got {packet['type']:#x}")
    p = packet["payload"]
    if len(p) != 14:
        raise ValueError(f"SEND_DELIVER payload must be 14 words; got {len(p)}")
    recipient_ref = p[0] | (p[1] << 32)
    int_payload = list(p[2:6])
    or_payload = []
    for i in range(4):
        ref = p[6 + 2*i] | (p[7 + 2*i] << 32)
        or_payload.append(ref)
    return recipient_ref, int_payload, or_payload


# OBJ_READ_REQ / OBJ_READ_RESP / OBJ_WRITE_REQ / OBJ_WRITE_RESP
# (Volume IV §4.1). The home processor performs the validity, bounds,
# and capability checks itself; on failure the response carries a fault
# code in the low six bits of the `flags` byte instead of data.

# Response fault codes (Vol IV §4.1, low 6 bits of the response flags byte).
RESP_OK         = 0x00
RESP_STALE      = 0x01
RESP_BOUNDS     = 0x02
RESP_CAP        = 0x03
RESP_BUS_ERROR  = 0x04
RESP_FORWARDED  = 0x3F


def build_obj_read_req(src_pid: int, dst_pid: int, trans_id: int,
                       ref: int, offset: int, width: int) -> bytes:
    payload = [
        ref & 0xFFFFFFFF,
        (ref >> 32) & 0xFFFFFFFF,
        offset & 0xFFFFFFFF,
        width & 0xFFFFFFFF,
    ]
    return pack_packet(src_pid, dst_pid, PKT_OBJ_READ_REQ, 0, trans_id, payload)


def build_obj_read_resp(src_pid: int, dst_pid: int, trans_id: int,
                        flags: int, data: bytes) -> bytes:
    """Pad data to a 4-byte word boundary; pack words as the payload."""
    if flags == RESP_OK:
        pad = (-len(data)) % 4
        padded = data + bytes(pad)
        words = list(struct.unpack(f">{len(padded)//4}I", padded)) if padded else []
    else:
        words = []
    return pack_packet(src_pid, dst_pid, PKT_OBJ_READ_RESP, flags, trans_id, words)


def build_obj_write_req(src_pid: int, dst_pid: int, trans_id: int,
                        ref: int, offset: int, width: int, data: bytes) -> bytes:
    pad = (-len(data)) % 4
    padded = data + bytes(pad)
    data_words = list(struct.unpack(f">{len(padded)//4}I", padded)) if padded else []
    payload = [
        ref & 0xFFFFFFFF,
        (ref >> 32) & 0xFFFFFFFF,
        offset & 0xFFFFFFFF,
        width & 0xFFFFFFFF,
    ] + data_words
    return pack_packet(src_pid, dst_pid, PKT_OBJ_WRITE_REQ, 0, trans_id, payload)


def build_obj_write_resp(src_pid: int, dst_pid: int, trans_id: int,
                         flags: int) -> bytes:
    return pack_packet(src_pid, dst_pid, PKT_OBJ_WRITE_RESP, flags, trans_id, [])


# Phase 45d — remote Task primitive packets. Each REQ carries the target
# task ref (2 words, low-half first per Vol IV §4.1); the corresponding
# RESP carries an ERR_* status word plus any primitive-specific result
# words. flags is unused in these packet types.

def build_task_wait_req(src_pid: int, dst_pid: int, trans_id: int,
                        ref: int) -> bytes:
    payload = [ref & 0xFFFFFFFF, (ref >> 32) & 0xFFFFFFFF]
    return pack_packet(src_pid, dst_pid, PKT_TASK_WAIT_REQ, 0, trans_id, payload)


def build_task_wait_resp(src_pid: int, dst_pid: int, trans_id: int,
                         status: int, exit_code: int) -> bytes:
    """status = ERR_*; exit_code is meaningful only when status == ERR_OK."""
    payload = [status & 0xFFFFFFFF, exit_code & 0xFFFFFFFF]
    return pack_packet(src_pid, dst_pid, PKT_TASK_WAIT_RESP, 0, trans_id, payload)


def build_task_query_req(src_pid: int, dst_pid: int, trans_id: int,
                         ref: int) -> bytes:
    payload = [ref & 0xFFFFFFFF, (ref >> 32) & 0xFFFFFFFF]
    return pack_packet(src_pid, dst_pid, PKT_TASK_QUERY_REQ, 0, trans_id, payload)


def build_task_query_resp(src_pid: int, dst_pid: int, trans_id: int,
                          status: int, packed: int) -> bytes:
    """status = ERR_*; packed is the architectural Vol VI #0x008 packed
    state word (state | proc<<8 | exit_code<<16) — meaningful only when
    status == ERR_OK."""
    payload = [status & 0xFFFFFFFF, packed & 0xFFFFFFFF]
    return pack_packet(src_pid, dst_pid, PKT_TASK_QUERY_RESP, 0, trans_id, payload)


def build_task_kill_req(src_pid: int, dst_pid: int, trans_id: int,
                        ref: int, exit_code: int) -> bytes:
    payload = [ref & 0xFFFFFFFF, (ref >> 32) & 0xFFFFFFFF,
               exit_code & 0xFFFFFFFF]
    return pack_packet(src_pid, dst_pid, PKT_TASK_KILL_REQ, 0, trans_id, payload)


def build_task_kill_resp(src_pid: int, dst_pid: int, trans_id: int,
                         status: int) -> bytes:
    payload = [status & 0xFFFFFFFF]
    return pack_packet(src_pid, dst_pid, PKT_TASK_KILL_RESP, 0, trans_id, payload)


# Map response-flag fault codes to architectural trap causes for the
# issuer to raise upon receiving a non-OK response.
RESP_FLAG_TO_CAUSE = {
    RESP_STALE:     CAUSE_STALE_REF,
    RESP_BOUNDS:    CAUSE_BOUNDS,
    RESP_CAP:       CAUSE_CAP_VIOLATION,
    RESP_BUS_ERROR: CAUSE_BUS_ERROR_D,
}


# ---------------------------------------------------------------------------
# Pending SEND message (host-side parsed form of a SEND_DELIVER packet)
# ---------------------------------------------------------------------------

@dataclass
class PendingSend:
    recipient_ref: int                   # full 64-bit ref of the target object
    int_payload: List[int]               # 4 ints (R4..R7 of issuer at SEND time)
    or_payload: List[int]                # 4 OR refs (O1..O4 of issuer at SEND time)
    src_pid: int                         # which CPU issued this SEND
    trans_id: int = 0                    # per-source transaction id

    def to_wire(self, dst_pid: int) -> bytes:
        return build_send_deliver(self.src_pid, dst_pid, self.trans_id,
                                  self.recipient_ref, self.int_payload,
                                  self.or_payload)

    @classmethod
    def from_wire(cls, data: bytes) -> 'PendingSend':
        pkt = unpack_packet(data)
        recipient_ref, int_payload, or_payload = parse_send_deliver(pkt)
        return cls(recipient_ref=recipient_ref,
                   int_payload=int_payload,
                   or_payload=or_payload,
                   src_pid=pkt["src_pid"],
                   trans_id=pkt["trans_id"])


# ---------------------------------------------------------------------------
# Crossbar interface and in-process implementation
# ---------------------------------------------------------------------------
#
# Everything that crosses between CPUs (and, in a future revision, between
# CPUs and devices) goes through a Crossbar. The Crossbar owns nothing
# semantic about the protocol — it inspects each packet's `dst_pid` field
# and hands the packet off to that destination's Port. A Port is anything
# that can receive packets: today, only CPUs implement Port; tomorrow,
# device processes will too.
#
# The InProcessCrossbar implementation routes by direct method dispatch
# inside one Python process. A SocketCrossbar (next phase) will route
# bytes over a UNIX domain socket to peer CPU processes.

class Port:
    """A participant on the crossbar. Any object that can receive packet
    bytes addressed to a particular pid is a Port."""
    def receive_packet(self, packet: bytes) -> None:
        raise NotImplementedError


class Crossbar:
    """Interface for the crossbar interconnect.

    `send_packet(packet)` routes one wire-format packet to the Port
    registered for its `dst_pid` field. Implementations may be
    in-process, over a socket, or over a real fabric — the rest of the
    simulator only sees this method.

    `poll_incoming()` is called once per scheduler tick; it lets
    transport-bearing implementations (e.g., SocketCrossbar) drain any
    bytes from their wire and deliver complete packets into the local
    Port. The default in-process implementation does nothing."""
    def send_packet(self, packet: bytes) -> None:
        raise NotImplementedError

    def attach_port(self, pid: int, port: Port) -> None:
        raise NotImplementedError

    def poll_incoming(self) -> bool:
        return False

    def close(self) -> None:
        pass


class SocketCrossbar(Crossbar):
    """Crossbar implementation that talks to an external `oriscbar`
    process over a UNIX domain socket. Wire framing and handshake are
    documented in oriscbar's module docstring. The simulator runs in
    single-CPU mode in this configuration; the external crossbar
    routes between many such simorisc instances and any device
    processes."""
    HELLO_MAGIC  = 0xC0FFEEAA
    HELLO_OK     = 0x00000000

    def __init__(self, sock_path: str, my_pid: int,
                 trace_enabled: bool = False):
        import socket
        self.sock_path = sock_path
        self.my_pid = my_pid
        self.trace_enabled = trace_enabled
        self.local_port: Optional[Port] = None
        self.recv_buf = bytearray()
        self.connected = True
        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        # Brief retry loop in case the launcher is still bringing
        # oriscbar up.
        deadline = time.time() + 5.0
        while True:
            try:
                self.sock.connect(sock_path)
                break
            except (FileNotFoundError, ConnectionRefusedError) as e:
                if time.time() >= deadline:
                    raise SystemExit(
                        f"simorisc: could not connect to crossbar at "
                        f"{sock_path}: {e}")
                time.sleep(0.05)
        # Handshake.
        self.sock.sendall(struct.pack(">II", self.HELLO_MAGIC, my_pid))
        reply = self._recv_exact(8)
        magic, status = struct.unpack(">II", reply)
        if magic != self.HELLO_MAGIC or status != self.HELLO_OK:
            raise SystemExit(
                f"simorisc: crossbar handshake failed "
                f"(magic={magic:#x}, status={status:#x})")
        self.sock.setblocking(False)

    def _recv_exact(self, n: int) -> bytes:
        out = bytearray()
        while len(out) < n:
            chunk = self.sock.recv(n - len(out))
            if not chunk:
                raise SystemExit("simorisc: crossbar closed during handshake")
            out.extend(chunk)
        return bytes(out)

    def attach_port(self, pid: int, port: Port) -> None:
        if pid != self.my_pid:
            raise ValueError(f"SocketCrossbar can only host pid={self.my_pid}, "
                             f"not pid={pid}")
        self.local_port = port

    def send_packet(self, packet: bytes) -> None:
        try:
            self.sock.sendall(struct.pack(">I", len(packet)) + packet)
        except OSError as e:
            print(f"simorisc: socket send failed: {e}", file=sys.stderr)
            return
        if self.trace_enabled:
            self._trace_outgoing(packet)

    def poll_incoming(self) -> bool:
        worked = False
        while True:
            try:
                chunk = self.sock.recv(65536)
            except (BlockingIOError, InterruptedError):
                break
            except OSError:
                self.connected = False
                break
            if not chunk:
                self.connected = False
                break
            self.recv_buf.extend(chunk)
            worked = True
        while len(self.recv_buf) >= 4:
            (length,) = struct.unpack(">I", bytes(self.recv_buf[:4]))
            if len(self.recv_buf) < 4 + length:
                break
            packet = bytes(self.recv_buf[4:4 + length])
            del self.recv_buf[:4 + length]
            if self.trace_enabled:
                self._trace_incoming(packet)
            if self.local_port is not None:
                self.local_port.receive_packet(packet)
            worked = True
        return worked

    def _trace_outgoing(self, packet: bytes) -> None:
        try:
            p = unpack_packet(packet)
            print(f"  ; CROSSBAR(socket) tx -> CPU{p['dst_pid']} "
                  f"type=0x{p['type']:02x} bytes={packet.hex()}", file=sys.stderr)
        except ValueError:
            print(f"  ; CROSSBAR(socket) tx malformed bytes={packet.hex()}",
                  file=sys.stderr)

    def _trace_incoming(self, packet: bytes) -> None:
        try:
            p = unpack_packet(packet)
            print(f"  ; CROSSBAR(socket) rx <- CPU{p['src_pid']} "
                  f"type=0x{p['type']:02x} bytes={packet.hex()}", file=sys.stderr)
        except ValueError:
            print(f"  ; CROSSBAR(socket) rx malformed bytes={packet.hex()}",
                  file=sys.stderr)

    def close(self) -> None:
        try:
            self.sock.close()
        except OSError:
            pass


class InProcessCrossbar(Crossbar):
    """Default implementation: an in-memory routing table. Each call to
    `send_packet` immediately delivers to the destination Port's
    `receive_packet`. No latency model, no flow control, no real link
    arbitration — just direct dispatch sufficient for ISA-level
    simulation."""
    def __init__(self, trace_enabled: bool = False):
        self.ports: Dict[int, Port] = {}
        self.trace_enabled = trace_enabled

    def attach_port(self, pid: int, port: Port) -> None:
        self.ports[pid] = port

    def send_packet(self, packet: bytes) -> None:
        try:
            pkt = unpack_packet(packet)
        except ValueError as e:
            if self.trace_enabled:
                print(f"  ; CROSSBAR drop (malformed): {e}", file=sys.stderr)
            return
        dst = pkt["dst_pid"]
        if dst not in self.ports:
            if self.trace_enabled:
                print(f"  ; CROSSBAR drop: dst CPU{dst} not connected",
                      file=sys.stderr)
            return
        if self.trace_enabled:
            self._trace(packet, pkt)
        self.ports[dst].receive_packet(packet)

    def _trace(self, packet: bytes, pkt: Dict) -> None:
        type_name = {
            PKT_OBJ_READ_REQ:    "OBJ_READ_REQ",
            PKT_OBJ_READ_RESP:   "OBJ_READ_RESP",
            PKT_OBJ_WRITE_REQ:   "OBJ_WRITE_REQ",
            PKT_OBJ_WRITE_RESP:  "OBJ_WRITE_RESP",
            PKT_SEND_DELIVER:    "SEND_DELIVER",
            PKT_TASK_WAIT_REQ:   "TASK_WAIT_REQ",
            PKT_TASK_WAIT_RESP:  "TASK_WAIT_RESP",
            PKT_TASK_QUERY_REQ:  "TASK_QUERY_REQ",
            PKT_TASK_QUERY_RESP: "TASK_QUERY_RESP",
            PKT_TASK_KILL_REQ:   "TASK_KILL_REQ",
            PKT_TASK_KILL_RESP:  "TASK_KILL_RESP",
            PKT_HOST_INPUT:      "HOST_INPUT",
        }.get(pkt["type"], f"type=0x{pkt['type']:02x}")
        print(f"  ; CROSSBAR CPU{pkt['src_pid']} -> CPU{pkt['dst_pid']} "
              f"{type_name} trans={pkt['trans_id']} len={len(pkt['payload'])}w "
              f"bytes={packet.hex()}", file=sys.stderr)


# ---------------------------------------------------------------------------
# CPU state (per-processor)
# ---------------------------------------------------------------------------

class CPU(Port):
    def __init__(self, pid: int = 0, system: Optional['System'] = None):
        self.pid      = pid
        self.system   = system

        self.gpr      = [0] * 32          # R0..R31, R0 hardwired zero
        self.opr      = [0] * 16          # O0..O15, O0 hardwired null
        self.hi       = 0
        self.lo       = 0
        self.pc       = 0
        self.next_pc  = 0
        self.cycles   = 0

        # Object table — local to this processor; remote references are
        # routed through System.lookup_remote_descriptor().
        self.descriptors: List[Optional[Descriptor]] = [None]  # idx 0 reserved
        self.next_obj_idx = 1
        # Reusable freed-slot list (FIFO); generation already incremented.
        self.free_indices: List[int] = []

        # Page-table substitute: VA range -> (descriptor index, base offset, prot).
        self.mappings: List[Tuple[int,int,int,int,int]] = []

        # Multi-CPU bookkeeping.
        self.active = False                  # True when a task is running
        self.exit_code: Optional[int] = None # set by TaskExit
        # inbox holds raw SEND_DELIVER packet bytes per Volume IV. The
        # crossbar deposits packets here; dispatch_handler pops bytes,
        # parses to a PendingSend, and runs the registered handler.
        # Per-object queues installed by ReceiveQueueAttach hold packet
        # bytes too (in Descriptor.queue).
        self.inbox: List[bytes] = []
        # Wire-level request/response queues for OBJ_READ/WRITE traffic.
        # `requests` holds OBJ_READ_REQ / OBJ_WRITE_REQ packets that this
        # CPU is the home of; the scheduler drains them autonomously each
        # tick (the CPU's "memory controller"). `responses` holds the
        # corresponding *_RESP packets addressed to this CPU as the
        # original issuer; a blocked CPU watches these for matching
        # trans_ids.
        self.requests:  List[bytes] = []
        self.responses: List[bytes] = []
        self.boot_state: Optional[Dict] = None  # snapshot used to relaunch handler tasks
        self.blocked_on: Optional[BlockedSignal] = None  # poll/response wait state
        self.next_trans_id = 0               # per-CPU SEND/OL/OS transaction id counter
        # Set to True by primitives that have already moved PC into the
        # right place (InstallProgram, TaskYield, TaskExit-with-successor)
        # so the CALL dispatch site won't bump it past the redirect.
        self._call_redirected_pc = False

        # Preemption plumbing (Phase 35). `in_trap_handler` is True
        # between deliver_trap and the next ERET; while it's set,
        # TaskYield-from-the-handler doesn't context-switch
        # immediately (which would lose the trap's saved state).
        # Instead it sets `yield_pending`, and ERET honors it by
        # picking the next runnable task before resuming user mode.
        # The trapping task's user state was checkpointed into its
        # Task struct on trap delivery so the swap is clean.
        self.in_trap_handler = False
        self.yield_pending   = False

        # Pending deferred frees (Volume VI primitive #0x107,
        # ObjFreeDeferred). Each entry is (deadline_seconds, idx);
        # entries fire in run() once `time.time() >= deadline_seconds`,
        # at which point the descriptor is freed normally. The
        # descriptor stays live (answers OBJ_READ_REQs) while waiting,
        # which is the whole point — gives an in-flight async SEND's
        # receiver time to finish reading the bytes before they
        # disappear. Same idiom as RESET_DRAIN_SECONDS for chunkboot.
        self.deferred_frees: List[Tuple[float, int]] = []

        # Task scheduling state. `current_task` is what's running on this
        # CPU right now; `tasks` is every Task ever created here keyed by
        # its descriptor index; `runnable` is the round-robin queue of
        # ready-to-run tasks not currently running. Populated by
        # init_cpu (bootstrap task) and TaskCreate.
        self.current_task: Optional['Task'] = None
        self.tasks:    Dict[int, 'Task'] = {}
        self.runnable: List['Task'] = []

        # Privilege state (Volume II Section 13). Mode defaults to
        # supervisor — this preserves the pre-privilege-modes behaviour
        # of every existing program: shells, the chunkboot loader,
        # everything that calls MapObject / InstallHandler / InstallProgram
        # boots as supervisor and keeps working. main() honours --mode to
        # override per-program (and per-CPU on reset).
        self.mode = MODE_SUPERVISOR
        # ERET destination, written by trap delivery (deliver_trap) and
        # consumed by ERET. saved_pc is also exposed as the EPC control
        # register; saved_mode lives in STATUS bits [3:2] when read out.
        self.saved_mode = MODE_SUPERVISOR
        self.saved_pc   = 0

        # Architecturally visible control registers populated by trap
        # delivery (Volume II Section 14). VECBASE is supplied by
        # firmware via SCTRL; CAUSE / BADVADDR are written when a trap
        # is delivered to a vector and read by the handler via LCTRL.
        self.vecbase     = 0
        self.cause_reg   = 0
        self.badvaddr_reg = 0

        # Supervisor-installable trap handlers (Volume VI primitive
        # #0x520, InstallTrapHandler). Per-CPU map cause → handler VA;
        # consulted by deliver_trap before falling back to VECBASE.
        # Handlers run in supervisor mode. The handler VA may not be
        # mapped in the trapping task's address space (e.g., a shell
        # registers a handler in its own code; a guest task it spawned
        # later traps), so deliver_trap swaps in the mappings the
        # supervisor had at install time, then load_task_to_cpu on
        # ERET restores the trapping task's mappings.
        self.trap_handlers: Dict[int, int] = {}
        self.trap_handler_mappings: Dict[int, List[Tuple[int,int,int,int,int]]] = {}

        # Timer interrupt state (Volume V Section 2.10 — COMPARE).
        # `compare_reg` is the cycle-counter target; when cycles >=
        # compare and STATUS.IE is set, the simulator raises an
        # external-interrupt trap once and clears IE so the handler
        # runs without immediately re-firing. Setting compare_reg=0
        # disables the timer (the default).
        self.compare_reg = 0
        self.status_ie   = False    # bit 4 of STATUS

        # Trace control.
        self.trace_enabled = False

    # ---- Port interface -----------------------------------------------------

    def receive_packet(self, packet: bytes) -> None:
        """Crossbar entry point. Decode the packet's type and route it to
        the appropriate per-CPU queue: SEND_DELIVER goes to a
        descriptor's receive queue if attached, else to the inbox; object
        memory requests/responses go to the requests/responses queues."""
        try:
            pkt = unpack_packet(packet)
        except ValueError:
            return
        t = pkt["type"]
        if t == PKT_SEND_DELIVER:
            try:
                recipient_ref, _, _ = parse_send_deliver(pkt)
            except ValueError:
                return
            idx = ref_index(recipient_ref)
            if 0 < idx < len(self.descriptors) and \
                    self.descriptors[idx] is not None and \
                    self.descriptors[idx].queue is not None:
                desc = self.descriptors[idx]
                if len(desc.queue) >= desc.queue_max_depth:
                    return  # full; drop
                desc.queue.append(packet)
            else:
                self.inbox.append(packet)
        elif t in (PKT_OBJ_READ_REQ, PKT_OBJ_WRITE_REQ,
                   PKT_TASK_WAIT_REQ, PKT_TASK_QUERY_REQ, PKT_TASK_KILL_REQ):
            # All home-side request packets land in `requests` and get
            # serviced by _process_requests on the home CPU's tick.
            self.requests.append(packet)
        elif t in (PKT_OBJ_READ_RESP, PKT_OBJ_WRITE_RESP,
                   PKT_TASK_WAIT_RESP, PKT_TASK_QUERY_RESP, PKT_TASK_KILL_RESP):
            # All issuer-side response packets land in `responses` and
            # get matched against cpu.blocked_on (or task.blocked_on for
            # parked tasks) by trans_id.
            self.responses.append(packet)
        elif t == PKT_HOST_INPUT:
            # Headless host-input injection (Phase 60 follow-up): a test
            # harness delivers a keyboard/pointer event into this CPU's
            # local TAG_INPUT_SINK, the same path the Tk display worker
            # uses for live input.  payload = [kind, w0, w1, w2, w3].
            p = pkt["payload"]
            if len(p) >= 5:
                self.enqueue_input_sink(p[0] & 0xFF, [p[1], p[2], p[3], p[4]])
        # Other packet types currently dropped silently (e.g., DESC_*,
        # LINK_*); future revisions may dispatch them here too.

    def enqueue_input_sink(self, kind: int, int_payload: List[int]) -> None:
        """Append a host-input SEND_DELIVER to this CPU's registered
        TAG_INPUT_SINK queue for `kind` (0=keyboard, 1=pointer), if any.

        Shared by the Tk display worker (live keystrokes/mouse, via
        TkDisplayWorker._enqueue_sink) and the PKT_HOST_INPUT crossbar
        path (headless test injection).  Both deliver a byte-identical
        event into the sink — the WM can't tell a real keypress from an
        injected one.  No-op if no sink is registered or its queue is
        full (matches the Tk worker's silent-drop behaviour)."""
        sinks = getattr(self, "input_sinks", None)
        if sinks is None:
            return
        idx = sinks.get(kind)
        if idx is None:
            return
        if idx >= len(self.descriptors) or self.descriptors[idx] is None:
            return
        desc = self.descriptors[idx]
        if not desc.live or desc.queue is None:
            return
        if len(desc.queue) >= desc.queue_max_depth:
            return  # silent drop; queue full
        recipient_ref = make_ref(generation=desc.generation,
                                 home=self.pid, index=idx,
                                 caps=desc.max_caps)
        pkt = build_send_deliver(
            src_pid=self.pid, dst_pid=self.pid, trans_id=0,
            recipient_ref=recipient_ref,
            int_payload=int_payload,
            or_payload=[recipient_ref, 0, 0, 0],
        )
        desc.queue.append(pkt)

    # ---- GPR/OR helpers -----------------------------------------------------

    def set_gpr(self, idx: int, val: int) -> None:
        if idx == 0:
            return
        self.gpr[idx] = val & 0xFFFFFFFF

    def get_gpr(self, idx: int) -> int:
        return self.gpr[idx] & 0xFFFFFFFF

    def get_sgpr(self, idx: int) -> int:
        return sext32(self.gpr[idx] & 0xFFFFFFFF)

    def set_opr(self, idx: int, val: int) -> None:
        if idx == 0:
            return  # O0 hardwired null
        self.opr[idx] = val & 0xFFFFFFFFFFFFFFFF

    def get_opr(self, idx: int) -> int:
        return self.opr[idx] & 0xFFFFFFFFFFFFFFFF

    # ---- privileged control registers (Volume V Section 2.10) ---------------

    def ctrl_read(self, idx: int) -> int:
        """LCTRL fetch. The simulator backs the architecturally visible
        subset; firmware-only registers controlling the (absent) TLB,
        object table, and crossbar route are read-as-zero.

        STATUS layout (simulator-defined; spec leaves bit assignment to
        Volume V): bits [1:0] = current mode, bits [3:2] = saved mode,
        bit 4 = IE (interrupt enable, gates the timer-interrupt path)."""
        if   idx == CTRL_STATUS:
            return ((self.mode & 0x3) |
                    ((self.saved_mode & 0x3) << 2) |
                    ((1 if self.status_ie else 0) << 4))
        elif idx == CTRL_CAUSE:    return self.cause_reg & 0xFFFFFFFF
        elif idx == CTRL_EPC:      return self.saved_pc & 0xFFFFFFFF
        elif idx == CTRL_BADVADDR: return self.badvaddr_reg & 0xFFFFFFFF
        elif idx == CTRL_CONTEXT:  return 0
        elif idx == CTRL_COUNT:    return self.cycles & 0xFFFFFFFF
        elif idx == CTRL_COMPARE:  return self.compare_reg & 0xFFFFFFFF
        elif idx == CTRL_PROCID:   return self.pid & 0xFFFFFFFF
        elif idx == CTRL_VECBASE:  return self.vecbase & 0xFFFFFFFF
        return 0

    def ctrl_write(self, idx: int, val: int) -> None:
        """SCTRL store. PROCID is read-only (writes silently ignored, per
        Volume V). STATUS writes update both the current mode bits
        (immediate effect — how supervisor code self-demotes) and the
        saved-mode bits (consumed by the next ERET — how supervisor
        sets up an ERET-into-user-mode hand-off after preparing EPC)."""
        v = val & 0xFFFFFFFF
        if   idx == CTRL_STATUS:
            self.mode = v & 0x3
            self.saved_mode = (v >> 2) & 0x3
            self.status_ie = bool((v >> 4) & 0x1)
        elif idx == CTRL_CAUSE:    self.cause_reg = v
        elif idx == CTRL_EPC:      self.saved_pc = v
        elif idx == CTRL_BADVADDR: self.badvaddr_reg = v
        elif idx == CTRL_COMPARE:  self.compare_reg = v
        elif idx == CTRL_VECBASE:  self.vecbase = v
        # CONTEXT / COUNT: writable in spec but no architectural effect
        # in this simulator yet. PROCID and the remaining firmware-only
        # registers: ignore.

    # ---- object table -------------------------------------------------------

    def alloc_object(self, size: int, type_tag: int, max_caps: int,
                     init_bytes: Optional[bytes] = None,
                     objstore: bool = False) -> int:
        """Allocate an object on this CPU; return its reference (caps =
        max_caps; home = self.pid). When `objstore` is True the descriptor
        is flagged as OR-typed: integer OL/OS trap on it, and only
        OREFLD/OREFST can read or write its storage."""
        storage = bytearray(size)
        if init_bytes is not None:
            storage[:len(init_bytes)] = init_bytes
        if self.free_indices:
            idx = self.free_indices.pop(0)
            # Carry the bumped generation forward.
            prior_gen = self.descriptors[idx].generation if self.descriptors[idx] else 1
            desc = Descriptor(storage=storage, length=size,
                              generation=prior_gen, type_tag=type_tag,
                              max_caps=max_caps, objstore=objstore)
            self.descriptors[idx] = desc
        else:
            desc = Descriptor(storage=storage, length=size,
                              generation=1, type_tag=type_tag,
                              max_caps=max_caps, objstore=objstore)
            idx = self.next_obj_idx
            self.next_obj_idx += 1
            self.descriptors.append(desc)
        return make_ref(generation=desc.generation, home=self.pid,
                        index=idx, caps=max_caps)

    def free_object(self, idx: int) -> None:
        """Bump the generation and mark the slot freed; callers are
        responsible for capability checks."""
        d = self.descriptors[idx]
        if d is None:
            return
        d.generation = (d.generation + 1) & 0xFFFF
        if d.generation == 0:
            d.generation = 1   # avoid the all-zero-fields-=-null collision
        d.live = False
        # Keep slot in self.descriptors so the bumped generation persists;
        # mark it freed via .live = False, and recycle through free_indices.
        self.free_indices.append(idx)

    def map_object(self, ref: int, va: int, offset: int, length: int,
                   prot: int) -> None:
        """Install a VA->object mapping for general-register loads/stores."""
        idx = ref_index(ref)
        self.mappings.append((va, va + length, idx, offset, prot))

    def lookup_va(self, va: int, width: int, want_prot: int,
                  is_fetch: bool, faulting_pc: int) -> Tuple[Descriptor, int]:
        """Translate a virtual address to (local descriptor, object_offset)."""
        if width in (2, 4) and (va & (width - 1)):
            raise Trap(
                CAUSE_ADDR_MISALIGN_I if is_fetch else CAUSE_ADDR_MISALIGN_D,
                faulting_pc,
                f"VA 0x{va:08x} not aligned to {width}")
        for (lo, hi, idx, base, prot) in self.mappings:
            if lo <= va < hi and va + width <= hi:
                if (prot & want_prot) != want_prot:
                    raise Trap(CAUSE_PAGE_PERMISSION, faulting_pc,
                               f"VA 0x{va:08x} prot {prot:#x} lacks {want_prot:#x}")
                return self.descriptors[idx], base + (va - lo)
        raise Trap(
            CAUSE_TLB_MISS_I if is_fetch else CAUSE_TLB_MISS_D,
            faulting_pc,
            f"unmapped VA 0x{va:08x}")

    # ---- memory access -------------------------------------------------------

    def fetch_instr(self, pc: int) -> int:
        desc, off = self.lookup_va(pc, 4, CAP_X, is_fetch=True, faulting_pc=pc)
        return struct.unpack(">I", bytes(desc.storage[off:off+4]))[0]

    def load_gpr_mem(self, va: int, width: int, signed: bool,
                     faulting_pc: int) -> int:
        desc, off = self.lookup_va(va, width, CAP_R, is_fetch=False,
                                   faulting_pc=faulting_pc)
        raw = bytes(desc.storage[off:off+width])
        if   width == 1: val = raw[0]
        elif width == 2: val = struct.unpack(">H", raw)[0]
        elif width == 4: val = struct.unpack(">I", raw)[0]
        else: raise AssertionError("width")
        if signed:
            sign = 1 << (width * 8 - 1)
            if val & sign:
                val -= (1 << (width * 8))
            val &= 0xFFFFFFFF
        return val

    def store_gpr_mem(self, va: int, width: int, val: int,
                      faulting_pc: int) -> None:
        desc, off = self.lookup_va(va, width, CAP_W, is_fetch=False,
                                   faulting_pc=faulting_pc)
        if   width == 1: desc.storage[off] = val & 0xFF
        elif width == 2: desc.storage[off:off+2] = struct.pack(">H", val & 0xFFFF)
        elif width == 4: desc.storage[off:off+4] = struct.pack(">I", val & 0xFFFFFFFF)
        else: raise AssertionError("width")

    # ---- object register access ---------------------------------------------

    def deref_obj(self, oreg_idx: int, offset: int, width: int,
                  required_cap: int, faulting_pc: int,
                  *, expect_objstore: bool = False) -> Tuple[Descriptor, int, int]:
        """Validate (null/stale/bounds/cap/storage-type) an OL/OS or
        OREFLD/OREFST reference and return (descriptor, byte offset in
        storage, home_pid). When `expect_objstore` is True (OREFLD/OREFST
        path) the descriptor's `objstore` flag must be set; when False
        (integer OL/OS path) the flag must be clear. A mismatch traps
        capability-violation."""
        ref = self.get_opr(oreg_idx)
        if ref == 0:
            raise Trap(CAUSE_NULL_DEREF, faulting_pc,
                       f"null O{oreg_idx} dereference")

        # Caps check uses the issuing reference's caps field; the home's
        # max_caps is the upper bound but not checked here (it was checked
        # at allocation/derivation).
        if (ref_caps(ref) & required_cap) != required_cap:
            raise Trap(CAUSE_CAP_VIOLATION, faulting_pc,
                       f"O{oreg_idx} caps {ref_caps(ref):#x} lacks {required_cap:#x}")

        home = ref_home(ref)
        if self.system is None or home == self.pid:
            descriptors = self.descriptors
        else:
            target = self.system.cpus[home]
            descriptors = target.descriptors

        idx = ref_index(ref)
        if idx >= len(descriptors) or descriptors[idx] is None:
            raise Trap(CAUSE_STALE_REF, faulting_pc,
                       f"O{oreg_idx} index {idx} out of range on CPU {home}")
        desc = descriptors[idx]
        if not desc.live or desc.generation != ref_generation(ref):
            raise Trap(CAUSE_STALE_REF, faulting_pc,
                       f"O{oreg_idx} generation {ref_generation(ref)} != "
                       f"descriptor {desc.generation}")

        if desc.objstore != expect_objstore:
            kind = "OR-typed (OBJSTORE)" if desc.objstore else "byte-typed"
            wanted = "OBJSTORE" if expect_objstore else "byte-typed"
            raise Trap(CAUSE_CAP_VIOLATION, faulting_pc,
                       f"O{oreg_idx} storage is {kind}; access requires {wanted}")

        if offset < 0 or offset + width > desc.length or width <= 0:
            raise Trap(CAUSE_BOUNDS, faulting_pc,
                       f"O{oreg_idx} offset {offset} width {width} "
                       f"outside [0,{desc.length})")
        if width in (2, 4, 8) and (offset & (width - 1)):
            raise Trap(CAUSE_ADDR_MISALIGN_D, faulting_pc,
                       f"O{oreg_idx} offset {offset} not aligned to {width}")
        return desc, offset, home

    def inspect_obj(self, oreg_idx: int, faulting_pc: int) -> Tuple[Descriptor, int]:
        """Look up an object's descriptor for the inspection ops (OLEN, OTAG,
        OHOME, OCAP). Only checks null + stale, no caps or bounds. Returns
        (descriptor, home_pid). The OHOME caller wants the home directly
        (stored already in the ref); other callers just want the descriptor."""
        ref = self.get_opr(oreg_idx)
        if ref == 0:
            raise Trap(CAUSE_NULL_DEREF, faulting_pc, f"O{oreg_idx} null on inspect")
        home = ref_home(ref)
        if self.system is None or home == self.pid:
            descriptors = self.descriptors
        else:
            descriptors = self.system.cpus[home].descriptors
        idx = ref_index(ref)
        if idx >= len(descriptors) or descriptors[idx] is None:
            raise Trap(CAUSE_STALE_REF, faulting_pc, f"O{oreg_idx} stale on inspect")
        desc = descriptors[idx]
        if not desc.live or desc.generation != ref_generation(ref):
            raise Trap(CAUSE_STALE_REF, faulting_pc, f"O{oreg_idx} stale on inspect")
        return desc, home


# ---------------------------------------------------------------------------
# System (the crossbar + N CPUs)
# ---------------------------------------------------------------------------

class System:
    def __init__(self, n_cpus: int):
        self.cpus = [CPU(pid=i, system=self) for i in range(n_cpus)]
        self.n_cpus = n_cpus
        self.trace_enabled = False
        self.serve_mode = False    # if True, don't exit on idle (socket-server mode)
        self.crossbar: Crossbar = InProcessCrossbar()
        for cpu in self.cpus:
            self.crossbar.attach_port(cpu.pid, cpu)
        # Wall-clock zero-point for the TimeNow firmware primitive
        # (Vol VI #0x400). TimeNow returns microseconds since this
        # moment, so the simulator's sense of time matches the
        # outside world rather than a fictional clock. Captured here
        # so all CPUs in a multi-CPU System see the same epoch.
        self.boot_time = time.time()

    # ---- inter-CPU SEND queue ----------------------------------------------

    def queue_send(self, msg: PendingSend) -> None:
        """Serialize a PendingSend to a wire-format SEND_DELIVER packet and
        push it onto the crossbar. Routing (inbox vs descriptor queue) is
        the receiving CPU's responsibility — see CPU.receive_packet. In
        socket mode the local System has only one CPU; the crossbar
        validates that the destination is connected and drops otherwise."""
        home = ref_home(msg.recipient_ref)
        packet = msg.to_wire(dst_pid=home)
        self.crossbar.send_packet(packet)

    # ---- handler dispatch --------------------------------------------------

    def dispatch_handler(self, cpu: CPU) -> bool:
        """If `cpu` is idle and has a pending SEND, dispatch its handler as a
        fresh task. Returns True iff a handler was launched."""
        if cpu.active or not cpu.inbox:
            return False
        packet = cpu.inbox.pop(0)
        try:
            msg = PendingSend.from_wire(packet)
        except ValueError as e:
            if self.trace_enabled:
                print(f"  ; CPU{cpu.pid}: malformed inbox packet ({e}); dropped",
                      file=sys.stderr)
            return False
        idx = ref_index(msg.recipient_ref)
        if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
            if self.trace_enabled:
                print(f"  ; CPU{cpu.pid}: SEND_DELIVER for absent obj idx={idx} dropped",
                      file=sys.stderr)
            return False
        desc = cpu.descriptors[idx]
        if not desc.live or desc.generation != ref_generation(msg.recipient_ref):
            if self.trace_enabled:
                print(f"  ; CPU{cpu.pid}: SEND_DELIVER stale (gen mismatch) dropped",
                      file=sys.stderr)
            return False
        if desc.send_handler_ref == 0:
            if self.trace_enabled:
                print(f"  ; CPU{cpu.pid}: SEND_DELIVER to obj idx={idx} dropped (no handler)",
                      file=sys.stderr)
            return False

        # Restore the boot register snapshot, then overlay the handler-specific
        # registers per Volume III Section 7.2.
        snap = cpu.boot_state
        cpu.gpr = list(snap["gpr"])
        cpu.opr = list(snap["opr"])
        cpu.hi  = 0
        cpu.lo  = 0

        # O1 = fresh full-caps self-reference (firmware constructs).
        full_self = make_ref(generation=desc.generation, home=cpu.pid,
                             index=idx, caps=desc.max_caps)
        cpu.set_opr(1, full_self)
        # O2..O4 = first three OR payload args from the wire.
        for i, oref in enumerate(msg.or_payload[:3]):
            cpu.set_opr(2 + i, oref)
        # R4..R7 = integer payload from the wire.
        for i, val in enumerate(msg.int_payload[:4]):
            cpu.set_gpr(4 + i, val)

        # PC = handler VA computed at install time from the handler code
        # object's executable mapping. Loadable modules mapped at any VA
        # work transparently here; InstallHandler is responsible for
        # rejecting handlers whose offset is not in any executable mapping.
        cpu.pc = desc.send_handler_va & 0xFFFFFFFF
        cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
        cpu.active = True

        if self.trace_enabled:
            print(f"  ; CPU{cpu.pid}: dispatched handler at PC=0x{cpu.pc:08x} "
                  f"for obj idx={idx}",
                  file=sys.stderr)
        return True

    # ---- autonomous request handling ---------------------------------------

    def _process_requests(self, cpu: CPU) -> None:
        """Drain any OBJ_READ_REQ / OBJ_WRITE_REQ packets in this CPU's
        request queue, perform the bounds/cap/generation checks against
        the local descriptor table, and emit corresponding *_RESP packets
        to the originating CPU. This is the firmware/memory-controller
        contribution per Volume IV §4.1."""
        while cpu.requests:
            packet = cpu.requests.pop(0)
            try:
                pkt = unpack_packet(packet)
            except ValueError as e:
                if self.trace_enabled:
                    print(f"  ; CPU{cpu.pid}: malformed request packet ({e})",
                          file=sys.stderr)
                continue
            if pkt["type"] == PKT_OBJ_READ_REQ:
                self._handle_obj_read_req(cpu, pkt)
            elif pkt["type"] == PKT_OBJ_WRITE_REQ:
                self._handle_obj_write_req(cpu, pkt)
            elif pkt["type"] == PKT_TASK_WAIT_REQ:
                self._handle_task_wait_req(cpu, pkt)
            elif pkt["type"] == PKT_TASK_QUERY_REQ:
                self._handle_task_query_req(cpu, pkt)
            elif pkt["type"] == PKT_TASK_KILL_REQ:
                self._handle_task_kill_req(cpu, pkt)

    def _validate_at_home(self, cpu: CPU, ref: int, offset: int, width: int,
                          required_cap: int, expect_objstore: bool = False
                          ) -> Tuple[Optional[Descriptor], int]:
        """Run the home-side validation (Vol IV §4.1) and return
        (descriptor or None, fault_code). On fault `descriptor` is None
        and the caller responds with the fault code in flags."""
        idx = ref_index(ref)
        if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
            return None, RESP_STALE
        desc = cpu.descriptors[idx]
        if not desc.live or desc.generation != ref_generation(ref):
            return None, RESP_STALE
        if (ref_caps(ref) & required_cap) != required_cap:
            return None, RESP_CAP
        if desc.objstore != expect_objstore:
            return None, RESP_CAP
        if offset < 0 or offset + width > desc.length or width <= 0:
            return None, RESP_BOUNDS
        # Don't enforce offset/width alignment here: this validator is
        # called from _handle_obj_read_req / _handle_obj_write_req, which
        # serve arbitrary byte-stream device reads (e.g. oriscterm
        # fetching a 2-byte console-write payload at an odd offset).
        # CPU-side OL/OS instructions enforce VA alignment in
        # lookup_va, before they even issue an OBJ_READ_REQ, so adding
        # an alignment check here would only break legitimate device
        # traffic.
        return desc, RESP_OK

    def _handle_obj_read_req(self, cpu: CPU, pkt: Dict) -> None:
        p = pkt["payload"]
        ref = p[0] | (p[1] << 32)
        offset = p[2] if p[2] < 0x80000000 else p[2] - 0x100000000  # signed
        width = p[3]
        issuer = pkt["src_pid"]
        desc, fault = self._validate_at_home(cpu, ref, offset, width, CAP_R)
        if fault != RESP_OK:
            response = build_obj_read_resp(cpu.pid, issuer, pkt["trans_id"],
                                           fault, b'')
        else:
            data = bytes(desc.storage[offset:offset+width])
            response = build_obj_read_resp(cpu.pid, issuer, pkt["trans_id"],
                                           RESP_OK, data)
        self.crossbar.send_packet(response)

    def _handle_obj_write_req(self, cpu: CPU, pkt: Dict) -> None:
        p = pkt["payload"]
        ref = p[0] | (p[1] << 32)
        offset = p[2] if p[2] < 0x80000000 else p[2] - 0x100000000
        width = p[3]
        issuer = pkt["src_pid"]
        desc, fault = self._validate_at_home(cpu, ref, offset, width, CAP_W)
        if fault == RESP_OK:
            # Reconstruct data from payload words 4..end, take only `width` bytes.
            data_words = p[4:]
            raw = b''.join(struct.pack(">I", w & 0xFFFFFFFF) for w in data_words)
            desc.storage[offset:offset+width] = raw[:width]
        response = build_obj_write_resp(cpu.pid, issuer, pkt["trans_id"], fault)
        self.crossbar.send_packet(response)

    # ---- Phase 45d: remote Task primitive request handlers -----------------
    #
    # All three look up the target task from a 64-bit ref payload and
    # validate against this CPU's descriptor table. Validation uses the
    # same checks as _resolve_task_arg (descriptor exists, live,
    # generation matches, tagged TAG_TASK, present in cpu.tasks). On
    # validation failure we send the matching ERR_* in the response and
    # return immediately. On success the primitive logic runs locally.
    #
    # _resolve_remote_task returns (task, status). status == ERR_OK means
    # the task lookup succeeded; non-OK means we should return that
    # status without performing the operation.

    def _resolve_remote_task(self, cpu: CPU, ref: int) -> Tuple[Optional['Task'], int]:
        if ref == 0:
            return None, ERR_EFAULT
        if ref_home(ref) != cpu.pid:
            # Shouldn't happen — the originator wouldn't have routed
            # the request here if home didn't match cpu.pid. Treat as
            # ESTALE (nothing for us to find).
            return None, ERR_ESTALE
        idx = ref_index(ref)
        if idx <= 0 or idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
            return None, ERR_ESTALE
        desc = cpu.descriptors[idx]
        if not desc.live or desc.generation != ref_generation(ref):
            return None, ERR_ESTALE
        if desc.type_tag != TAG_TASK or idx not in cpu.tasks:
            return None, ERR_EINVAL
        return cpu.tasks[idx], ERR_OK

    def _handle_task_wait_req(self, cpu: CPU, pkt: Dict) -> None:
        p = pkt["payload"]
        ref = p[0] | (p[1] << 32)
        issuer = pkt["src_pid"]
        trans_id = pkt["trans_id"]
        task, status = self._resolve_remote_task(cpu, ref)
        if status != ERR_OK:
            self.crossbar.send_packet(build_task_wait_resp(
                cpu.pid, issuer, trans_id, status, 0))
            return
        if task.state == TASK_STATE_EXITED:
            # Already exited — reply immediately with the exit code.
            self.crossbar.send_packet(build_task_wait_resp(
                cpu.pid, issuer, trans_id, ERR_OK, task.exit_code & 0xFF))
            return
        # Park the request as a remote waiter. _wake_waiters will pump
        # the response when this task transitions to EXITED (via either
        # primitive_TaskExit on the task itself or primitive_TaskKill
        # from anywhere).
        task.remote_waiters.append((issuer, trans_id))

    def _handle_task_query_req(self, cpu: CPU, pkt: Dict) -> None:
        p = pkt["payload"]
        ref = p[0] | (p[1] << 32)
        issuer = pkt["src_pid"]
        trans_id = pkt["trans_id"]
        task, status = self._resolve_remote_task(cpu, ref)
        if status != ERR_OK:
            self.crossbar.send_packet(build_task_query_resp(
                cpu.pid, issuer, trans_id, status, 0))
            return
        # Build the same packed state word primitive_TaskQuery does
        # (Vol VI #0x008): low 8 bits = state, next 8 = proc, upper
        # 16 = exit_code (only meaningful for EXITED).
        state = task.state & 0xFF
        proc  = cpu.pid & 0xFF
        code  = (task.exit_code or 0) & 0xFFFF \
                if task.state == TASK_STATE_EXITED else 0
        packed = state | (proc << 8) | (code << 16)
        self.crossbar.send_packet(build_task_query_resp(
            cpu.pid, issuer, trans_id, ERR_OK, packed))

    def _handle_task_kill_req(self, cpu: CPU, pkt: Dict) -> None:
        p = pkt["payload"]
        ref = p[0] | (p[1] << 32)
        exit_code = p[2] & 0xFF
        issuer = pkt["src_pid"]
        trans_id = pkt["trans_id"]
        task, status = self._resolve_remote_task(cpu, ref)
        if status != ERR_OK:
            self.crossbar.send_packet(build_task_kill_resp(
                cpu.pid, issuer, trans_id, status))
            return
        # Local primitive_TaskKill rejects "kill yourself"; remote
        # callers can't BE the target (different CPU), so the only
        # protective check that still applies is "kill of an already-
        # EXITED task is a no-op (idempotent)" — same as the local path.
        if task.state == TASK_STATE_EXITED:
            self.crossbar.send_packet(build_task_kill_resp(
                cpu.pid, issuer, trans_id, ERR_OK))
            return
        # Drop the target from anywhere it might be parked, mirroring
        # primitive_TaskKill.
        if task.state == TASK_STATE_RUNNABLE:
            try:
                cpu.runnable.remove(task)
            except ValueError:
                pass
        was_current = (task is cpu.current_task)
        task.blocked_on = None
        task.state      = TASK_STATE_EXITED
        task.exit_code  = exit_code
        if was_current:
            # The home CPU was running this task at the moment we
            # killed it. Step it off the CPU now: pick another
            # runnable, context-switch, and (if there's nothing
            # else to run) park on BlockedOnExitWait so the CPU
            # stays alive to answer in-flight requests until the
            # scheduler finds something else to schedule. This
            # mirrors what primitive_TaskExit does when a task
            # exits itself, except triggered by a remote SEND
            # rather than a local CALL.
            cpu.current_task = None
            cpu.active = False
            nxt = pick_next_runnable(cpu)
            if nxt is not None:
                context_switch(cpu, nxt)
            elif any(t.state == TASK_STATE_BLOCKED
                     for t in cpu.tasks.values()):
                cpu.blocked_on = BlockedOnExitWait()
        _wake_waiters(cpu, task)
        self.crossbar.send_packet(build_task_kill_resp(
            cpu.pid, issuer, trans_id, ERR_OK))

    # ---- blocked-CPU resume ------------------------------------------------

    def _wake_blocked_tasks(self, cpu: 'CPU') -> None:
        """Scan tasks that are BLOCKED-but-not-current; if their
        IPC condition is now satisfied (matching response in
        cpu.responses, or non-empty queue), promote them to
        RUNNABLE and queue them up for the scheduler. The actual
        unblock (writing the result registers, advancing PC) happens
        in the existing _try_unblock path once the task is
        scheduled back and cpu.blocked_on holds its signal again.

        Read-only against cpu state — no responses consumed, no
        descriptor queues popped. Phase 36."""
        for task in cpu.tasks.values():
            if task.state != TASK_STATE_BLOCKED:
                continue
            if task is cpu.current_task:
                continue   # current_task's blocked_on lives on the CPU
            b = task.blocked_on
            if b is None:
                continue
            ready = False
            if isinstance(b, (BlockedOnResponse, BlockedOnTaskWait,
                              BlockedOnTaskQuery, BlockedOnTaskKill,
                              BlockedOnObjFetch)):
                # All four "wait for a response packet by trans_id"
                # signals share the same readiness condition: a matching
                # packet sitting in cpu.responses. The actual delivery
                # (R2/R3 fill, PC advance) happens in _try_unblock once
                # this task is current again.
                for packet in cpu.responses:
                    try:
                        pkt = unpack_packet(packet)
                    except ValueError:
                        continue
                    if pkt['trans_id'] == b.trans_id:
                        ready = True
                        break
            elif isinstance(b, BlockedOnQueue):
                idx = b.descriptor_idx
                if 0 < idx < len(cpu.descriptors) \
                        and cpu.descriptors[idx] is not None \
                        and cpu.descriptors[idx].queue \
                        and len(cpu.descriptors[idx].queue) > 0:
                    ready = True
                # Skip the timeout-decrement path — non-current
                # tasks don't tick down. Practical for the shell
                # case where the blocking call is term_getkey
                # (infinite timeout); user code that needs strict
                # timeout semantics should stay current.
            elif isinstance(b, BlockedOnQueueSet):
                # Ready as soon as ANY queue in the set is non-empty...
                for idx in b.descriptor_indices:
                    if 0 < idx < len(cpu.descriptors) \
                            and cpu.descriptors[idx] is not None \
                            and cpu.descriptors[idx].queue \
                            and len(cpu.descriptors[idx].queue) > 0:
                        ready = True
                        break
                # ...or the optional wall-clock timeout has expired (the
                # actual ERR_ETIMEOUT/PC-advance lands in _try_unblock_queue_set
                # once this task is current again).
                if not ready and b.deadline is not None \
                        and time.time() >= b.deadline:
                    ready = True
            if ready:
                task.state = TASK_STATE_RUNNABLE
                # Direct-handoff: a task that just had its IPC condition
                # satisfied (a reply/SEND landed) goes to the FRONT of the
                # round-robin queue, not the back, so it resumes on this
                # CPU's very next schedule instead of after a full lap.
                # The sender has effectively handed off to it. This is the
                # last interactive-latency lever: a foreground task doing
                # serial RPCs (`help`, `ps`) used to wait ~one round-robin
                # lap PER reply when other tasks were runnable; front-insert
                # collapses that to next-schedule. Still cooperative — only
                # the queue ORDER changes; the current task keeps running
                # until it yields/blocks (no preemption).
                #
                # Fairness: Ouroboros's real wake pattern is a single task
                # waiting on a single reply, so front-insert is the desired,
                # benign behavior. If a genuine wake-storm ever caused
                # starvation, fall back to insert-just-ahead-of-current or a
                # bounded boost; absolute-front is kept for simplicity until
                # a test forces otherwise.
                cpu.runnable.insert(0, task)

    def _try_unblock(self, cpu: CPU) -> bool:
        """Resume a blocked CPU if its wait condition is now satisfied.
        Returns True if the CPU made progress (delivered a message,
        advanced past a fault, or decremented a timeout)."""
        b = cpu.blocked_on
        if isinstance(b, BlockedOnQueue):
            return self._try_unblock_queue(cpu, b)
        if isinstance(b, BlockedOnQueueSet):
            return self._try_unblock_queue_set(cpu, b)
        if isinstance(b, BlockedOnResponse):
            return self._try_unblock_response(cpu, b)
        if isinstance(b, BlockedOnTaskWait):
            return self._try_unblock_task_resp(cpu, b, PKT_TASK_WAIT_RESP,
                                                deliver_r3=True)
        if isinstance(b, BlockedOnTaskQuery):
            return self._try_unblock_task_resp(cpu, b, PKT_TASK_QUERY_RESP,
                                                deliver_r3=True)
        if isinstance(b, BlockedOnTaskKill):
            return self._try_unblock_task_resp(cpu, b, PKT_TASK_KILL_RESP,
                                                deliver_r3=False)
        if isinstance(b, BlockedOnObjFetch):
            return self._try_unblock_obj_fetch(cpu, b)
        if isinstance(b, BlockedOnObjStore):
            return self._try_unblock_obj_store(cpu, b)
        return False

    def _try_unblock_queue(self, cpu: CPU, b: 'BlockedOnQueue') -> bool:
        idx = b.descriptor_idx
        if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0)
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        desc = cpu.descriptors[idx]
        if desc.queue and len(desc.queue) > 0:
            _deliver_queue_msg(cpu, desc.queue.pop(0))
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        if b.timeout < 0:
            return False    # infinite wait, nothing to do this tick
        b.timeout -= 1
        if b.timeout <= 0:
            cpu.set_gpr(2, ERR_ETIMEOUT); cpu.set_gpr(3, 0)
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        return True   # decremented the timer

    def _try_unblock_queue_set(self, cpu: CPU,
                               b: 'BlockedOnQueueSet') -> bool:
        """Resume a WaitAnyQueue once ANY listed queue is non-empty.
        Pure readiness: we DON'T pop the message (the caller drains it
        with its own ReceiveQueuePoll) — we just set R2 = ERR_OK and
        advance past the CALL. With a finite b.deadline, an expired
        wall-clock deadline resumes with ERR_ETIMEOUT instead; otherwise
        returning False keeps the CPU parked until a queue fills."""
        for idx in b.descriptor_indices:
            if 0 < idx < len(cpu.descriptors) \
                    and cpu.descriptors[idx] is not None \
                    and cpu.descriptors[idx].queue \
                    and len(cpu.descriptors[idx].queue) > 0:
                cpu.set_gpr(2, ERR_OK)
                cpu.set_gpr(3, 0)
                cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
                cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
                cpu.blocked_on = None
                return True
        if b.deadline is not None and time.time() >= b.deadline:
            cpu.set_gpr(2, ERR_ETIMEOUT)
            cpu.set_gpr(3, 0)
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        return False   # nothing ready yet — stay blocked

    def _try_unblock_response(self, cpu: CPU, b: 'BlockedOnResponse') -> bool:
        """Look for a response packet matching this CPU's outstanding
        request trans_id; on match either deliver into the destination
        register (read) or simply ack (write), then advance PC. On a
        non-OK response flag, raise the corresponding architectural
        Trap (which the scheduler catches)."""
        for i, packet in enumerate(cpu.responses):
            try:
                pkt = unpack_packet(packet)
            except ValueError:
                continue
            if pkt["trans_id"] != b.trans_id:
                continue
            cpu.responses.pop(i)
            flags = pkt["flags"] & 0x3F
            if flags != RESP_OK:
                cpu.blocked_on = None
                cause = RESP_FLAG_TO_CAUSE.get(flags, CAUSE_BUS_ERROR_D)
                raise Trap(cause, cpu.pc,
                           f"remote O{'S' if b.is_write else 'L'} fault "
                           f"flags={flags:#x}")
            if not b.is_write:
                # Reassemble the loaded value from the response data words.
                payload = pkt["payload"]
                raw = b''.join(struct.pack(">I", w & 0xFFFFFFFF) for w in payload)
                raw = raw[:b.width]
                v = int.from_bytes(raw, "big")
                if b.signed and v & (1 << (b.width*8 - 1)):
                    v -= 1 << (b.width*8)
                cpu.set_gpr(b.target_reg, to_u32(v))
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        return False  # no matching response yet

    def _try_unblock_obj_fetch(self, cpu: CPU, b: 'BlockedOnObjFetch') -> bool:
        """Phase 45e. Handler for ObjFetchBytes responses. The response
        is a regular OBJ_READ_RESP (we reuse the existing wire packet
        instead of inventing a new type — it already carries the bytes
        in its payload), matched by trans_id. On RESP_OK we copy the
        payload into the local destination descriptor at the offset
        the primitive recorded; on a fault flag we map RESP_* to ERR_*
        and leave the destination untouched. R2 = status, R3 = bytes
        copied (== b.byte_count on OK, 0 on fault), PC advances."""
        for i, packet in enumerate(cpu.responses):
            try:
                pkt = unpack_packet(packet)
            except ValueError:
                continue
            if pkt['type'] != PKT_OBJ_READ_RESP:
                continue
            if pkt['trans_id'] != b.trans_id:
                continue
            cpu.responses.pop(i)
            flags = pkt['flags'] & 0x3F
            if flags != RESP_OK:
                # Map RESP_* fault to ERR_* status; same translation
                # OL/OS uses to raise an architectural Trap, but here
                # we surface it as an ordinary primitive return code
                # so the caller can recover (it's a polled bulk read,
                # not a CPU-instruction load).
                err_map = {
                    RESP_STALE:     ERR_ESTALE,
                    RESP_BOUNDS:    ERR_EINVAL,
                    RESP_CAP:       ERR_EPERM,
                    RESP_BUS_ERROR: ERR_EFAULT,
                }
                cpu.set_gpr(2, err_map.get(flags, ERR_EFAULT))
                cpu.set_gpr(3, 0)
            else:
                payload = pkt['payload']
                raw = b''.join(struct.pack(">I", w & 0xFFFFFFFF)
                               for w in payload)
                raw = raw[:b.byte_count]
                # Re-validate the destination descriptor — the caller
                # may have ObjFreed it between issuing the request and
                # the response arriving (unlikely but possible if a
                # signal handler runs in between).
                desc = cpu.descriptors[b.dst_idx] \
                       if 0 < b.dst_idx < len(cpu.descriptors) else None
                if desc is None or not desc.live:
                    cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0)
                else:
                    desc.storage[b.dst_off:b.dst_off+b.byte_count] = raw
                    cpu.set_gpr(2, ERR_OK)
                    cpu.set_gpr(3, b.byte_count)
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        return False

    def _try_unblock_obj_store(self, cpu: CPU, b: 'BlockedOnObjStore') -> bool:
        """Phase 59. Mirror of _try_unblock_obj_fetch for ObjStoreBytes.
        The response is an OBJ_WRITE_RESP — no payload, just a flags
        byte.  On RESP_OK: R2 = ERR_OK, R3 = byte_count.  On fault:
        R2 = mapped ERR_*, R3 = 0.  Same RESP_* → ERR_* mapping
        ObjFetchBytes uses, since the failure modes (stale ref,
        out-of-bounds offset, missing W cap, etc.) are symmetric
        across read and write."""
        for i, packet in enumerate(cpu.responses):
            try:
                pkt = unpack_packet(packet)
            except ValueError:
                continue
            if pkt['type'] != PKT_OBJ_WRITE_RESP:
                continue
            if pkt['trans_id'] != b.trans_id:
                continue
            cpu.responses.pop(i)
            flags = pkt['flags'] & 0x3F
            if flags != RESP_OK:
                err_map = {
                    RESP_STALE:     ERR_ESTALE,
                    RESP_BOUNDS:    ERR_EINVAL,
                    RESP_CAP:       ERR_EPERM,
                    RESP_BUS_ERROR: ERR_EFAULT,
                }
                cpu.set_gpr(2, err_map.get(flags, ERR_EFAULT))
                cpu.set_gpr(3, 0)
            else:
                cpu.set_gpr(2, ERR_OK)
                cpu.set_gpr(3, b.byte_count)
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        return False

    def _try_unblock_task_resp(self, cpu: CPU, b: 'BlockedSignal',
                                expected_type: int, deliver_r3: bool) -> bool:
        """Phase 45d. Unified handler for the three new
        BlockedOnTask{Wait,Query,Kill} signals — they share a wire
        layout (status word in payload[0], optional secondary word in
        payload[1]). Match by trans_id, deliver R2 = status, R3 =
        secondary (when `deliver_r3`), advance PC, clear blocked_on.

        For TASK_KILL_RESP `deliver_r3` is False — the architectural
        TaskKill returns only a status in R2 (Vol VI #0x00A) and we
        don't want to clobber R3 from whatever the program had there.
        """
        for i, packet in enumerate(cpu.responses):
            try:
                pkt = unpack_packet(packet)
            except ValueError:
                continue
            if pkt["type"] != expected_type:
                continue
            if pkt["trans_id"] != b.trans_id:
                continue
            cpu.responses.pop(i)
            payload = pkt["payload"]
            status = payload[0] if payload else ERR_EFAULT
            cpu.set_gpr(2, status & 0xFFFFFFFF)
            if deliver_r3:
                secondary = payload[1] if len(payload) >= 2 else 0
                cpu.set_gpr(3, secondary & 0xFFFFFFFF)
            cpu.pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.next_pc = (cpu.pc + 4) & 0xFFFFFFFF
            cpu.blocked_on = None
            return True
        return False  # no matching response yet

    # ---- scheduler ---------------------------------------------------------

    def run(self, max_cycles: int) -> int:
        """Round-robin one instruction per active CPU per tick; dispatch
        handler tasks on idle CPUs with queued SENDs. Returns the exit code
        of CPU 0 (or of whichever CPU last exited if CPU 0 didn't run).

        `max_cycles == 0` means unlimited — the loop runs until the
        natural exit conditions fire (TaskExitSignal with no remaining
        work, or socket EOF in --connect mode). The default 10M cap is
        there as a CI safety net for runaway tests, not as a real
        budget for interactive use."""
        ticks = 0
        while max_cycles == 0 or ticks < max_cycles:
            any_progress = False
            # Drain incoming bytes from the crossbar transport (no-op for
            # InProcessCrossbar). This must happen before per-CPU work so
            # that responses arriving via socket are visible this tick.
            if self.crossbar.poll_incoming():
                any_progress = True
            # Then, drain inbound OBJ_READ_REQ / OBJ_WRITE_REQ packets on
            # every CPU. This represents the home processor's autonomous
            # memory-controller behaviour and runs regardless of the CPU's
            # task state — even idle or blocked CPUs answer remote reads.
            for cpu in self.cpus:
                if cpu.requests:
                    self._process_requests(cpu)
                    any_progress = True
            # Process any ObjFreeDeferred (#0x107) deadlines that have
            # elapsed. The descriptor stayed live up to this point so
            # late OBJ_READ_REQs from receivers (oriscterm, hostfsd)
            # could still be answered; now we tear it down for real.
            now = time.time()
            for cpu in self.cpus:
                if cpu.deferred_frees:
                    survivors = []
                    for (deadline, idx) in cpu.deferred_frees:
                        if now >= deadline:
                            if 0 < idx < len(cpu.descriptors) \
                                    and cpu.descriptors[idx] is not None \
                                    and cpu.descriptors[idx].live:
                                cpu.free_object(idx)
                            any_progress = True
                        else:
                            survivors.append((deadline, idx))
                    cpu.deferred_frees = survivors
            for cpu in self.cpus:
                # Wake any non-current BLOCKED tasks whose unblock
                # condition is now satisfied (the response landed,
                # the queue got a SEND); they go back to RUNNABLE for
                # the scheduler to pick. The actual unblock work
                # (writing R2/R3, advancing PC) happens when the task
                # is next scheduled and cpu.blocked_on is processed.
                self._wake_blocked_tasks(cpu)
                # Blocked CPUs: see if their queue/response is now ready
                # and resume past the CALL or OL/OS accordingly.
                if cpu.blocked_on is not None:
                    try:
                        if self._try_unblock(cpu):
                            any_progress = True
                    except Trap as t:
                        if deliver_trap(cpu, t):
                            any_progress = True
                            continue
                        report_trap(cpu, t)
                        return 3
                    # Still blocked? If there's another runnable task on
                    # this CPU, switch to it — the blocked task's
                    # blocked_on is preserved in its Task struct via
                    # save_cpu_to_task and will be reinstated when it's
                    # scheduled back. (Phase 36 — blocked-task preemption.)
                    if cpu.blocked_on is not None and cpu.runnable:
                        cur = cpu.current_task
                        nxt = pick_next_runnable(cpu)
                        if nxt is not None and nxt is not cur:
                            if cur is not None and cur.state != TASK_STATE_EXITED:
                                # Park the live current task as BLOCKED;
                                # save_cpu_to_task captures cpu.blocked_on
                                # so its wait state is restored when it's
                                # scheduled back. EXITED tasks just stay
                                # EXITED — nothing to save and we don't
                                # want to flip them to BLOCKED.
                                cur.state = TASK_STATE_BLOCKED
                                save_cpu_to_task(cpu, cur)
                            load_task_to_cpu(cpu, nxt)
                            nxt.state = TASK_STATE_RUNNING
                            cpu.current_task = nxt
                            any_progress = True
                    continue
                if cpu.active:
                    try:
                        step(cpu)
                    except BlockedSignal as b:
                        # Raised mid-instruction (e.g., remote OL/OS).
                        # PC is unchanged; the scheduler will resume
                        # from the same instruction once the response
                        # arrives.
                        cpu.blocked_on = b
                        any_progress = True
                        continue
                    except TaskExitSignal as e:
                        if getattr(cpu, "reset_on_exit", False):
                            # MVP "tiny OS": this CPU is a reusable
                            # program slot. The guest just TaskExited;
                            # we'll wipe state and re-run the loader.
                            # But: if the guest's last act was a
                            # term_print SEND, the receiver may still
                            # be issuing OBJ_READ_REQs against the
                            # guest's data descriptor — wiping
                            # immediately would lose those bytes.
                            # Defer the actual reset until a wall-
                            # clock deadline; meanwhile
                            # _process_requests answers in-flight
                            # reads against the still-valid descriptor
                            # table.
                            cpu.active = False
                            cpu.exit_code = e.code & 0xFF
                            cpu.reset_at_time = time.time() + RESET_DRAIN_SECONDS
                            any_progress = True
                            continue
                        cpu.active = False
                        cpu.exit_code = e.code & 0xFF
                        # Snapshot state at TaskExit so any handlers that
                        # subsequently dispatch on this CPU inherit the
                        # environment main configured (e.g., O5..O15
                        # carrying refs to other objects). Architecturally
                        # the handler is a fresh task; this snapshot is the
                        # firmware/loader's contribution to its initial
                        # register state, atop which the SEND payload is
                        # overlaid by Volume III Section 7.2.
                        cpu.boot_state = {
                            "gpr": list(cpu.gpr),
                            "opr": list(cpu.opr),
                            "code_va_base": cpu.boot_state["code_va_base"],
                        }
                    except Trap as t:
                        if deliver_trap(cpu, t):
                            any_progress = True
                            continue
                        report_trap(cpu, t)
                        return 3
                    any_progress = True
                else:
                    # Inactive CPU: either it's draining toward a
                    # deferred reset (the wall-clock deadline gates
                    # this; while waiting, _process_requests above
                    # still answers in-flight reads), or it has
                    # handler dispatch work to do.
                    if getattr(cpu, "reset_at_time", 0) > 0:
                        if time.time() >= cpu.reset_at_time:
                            cpu.reset_at_time = 0
                            reset_cpu(cpu)
                            any_progress = True
                        # else: don't set any_progress — let the run
                        # loop's idle-sleep give us 1ms ticks while
                        # we wait for the deadline.
                    elif self.dispatch_handler(cpu):
                        any_progress = True
            if not any_progress:
                # Stay alive if any of: (a) the user asked us to serve
                # forever via --serve, (b) we're in socket mode and at
                # least one CPU is blocked waiting on something the
                # socket might deliver, or (c) a CPU is draining
                # toward a deferred reset and may yet receive
                # in-flight OBJ_READ_REQs. In all cases, exit when
                # the socket has EOF'd.
                in_socket_mode = hasattr(self.crossbar, 'connected')
                waiting_blocked = any(
                    cpu.blocked_on is not None for cpu in self.cpus)
                draining = any(
                    getattr(cpu, "reset_at_time", 0) > 0 for cpu in self.cpus)
                # Pending ObjFreeDeferred deadlines deliberately do NOT
                # keep the loop alive: if the system has otherwise gone
                # idle (e.g., the shell typed `exit`), the host process
                # is winding down and the OS reclaims everything. Frees
                # only matter while there's an active CPU around to
                # service incoming OBJ_READ_REQs against the not-yet-
                # freed descriptor; in that case the active CPU itself
                # already keeps the loop alive via any_progress.
                if self.serve_mode or (in_socket_mode and waiting_blocked) \
                        or (in_socket_mode and draining):
                    if in_socket_mode and not self.crossbar.connected:
                        break
                    # Idle wait. No runnable work this tick; we're blocked on
                    # something a socket packet (an IPC reply / SEND) will
                    # deliver. Rather than sleep a fixed quantum and re-poll —
                    # which made every cross-crossbar round-trip wait out up to
                    # a full ~1 ms timer even though the reply bytes were
                    # already in the socket — block in select() on the crossbar
                    # socket, so an arriving packet wakes us at once. The 1 ms
                    # timeout is now only a ceiling for non-socket wakeups
                    # (deferred-free / reset deadlines, host display ticks).
                    _sock = getattr(self.crossbar, "sock", None)
                    if _sock is not None:
                        try:
                            select.select([_sock], (), (), 0.001)
                        except (OSError, ValueError):
                            time.sleep(0.001)
                    else:
                        time.sleep(0.001)
                    ticks += 1
                    # Phase 60 — pump the host display worker on idle
                    # ticks too, so a screen with no firmware activity
                    # still processes Tk events (window-close, expose,
                    # etc.).
                    for cpu in self.cpus:
                        w = getattr(cpu, "display_worker", None)
                        if w is not None:
                            w.tick()
                    continue
                break
            ticks += 1
            # Phase 60 — pump host display workers each progress tick.
            # Internally throttled to ~60 Hz so rapid bursts of
            # ObjStoreBytes don't repaint per cycle.
            for cpu in self.cpus:
                w = getattr(cpu, "display_worker", None)
                if w is not None:
                    w.tick()
        else:
            print(f"simorisc: max cycles exceeded ({max_cycles})", file=sys.stderr)
            return 2

        # Determine exit code: prefer CPU 0's exit, else first non-None.
        for cpu in self.cpus:
            if cpu.exit_code is not None:
                return cpu.exit_code
        return 0


# ---------------------------------------------------------------------------
# Decoder helpers
# ---------------------------------------------------------------------------

def sext16(v: int) -> int:
    v &= 0xFFFF
    return v - 0x10000 if v & 0x8000 else v

def sext32(v: int) -> int:
    v &= 0xFFFFFFFF
    return v - 0x100000000 if v & 0x80000000 else v

def to_u32(v: int) -> int:
    return v & 0xFFFFFFFF


# ---------------------------------------------------------------------------
# Phase 60 — host display worker (--display tk)
# ---------------------------------------------------------------------------
#
# When simorisc runs with --display tk, every TAG_FRAMEBUFFER object the
# CPU allocates (via primitive_ObjAllocFramebuffer) gets mirrored into a
# host Tk window.  Stores via ObjStoreBytes flag the descriptor dirty;
# the worker repaints on its next tick.  No wire round-trips — the
# pixel bytes live in the same Python process as the simulator.
#
# Headless (default `--display none`) keeps the firmware op working
# (TAG_FRAMEBUFFER is just a plain bytearray) but skips Tk; lets CI
# and smoke tests exercise the same firmware path without a display.

def olgx_color_group(bg1_hex):
    """OPEN LOOK 3D color group {White, BG1, BG2, BG3} from a base face
    color BG1, via the olgx HSV algorithm (libolgx ol_color.c
    `olgx_hsv_to_3D`): work in HSV; from base V — White = V*1.2 (VMUL),
    BG2 = V*0.9, BG3 = V*0.5 (SDIV/2 group), clamped to a 40% value floor
    (VMIN).  If White's value clips past 100% it is pinned to full value
    and its saturation halved, driving it toward pure white.

    For a gray BG1 (S=0) this reduces to plain RGB scaling; for a colored
    window tint (a later PR) the HSV path keeps the highlight tinted.
    BG1 #cccccc -> White #f5f5f5, BG2 #b8b8b8, BG3 #666666 — exactly the
    grays sampled from the real OpenWindows shot (docs/images/
    openwindows_ipx.png).  Returns a dict of '#rrggbb' strings."""
    r, g, b = (int(bg1_hex[i:i + 2], 16) for i in (1, 3, 5))
    h, s, v = colorsys.rgb_to_hsv(r / 255.0, g / 255.0, b / 255.0)
    VMUL, BG2_MUL, BG3_MUL, VMIN = 1.2, 0.9, 0.5, 0.40

    def _hex(hh, ss, vv):
        rr, gg, bb = colorsys.hsv_to_rgb(hh, ss, max(0.0, min(1.0, vv)))
        return "#%02x%02x%02x" % (round(rr * 255), round(gg * 255),
                                  round(bb * 255))

    vw, sw = v * VMUL, s
    if vw > 1.0:                       # highlight clips -> pin V, halve S
        vw, sw = 1.0, s / 2.0
    return {
        "white": _hex(h, sw, vw),
        "bg1":   bg1_hex,
        "bg2":   _hex(h, s, max(VMIN, v * BG2_MUL)),
        "bg3":   _hex(h, s, max(VMIN, v * BG3_MUL)),
    }


# OPEN LOOK gray-on-blue.  The window's gray color group is DERIVED from
# BG1 via olgx_color_group (not hand-typed), so a future colored-tint PR
# reuses the same math.
_OL_GRAY = olgx_color_group("#cccccc")

# Index -> RGB for the 8-bit indexed framebuffer.
#   0-8   the development accent ramp.  mouse_paint cycles 1..8; idx 8
#         (pure white) doubles as the OPEN LOOK focused-title-bar white.
#         These are NOT repurposed by the OPEN LOOK scheme.
#   9-14  OPEN LOOK gray-on-blue (real OpenWindows 3 / SunOS 4.1.4 —
#         docs/images/openwindows_ipx.png; the WM's chrome constants map
#         onto these in oriscwm.c):
#           9  workspace desktop  #40a0c0   bright cyan-blue
#          10  window face / unfocused title  BG1 #cccccc
#          11  highlight / content pane       White #f5f5f5  (bevel: next PR)
#          12  bevel mid                      BG2 #b8b8b8    (bevel: next PR)
#          13  frame outline / shadow         BG3 #666666
#          14  text / outlines                #000000
VEC_PALETTE_HEX = {
    0: "#0a0a14", 1: "#d8d8d8", 2: "#ff5555", 3: "#55ff55",
    4: "#5599ff", 5: "#ffd866", 6: "#66ddff", 7: "#ff66ff",
    8: "#ffffff",
    9:  "#40a0c0",
    10: _OL_GRAY["bg1"],
    11: _OL_GRAY["white"],
    12: _OL_GRAY["bg2"],
    13: _OL_GRAY["bg3"],
    14: "#000000",
}

# Key codepoints sent to TAG_INPUT_SINK (kind=0) subscribers.  Mirror
# of oriscterm's KEY_* constants — receivers (oriscwm + libc term.c)
# already know these.  Printable characters use their plain byte
# value (event.char); special keys map via KEYSYM_TO_CODE below.
# Must match liborisc.h's TK_* defines so client programs (edit,
# shell read_line, winhello, etc.) recognise them.  Pre-step-14
# this file used a different numbering inherited from oriscterm's
# legacy protocol; arrow keys silently dropped because TK_UP
# (0x180) and the WM-emitted 0x126 didn't match in any edit-style
# `if (key == TK_UP)` check.
KEY_BACKSPACE = 0x108
KEY_TAB       = 0x109
KEY_RETURN    = 0x10D
KEY_FOCUS_IN  = 0x10E
KEY_ESCAPE    = 0x11B
KEY_DELETE    = 0x17F
KEY_UP        = 0x180
KEY_DOWN      = 0x181
KEY_LEFT      = 0x182
KEY_RIGHT     = 0x183
KEY_HOME      = 0x184
KEY_END       = 0x185
KEY_PAGE_UP   = 0x186
KEY_PAGE_DOWN = 0x187
KEY_F1        = 0x190

# Pointer event types (kind=1).  Mirror of oriscterm's PTR_*.
PTR_MOTION = 0x00
PTR_DOWN   = 0x01
PTR_UP     = 0x02

KEYSYM_TO_CODE = {
    "BackSpace": KEY_BACKSPACE,
    "Tab":       KEY_TAB,
    "Return":    KEY_RETURN,
    "Escape":    KEY_ESCAPE,
    "Delete":    KEY_DELETE,
    "Up":        KEY_UP,
    "Down":      KEY_DOWN,
    "Left":      KEY_LEFT,
    "Right":     KEY_RIGHT,
    "Home":      KEY_HOME,
    "End":       KEY_END,
    "Prior":     KEY_PAGE_UP,
    "Next":      KEY_PAGE_DOWN,
    **{f"F{i}": KEY_F1 + (i - 1) for i in range(1, 13)},
}


def _build_palette_lut():
    """Per-index 3-byte RGB lookup, used by the b\"\".join repaint loop.
    Indices outside VEC_PALETTE_HEX fall through to bg (idx 0).  Same
    shape γ.10 used in oriscterm — repaints land in the tens of ms even
    at 1280×768 because the inner loop is C-level (`b\"\".join`)."""
    bg = VEC_PALETTE_HEX[0]
    bg_rgb = bytes((int(bg[1:3], 16), int(bg[3:5], 16), int(bg[5:7], 16)))
    lut = []
    for i in range(256):
        h = VEC_PALETTE_HEX.get(i)
        if h is None:
            lut.append(bg_rgb)
        else:
            lut.append(bytes((int(h[1:3], 16), int(h[3:5], 16),
                              int(h[5:7], 16))))
    return lut


class TkDisplayWorker:
    """Bind host Tk windows to TAG_FRAMEBUFFER objects.  Lifetime
    matches the parent simorisc process; per-CPU instance.

    The worker is no-op when Tk import fails (CI / headless) — the
    framebuffer object still exists, the firmware path still works,
    just nothing visible appears.

    tick() is called from System.run after each progress pass.  It
    pumps Tk's event loop and repaints any framebuffer whose
    desc.fb_dirty is set.  Repaints throttle at ~60 Hz to keep the
    simulator from spending its budget repainting on rapid bursts of
    small writes."""

    def __init__(self, title_prefix="oriscwm fb"):
        self.title_prefix = title_prefix
        self._tk = None        # tkinter module (lazy import)
        self._root = None
        self._tracked = {}     # idx → {win, image, width, height, desc}
        # Pending registrations: (cpu_pid, idx, desc).  Filled by
        # register_framebuffer (called from inside the firmware
        # primitive — must return fast so the WM doesn't stall while
        # supervisors are racing wm_init retries) and drained by
        # tick() off the firmware-critical path.  Tk root + Toplevel
        # creation is hundreds of ms, enough to push the WM's
        # /sys/wm/<N>/0 dir_register past the supervisor's retry
        # budget.
        self._pending = []
        self._lut = _build_palette_lut()
        self._last_repaint = 0.0
        self._min_repaint_interval = 1.0 / 60.0

    def _ensure_root(self):
        if self._root is not None:
            return
        try:
            import tkinter as tk
        except ImportError:
            return
        try:
            self._root = tk.Tk()
        except Exception:
            self._root = None
            return
        self._tk = tk
        self._root.withdraw()  # FB windows are Toplevels; root invisible

    def register_framebuffer(self, cpu, idx, desc):
        # Fast path: just record.  tick() does the heavy Tk init.
        # cpu reference goes along for input event lookup later.
        self._pending.append((cpu, idx, desc))

    def _drain_pending(self):
        if not self._pending:
            return
        self._ensure_root()
        if self._root is None:
            self._pending.clear()  # Tk unavailable; drop without retry
            return
        while self._pending:
            cpu, idx, desc = self._pending.pop(0)
            if idx in self._tracked:
                continue
            win = self._tk.Toplevel(self._root)
            win.title(f"{self.title_prefix} pid={cpu.pid} fb#{idx}")
            img = self._tk.PhotoImage(width=desc.fb_width,
                                      height=desc.fb_height)
            # Phase 60 step 3 — Canvas takes focus so <Key> events
            # actually route to its handler.  Toplevel <Key> bindings
            # don't fire (Toplevel isn't a focus-capturing widget);
            # the Canvas is, so bind there.  takefocus=1 +
            # focus_set on creation + click-to-focus binding so
            # users get input when they click the window.
            canvas = self._tk.Canvas(win,
                                     width=desc.fb_width,
                                     height=desc.fb_height,
                                     borderwidth=0,
                                     highlightthickness=0,
                                     takefocus=1)
            canvas.pack(fill="both", expand=True)
            canvas.create_image(0, 0, image=img, anchor="nw")
            canvas.bind("<Key>", lambda ev, c=cpu: self._on_key(c, ev))
            canvas.bind("<Motion>",
                        lambda ev, c=cpu: self._on_pointer(c, ev,
                                                           PTR_MOTION, 0))
            canvas.bind("<ButtonPress>",
                        lambda ev, c=cpu, cv=canvas: (
                            cv.focus_set(),
                            self._on_pointer(c, ev, PTR_DOWN, ev.num),
                        ))
            canvas.bind("<ButtonRelease>",
                        lambda ev, c=cpu: self._on_pointer(c, ev,
                                                           PTR_UP,
                                                           ev.num))
            # Cmd+S dumps the live framebuffer to a native-resolution PNG
            # (the image's own pixels, untouched by macOS Retina doubling)
            # for a true 1:1 look; consumed here ("break") so it never
            # reaches the WM as a keystroke.
            canvas.bind("<Command-s>", lambda ev, i=idx: self._snapshot(i))
            canvas.focus_set()
            self._tracked[idx] = {
                "win": win, "image": img,
                "width": desc.fb_width, "height": desc.fb_height,
                "desc": desc, "cpu": cpu,
            }

    @staticmethod
    def _key_codepoint(event):
        """Tk event → a portable codepoint matching oriscterm's
        protocol.  Returns None for keys we don't translate
        (pure modifier presses, dead keys, etc.). """
        sym = event.keysym
        if sym in KEYSYM_TO_CODE:
            return KEYSYM_TO_CODE[sym]
        ch = event.char
        if not ch:
            return None
        b = ord(ch)
        if b == 0:
            return None
        return b

    def _enqueue_sink(self, cpu, kind, int_payload):
        """Deliver a live Tk input event into the CPU's TAG_INPUT_SINK.
        Thin wrapper over CPU.enqueue_input_sink (shared with the
        headless PKT_HOST_INPUT path) so the _on_key/_on_pointer
        handlers read naturally."""
        cpu.enqueue_input_sink(kind, int_payload)

    def _on_key(self, cpu, event):
        code = self._key_codepoint(event)
        # mods bits: 1=Shift, 2=Ctrl, 4=Alt — same as oriscterm.
        st = event.state
        mods = ((1 if (st & 0x01) else 0)
                | (2 if (st & 0x04) else 0)
                | (4 if (st & 0x08) else 0))
        # macOS Aqua Tk doesn't fill event.char for Ctrl+letter
        # combos (event.char comes back empty), so _key_codepoint
        # returns None and the event would otherwise drop on the
        # floor — meaning ^X / ^S / etc. in editors silently fail.
        # When Ctrl is held and the keysym is a single ASCII letter,
        # synthesize the ASCII control character ourselves: ^X is
        # 'x' & 0x1F = 0x18, ^S is 's' & 0x1F = 0x13, etc.  Matches
        # what X11 / Linux Tk delivers in event.char natively.
        if code is None and (mods & 2):
            sym = event.keysym
            if len(sym) == 1 and sym.isalpha():
                code = ord(sym.lower()) & 0x1F
        if code is None:
            return
        self._enqueue_sink(cpu, 0, [code, mods, 0, 0])

    def _on_pointer(self, cpu, event, evt_type, button):
        x = max(0, min(0xFFFF, int(event.x)))
        y = max(0, min(0xFFFF, int(event.y)))
        packed_xy = ((x & 0xFFFF) << 16) | (y & 0xFFFF)
        # button-state mask uses bit (1 << button); event.state
        # carries Tk's mouse-button bits at 0x100 (Btn1) etc.,
        # but we just synthesize from the current down/up event
        # for v1 — matches oriscterm's coarse behaviour.
        btn_state = (1 << button) if evt_type != PTR_UP else 0
        self._enqueue_sink(cpu, 1,
                           [evt_type, packed_xy, button, btn_state])

    def _snapshot(self, idx):
        """Cmd+S handler: write the live framebuffer to a native-resolution
        PNG under /tmp.  PhotoImage.write() emits the image's own pixels, so
        the file is the true 1:1 framebuffer regardless of the Retina display
        doubling.  Falls back to PPM if this Tk build lacks PNG."""
        info = self._tracked.get(idx)
        if info is None:
            return "break"
        self._snap_seq = getattr(self, "_snap_seq", 0) + 1
        base = "/tmp/orisc-fb%d-%03d" % (idx, self._snap_seq)
        try:
            info["image"].write(base + ".png", format="png")
            out = base + ".png"
        except Exception:
            info["image"].write(base + ".ppm")
            out = base + ".ppm"
        sys.stderr.write("[display] framebuffer snapshot %dx%d -> %s\n"
                         % (info["width"], info["height"], out))
        sys.stderr.flush()
        return "break"

    def _repaint(self, info):
        desc = info["desc"]
        W, H = info["width"], info["height"]
        lut = self._lut
        rgb = b"".join([lut[b] for b in desc.storage])
        ppm = (b"P6\n" + str(W).encode() + b" "
               + str(H).encode() + b"\n255\n" + rgb)
        try:
            info["image"].configure(data=ppm)
        except Exception:
            pass

    def tick(self):
        # System.run calls tick() once per simulated CPU instruction —
        # too often for any actual Tk work, so wallclock-throttle the
        # whole body to ~60 Hz.  Early-return on the throttle keeps
        # the per-cycle overhead to a single time.time() + compare,
        # which restores the WM CPU's effective rate after Phase 60
        # step 2 hooked us into the cycle loop.
        if not self._pending and self._root is None:
            return  # no Tk yet AND nothing pending — pure no-op
        now = time.time()
        if now - self._last_repaint < self._min_repaint_interval:
            return
        # Drain any pending Tk window registrations first — they
        # arrive from primitive_ObjAllocFramebuffer, which has to
        # return fast for the WM's boot sequence.
        self._drain_pending()
        if self._root is None:
            return
        for info in self._tracked.values():
            desc = info["desc"]
            if desc.fb_dirty:
                self._repaint(info)
                desc.fb_dirty = False
        self._last_repaint = now
        try:
            self._root.update()
        except Exception:
            self._root = None


# ---------------------------------------------------------------------------
# Loader (CONTRACT.md Section 1 + 2)
# ---------------------------------------------------------------------------

DEFAULT_STACK_SIZE = 0x10000

# Wall-clock seconds a --reset-on-exit CPU spends in a "drain" phase
# between TaskExit and the actual reset. During this window the CPU
# doesn't fetch instructions, but _process_requests still answers any
# in-flight OBJ_READ_REQs from receivers (e.g., oriscterm fetching
# the bytes of the guest's last term_print). Sized for a few-process
# Tk-mediated SEND→OBJ_READ_REQ round trip with some slack.
RESET_DRAIN_SECONDS = 0.5

def load_orx_file(path: str) -> Tuple[bytes, bytes, int, int]:
    """Parse an .orx file and return (text_bytes, data_bytes, entry_offset,
    stack_size)."""
    with open(path, "rb") as f:
        data = f.read()
    if len(data) < 0x20:
        sys.exit(f"simorisc: {path}: file too short for header")
    if data[:8] != MAGIC:
        sys.exit(f"simorisc: {path}: bad magic (got {data[:8]!r}, want {MAGIC!r})")
    version, flags, entry, text_size, data_size, stack_size = \
        struct.unpack(">IIIIII", data[0x08:0x20])
    if version != 1:
        sys.exit(f"simorisc: {path}: unsupported format version {version}")
    if text_size % 4 != 0:
        sys.exit(f"simorisc: {path}: text_size {text_size} not multiple of 4")
    expected = 0x20 + text_size + data_size
    if len(data) != expected:
        sys.exit(f"simorisc: {path}: file size {len(data)} != header-implied {expected}")
    if entry >= text_size or entry % 4 != 0:
        sys.exit(f"simorisc: {path}: bad entry offset {entry:#x} for text size {text_size:#x}")
    text_bytes = data[0x20:0x20 + text_size]
    data_bytes = data[0x20 + text_size:0x20 + text_size + data_size]
    if stack_size == 0:
        stack_size = DEFAULT_STACK_SIZE
    return text_bytes, data_bytes, entry, stack_size


CODE_VA = 0x00010000
DATA_VA = 0x00040000
ARGV_VA = 0x000A0000
STACK_TOP = 0x00200000


def init_cpu(cpu: CPU, text_bytes: bytes, data_bytes: bytes,
             entry: int, stack_size: int) -> None:
    """Allocate code/stack/(data) on `cpu` and prime its initial register state.
    Service objects (and the cross-CPU O5..O5+N-2 refs) are populated by
    System.populate_service_objects() after every CPU has been initialized."""
    text_size = len(text_bytes)
    data_size = len(data_bytes)

    code_ref  = cpu.alloc_object(text_size, type_tag=TAG_CODE,
                                 max_caps=CAP_R|CAP_X|CAP_C,
                                 init_bytes=text_bytes)
    stack_ref = cpu.alloc_object(stack_size, type_tag=TAG_STACK,
                                 max_caps=CAP_R|CAP_W|CAP_C)
    if data_size > 0:
        # Data REF stays R|C (CONTRACT §3) — OCAP and direct
        # OSB-through-O3 see the historical caps. But the MAPPING
        # gets R|W so VA-based stores to global variables work,
        # which C programs need (Dhrystone, the shell's cwd[],
        # anything with mutable file-scope data). The split is
        # intentional in OR: refs carry max-allowed caps, mappings
        # carry actually-exposed caps. UB programs that mutate
        # string literals via VA writes will silently succeed —
        # the MVP toolchain doesn't separate .rodata from .data.
        data_ref = cpu.alloc_object(data_size, type_tag=TAG_DATA,
                                    max_caps=CAP_R|CAP_C,
                                    init_bytes=data_bytes)
    else:
        data_ref = 0

    cpu.map_object(code_ref,  va=CODE_VA, offset=0,
                   length=text_size,  prot=CAP_R|CAP_X)
    cpu.map_object(stack_ref, va=STACK_TOP - stack_size, offset=0,
                   length=stack_size, prot=CAP_R|CAP_W)
    if data_size > 0:
        cpu.map_object(data_ref, va=DATA_VA, offset=0,
                       length=data_size, prot=CAP_R|CAP_W)

    cpu.set_opr(1, code_ref)
    cpu.set_opr(2, stack_ref)
    cpu.set_opr(3, data_ref)
    cpu.set_gpr(7, cpu.pid)            # PROCID by contract
    cpu.set_gpr(29, STACK_TOP - 16)    # SP
    cpu.set_gpr(30, 0)                 # FP
    cpu.set_gpr(31, 0)                 # RA

    cpu.pc = CODE_VA + entry
    cpu.next_pc = cpu.pc + 4
    cpu.active = True

    # Wrap the just-primed CPU state into a bootstrap Task struct so the
    # scheduler has a current_task to swap out when (if) the program
    # ever creates a child task and yields. Single-task programs never
    # touch this Task — they TaskExit, run loop sees no successor, and
    # tears the CPU down via TaskExitSignal as it always has.
    make_bootstrap_task(cpu, code_ref, stack_ref)


def populate_service_objects(system: System) -> None:
    """Allocate one service object per CPU (in multi-CPU mode), then hand
    each CPU references to its own (full caps in O4) and to the others
    (R+S only, in O5..O5+N-2 in PID-skipping-self order)."""
    if system.n_cpus < 2:
        return
    service_refs = []
    for cpu in system.cpus:
        ref = cpu.alloc_object(SERVICE_OBJ_SIZE, type_tag=TAG_SERVICE,
                               max_caps=CAP_R|CAP_W|CAP_S|CAP_V|CAP_C)
        service_refs.append(ref)

    for cpu in system.cpus:
        # O4 = my own service object, full caps.
        cpu.set_opr(4, service_refs[cpu.pid])
        # O5..O5+N-2 = other CPUs' services, R+S only.
        slot = 5
        for other_pid in range(system.n_cpus):
            if other_pid == cpu.pid:
                continue
            full_ref = service_refs[other_pid]
            weak = make_ref(generation=ref_generation(full_ref),
                            home=ref_home(full_ref),
                            index=ref_index(full_ref),
                            caps=CAP_R|CAP_S)
            cpu.set_opr(slot, weak)
            slot += 1


def snapshot_boot_state(cpu: CPU) -> None:
    """Record the post-init register state so handler dispatch can restore
    it before overlaying the SEND payload."""
    cpu.boot_state = {
        "gpr": list(cpu.gpr),
        "opr": list(cpu.opr),
        "code_va_base": CODE_VA,
    }


def reset_cpu(cpu: CPU) -> None:
    """Wipe `cpu` back to fresh boot state and re-run init from the saved
    boot args. Used by --reset-on-exit: when a non-leader CPU running the
    chunkboot loader hits TaskExit, we don't terminate the process; we
    re-init so the loader runs again and can boot the next program.

    Crossbar connection, PID, and trace settings persist across reset.

    The previous run's exit code (the byte the guest passed to
    TaskExit) is smuggled into the new R6 so the chunkboot loader
    can include it in its next "ready" announce — that's how
    linkbootd surfaces guest exit codes to the shell. R6 defaults
    to 0 on the very first boot (no prior run)."""
    args = cpu.reset_args   # set by main() once at startup
    prev_exit_code = cpu.exit_code if cpu.exit_code is not None else 0
    cpu.gpr            = [0] * 32
    cpu.opr            = [0] * 16
    cpu.hi             = 0
    cpu.lo             = 0
    cpu.pc             = 0
    cpu.next_pc        = 0
    cpu.descriptors    = [None]
    cpu.next_obj_idx   = 1
    cpu.free_indices   = []
    cpu.mappings       = []
    cpu.active         = False
    cpu.exit_code      = None
    cpu.inbox          = []
    cpu.requests       = []
    cpu.responses      = []
    cpu.boot_state     = None
    cpu.blocked_on     = None
    cpu.next_trans_id  = 0
    cpu.reset_at_time  = 0
    cpu.deferred_frees = []
    cpu.in_trap_handler = False
    cpu.yield_pending  = False
    cpu.current_task   = None
    cpu.tasks          = {}
    cpu.runnable       = []
    init_cpu(cpu, args["text"], args["data"], args["entry"], args["stack_size"])
    init_r4 = args.get("init_r4", 0)
    if init_r4:
        cpu.set_gpr(4, init_r4 & 0xFFFFFFFF)
    populate_self_service(cpu)
    install_external_services(cpu, args["services"])
    snapshot_boot_state(cpu)
    cpu.set_gpr(6, prev_exit_code & 0xFF)
    # Restore the boot-time privilege mode so a CPU rebooted under
    # --mode=user comes back as user, not the supervisor default.
    cpu.mode = getattr(cpu, "initial_mode", MODE_SUPERVISOR)


# ---------------------------------------------------------------------------
# Task scheduling (Volume VI Section 4)
# ---------------------------------------------------------------------------

def alloc_task_descriptor(cpu: CPU) -> int:
    """Reserve an object-table slot for a Task ref. The Task struct is
    stored separately in cpu.tasks; the descriptor exists so SEND, OREFLD,
    and other ref-bearing operations have something to identify the task
    by. Storage is empty (length 0) — the task lives in Python state."""
    ref = cpu.alloc_object(0, type_tag=TAG_TASK,
                           max_caps=CAP_R | CAP_V | CAP_C)
    return ref_index(ref)


def task_ref_for(cpu: CPU, task: 'Task', caps: int = CAP_R | CAP_V | CAP_C) -> int:
    """Manufacture a ref to `task` with the requested caps."""
    desc = cpu.descriptors[task.descriptor_idx]
    return make_ref(generation=desc.generation, home=cpu.pid,
                    index=task.descriptor_idx, caps=caps)


def save_cpu_to_task(cpu: CPU, task: 'Task') -> None:
    """Copy the running task's CPU-resident state out to its Task struct
    in preparation for a context switch. Called on the *outgoing* task
    just before load_task_to_cpu paints in the incoming one."""
    task.gpr          = cpu.gpr.copy()
    task.opr          = cpu.opr.copy()
    task.hi           = cpu.hi
    task.lo           = cpu.lo
    task.pc           = cpu.pc
    task.next_pc      = cpu.next_pc
    task.mode         = cpu.mode
    task.saved_mode   = cpu.saved_mode
    task.saved_pc     = cpu.saved_pc
    task.cause_reg    = cpu.cause_reg
    task.badvaddr_reg = cpu.badvaddr_reg
    task.mappings     = list(cpu.mappings)
    task.blocked_on   = cpu.blocked_on


def load_task_to_cpu(cpu: CPU, task: 'Task') -> None:
    """Paint the incoming task's saved state onto the CPU. Mirror of
    save_cpu_to_task; together they implement the context switch."""
    cpu.gpr          = task.gpr.copy()
    cpu.opr          = task.opr.copy()
    cpu.hi           = task.hi
    cpu.lo           = task.lo
    cpu.pc           = task.pc
    cpu.next_pc      = task.next_pc
    cpu.mode         = task.mode
    cpu.saved_mode   = task.saved_mode
    cpu.saved_pc     = task.saved_pc
    cpu.cause_reg    = task.cause_reg
    cpu.badvaddr_reg = task.badvaddr_reg
    cpu.mappings     = list(task.mappings)
    cpu.blocked_on   = task.blocked_on


def context_switch(cpu: CPU, next_task: 'Task') -> None:
    """Swap the running task. The outgoing task's state is saved to its
    Task struct; the incoming task's state is painted onto the CPU. The
    caller is responsible for having set the outgoing task's state field
    appropriately (RUNNABLE for yield, EXITED for exit) and for queuing
    it back on cpu.runnable if it should run again. The CALL dispatch
    site is told to skip its post-call PC advance (the new task's PC is
    already where it should be)."""
    outgoing = cpu.current_task
    if outgoing is not None:
        save_cpu_to_task(cpu, outgoing)
    load_task_to_cpu(cpu, next_task)
    next_task.state = TASK_STATE_RUNNING
    cpu.current_task = next_task
    cpu._call_redirected_pc = True


def pick_next_runnable(cpu: CPU) -> Optional['Task']:
    """Pop the next runnable task from the round-robin queue, or return
    None if the queue is empty."""
    return cpu.runnable.pop(0) if cpu.runnable else None


def make_bootstrap_task(cpu: CPU, code_ref: int, stack_ref: int) -> 'Task':
    """After init_cpu has primed the CPU's register file and mappings,
    capture them into a Task struct so the scheduler has something to
    save out when a context switch eventually happens. The CPU and the
    bootstrap task share their initial state by construction; the Task
    struct is the home of that state once a context switch occurs."""
    task = Task(descriptor_idx=alloc_task_descriptor(cpu),
                code_ref=code_ref, stack_ref=stack_ref,
                state=TASK_STATE_RUNNING)
    save_cpu_to_task(cpu, task)
    cpu.tasks[task.descriptor_idx] = task
    cpu.current_task = task
    return task


# ---------------------------------------------------------------------------
# Firmware primitive dispatch
# ---------------------------------------------------------------------------

def primitive_TaskCreate(cpu: CPU) -> None:
    """Create a task with its own address space and prime its register
    state. The new task starts in the NEW state — TaskResume moves it
    onto the runnable queue. Standard layout: code at CODE_VA (R+X),
    stack at STACK_TOP (R+W), data at DATA_VA (R+W) when O3 is
    non-null, and an args/argv buffer at ARGV_VA (R-only) when O4 is
    non-null — same VAs as init_cpu so pcc-generated code that
    assumes flat addresses Just Works in the child."""
    code_ref  = cpu.get_opr(1)
    stack_ref = cpu.get_opr(2)
    data_ref  = cpu.get_opr(3)              # optional; 0 = no data segment
    args_ref  = cpu.get_opr(4)              # optional; 0 = no args buffer
    entry     = cpu.get_gpr(4) & 0xFFFFFFFF
    init_r4   = cpu.get_gpr(5) & 0xFFFFFFFF
    if entry & 0x80000000:
        entry -= 0x100000000

    if code_ref == 0 or stack_ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if ref_home(code_ref) != cpu.pid or ref_home(stack_ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    if (ref_caps(code_ref) & CAP_X) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if (ref_caps(stack_ref) & (CAP_R | CAP_W)) != (CAP_R | CAP_W):
        cpu.set_gpr(2, ERR_EPERM); return
    code_idx, stack_idx = ref_index(code_ref), ref_index(stack_ref)
    for idx in (code_idx, stack_idx):
        if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None \
                or not cpu.descriptors[idx].live:
            cpu.set_gpr(2, ERR_ESTALE); return
    code_desc, stack_desc = cpu.descriptors[code_idx], cpu.descriptors[stack_idx]
    if code_desc.generation != ref_generation(code_ref) \
            or stack_desc.generation != ref_generation(stack_ref):
        cpu.set_gpr(2, ERR_ESTALE); return
    if entry < 0 or entry >= code_desc.length:
        cpu.set_gpr(2, ERR_EINVAL); return

    data_idx, data_desc = None, None
    if data_ref != 0:
        if ref_home(data_ref) != cpu.pid:
            cpu.set_gpr(2, ERR_EREMOTE); return
        if (ref_caps(data_ref) & CAP_R) == 0:
            cpu.set_gpr(2, ERR_EPERM); return
        data_idx = ref_index(data_ref)
        if data_idx >= len(cpu.descriptors) or cpu.descriptors[data_idx] is None \
                or not cpu.descriptors[data_idx].live:
            cpu.set_gpr(2, ERR_ESTALE); return
        data_desc = cpu.descriptors[data_idx]
        if data_desc.generation != ref_generation(data_ref):
            cpu.set_gpr(2, ERR_ESTALE); return

    args_idx, args_desc = None, None
    if args_ref != 0:
        if ref_home(args_ref) != cpu.pid:
            cpu.set_gpr(2, ERR_EREMOTE); return
        if (ref_caps(args_ref) & CAP_R) == 0:
            cpu.set_gpr(2, ERR_EPERM); return
        args_idx = ref_index(args_ref)
        if args_idx >= len(cpu.descriptors) or cpu.descriptors[args_idx] is None \
                or not cpu.descriptors[args_idx].live:
            cpu.set_gpr(2, ERR_ESTALE); return
        args_desc = cpu.descriptors[args_idx]
        if args_desc.generation != ref_generation(args_ref):
            cpu.set_gpr(2, ERR_ESTALE); return

    task = Task(descriptor_idx=alloc_task_descriptor(cpu),
                code_ref=code_ref, stack_ref=stack_ref,
                state=TASK_STATE_NEW)
    task.mappings = [
        (CODE_VA, CODE_VA + code_desc.length, code_idx, 0,
         CAP_R | CAP_X),
        (STACK_TOP - stack_desc.length, STACK_TOP, stack_idx, 0,
         CAP_R | CAP_W),
    ]
    if data_idx is not None:
        # Match init_cpu: data is mapped R+W so guests can mutate
        # globals (the ref's caps may still be R-only — the
        # ref-vs-mapping cap split is intentional, see init_cpu).
        task.mappings.append(
            (DATA_VA, DATA_VA + data_desc.length, data_idx, 0,
             CAP_R | CAP_W))
    if args_idx is not None:
        # Argv buffer mapped R-only at ARGV_VA. Programs that want
        # their args grab them via the libc helper which dereferences
        # this VA. Programs that don't care just don't map and the
        # VA stays unmapped — accessing it would trap.
        task.mappings.append(
            (ARGV_VA, ARGV_VA + args_desc.length, args_idx, 0,
             CAP_R))
    task.pc      = (CODE_VA + entry) & 0xFFFFFFFF
    task.next_pc = (task.pc + 4)     & 0xFFFFFFFF
    # Child inherits the parent's object registers — that's how the
    # parent passes service refs (terminal, hostfsd, shared scratch)
    # without a separate handoff mechanism. Vol VI §4.1 doesn't pin
    # the child's initial OR state, so inheriting matches the typical
    # fork-style hand-off and matches snapshot_boot_state's pattern
    # for handler dispatch. O0 stays the null reference. Supervisor
    # that wants a clean slate can always overwrite afterwards.
    task.opr     = list(cpu.opr)
    task.opr[0]  = 0
    task.gpr[4]  = init_r4
    task.gpr[7]  = cpu.pid                    # PROCID by contract
    task.gpr[29] = STACK_TOP - 16             # SP
    # Inherit the parent's privilege mode by default; supervisor can
    # demote a child by SCTRL-ing the new task's saved state via... well,
    # there's no primitive for that yet. Today: same mode as parent.
    task.mode    = cpu.mode
    task.saved_mode = cpu.mode

    cpu.tasks[task.descriptor_idx] = task
    cpu.set_opr(1, task_ref_for(cpu, task))
    cpu.set_gpr(2, ERR_OK)


def _resolve_task_arg(cpu: CPU, require_v: bool = True) -> Optional['Task']:
    """Validate O1 as a task ref, return its Task or None (with R2 set).
    `require_v=False` skips the V-capability check — TaskWait/TaskQuery
    take a task ref of any caps per Volume VI §4.1."""
    ref = cpu.get_opr(1)
    if ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return None
    if ref_home(ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return None
    if require_v and (ref_caps(ref) & CAP_V) == 0:
        cpu.set_gpr(2, ERR_EPERM); return None
    idx = ref_index(ref)
    desc = cpu.descriptors[idx] if 0 < idx < len(cpu.descriptors) else None
    if desc is None or not desc.live or desc.generation != ref_generation(ref):
        cpu.set_gpr(2, ERR_ESTALE); return None
    if desc.type_tag != TAG_TASK or idx not in cpu.tasks:
        cpu.set_gpr(2, ERR_EINVAL); return None
    return cpu.tasks[idx]


def primitive_TaskResume(cpu: CPU) -> None:
    task = _resolve_task_arg(cpu)
    if task is None:
        return
    if task.state == TASK_STATE_RUNNING or task.state == TASK_STATE_EXITED:
        cpu.set_gpr(2, ERR_EBUSY); return
    if task.state in (TASK_STATE_RUNNABLE,):
        cpu.set_gpr(2, ERR_OK); return  # already queued; idempotent
    task.state = TASK_STATE_RUNNABLE
    cpu.runnable.append(task)
    cpu.set_gpr(2, ERR_OK)


def primitive_TaskSuspend(cpu: CPU) -> None:
    task = _resolve_task_arg(cpu)
    if task is None:
        return
    if task.state == TASK_STATE_EXITED:
        cpu.set_gpr(2, ERR_EINVAL); return
    if task.state == TASK_STATE_RUNNABLE:
        try:
            cpu.runnable.remove(task)
        except ValueError:
            pass
    task.state = TASK_STATE_SUSPENDED
    if task is cpu.current_task:
        # Self-suspend: pick another runnable. If none, we'd deadlock;
        # report EBUSY rather than wedge the CPU silently. Real OS would
        # pull from a wait queue / interrupt.
        nxt = pick_next_runnable(cpu)
        if nxt is None:
            cpu.set_gpr(2, ERR_EBUSY); return
        cpu.set_gpr(2, ERR_OK)
        # The suspended task sees R2=OK on resume.
        save_cpu_to_task(cpu, task)
        load_task_to_cpu(cpu, nxt)
        nxt.state = TASK_STATE_RUNNING
        cpu.current_task = nxt
        cpu._call_redirected_pc = True
        return
    cpu.set_gpr(2, ERR_OK)


def primitive_TaskYield(cpu: CPU, faulting_pc: int) -> None:
    """Voluntarily surrender the rest of the quantum. Round-robin: pop
    the next runnable, push the current onto the back of the queue, swap
    state. If nobody else is runnable, this is a no-op.

    When called from inside a trap handler (cpu.in_trap_handler set
    by deliver_trap), an immediate context_switch would save the
    handler's mid-execution state into the outgoing task struct and
    lose the trapped task's resume image. So instead we set
    yield_pending and return; ERET honors it on the way out, after
    reflecting any handler-side SCTRL of EPC/STATUS into the
    outgoing task's resume image. This is the deferred-yield idiom
    that makes timer-driven preemption safe."""
    if cpu.in_trap_handler:
        cpu.yield_pending = True
        cpu.set_gpr(2, ERR_OK)
        return

    nxt = pick_next_runnable(cpu)
    cur = cpu.current_task
    if nxt is None or nxt is cur:
        cpu.set_gpr(2, ERR_OK)
        return
    # The yielding task resumes at the instruction after the CALL. Bump
    # PC before save so its restored state lands there, not on the CALL.
    cpu.pc      = (faulting_pc + 4) & 0xFFFFFFFF
    cpu.next_pc = (cpu.pc + 4)      & 0xFFFFFFFF
    cpu.set_gpr(2, ERR_OK)            # what `cur` will see on resume
    cur.state = TASK_STATE_RUNNABLE
    cpu.runnable.append(cur)
    context_switch(cpu, nxt)


def primitive_TaskCurrent(cpu: CPU) -> None:
    cur = cpu.current_task
    if cur is None:
        cpu.set_opr(1, 0); cpu.set_gpr(2, ERR_OK); return
    cpu.set_opr(1, task_ref_for(cpu, cur))
    cpu.set_gpr(2, ERR_OK)


def _wake_waiters(cpu: CPU, exiting: 'Task') -> None:
    """Move every task parked on `exiting` from BLOCKED to RUNNABLE,
    seeding its R2/R3 (visible after context-switch back) with the
    TaskWait return values. Called from primitive_TaskExit before
    pick_next_runnable so wakeups are first-class scheduler citizens.

    Phase 45d: also drains exiting.remote_waiters by sending a
    TASK_WAIT_RESP (status=ERR_OK, exit_code) for each pending
    remote TaskWait request. The originating CPU's
    _try_unblock_task_wait will deliver into its waiter's R2/R3 and
    advance PC."""
    for w in exiting.waiters:
        if w.state != TASK_STATE_BLOCKED:
            continue
        w.gpr[2] = ERR_OK
        w.gpr[3] = exiting.exit_code & 0xFF
        w.state  = TASK_STATE_RUNNABLE
        cpu.runnable.append(w)
    exiting.waiters = []
    # Remote waiters: build + send a TASK_WAIT_RESP for each. The
    # exit_code is what the local waiters got above. cpu.system is
    # always non-None for tasks that arrived via TASK_WAIT_REQ
    # (single-CPU sim has no crossbar route in), but guard anyway
    # for forward compatibility / unit tests.
    if exiting.remote_waiters and cpu.system is not None:
        for (waiter_pid, trans_id) in exiting.remote_waiters:
            cpu.system.crossbar.send_packet(build_task_wait_resp(
                cpu.pid, waiter_pid, trans_id,
                ERR_OK, exiting.exit_code & 0xFF))
        exiting.remote_waiters = []


def primitive_TaskExit(cpu: CPU) -> None:
    """Terminate the calling task. Wake any tasks waiting on it, then
    context-switch to the next runnable. If nothing is runnable BUT
    there are still BLOCKED tasks (e.g., a shell parked in
    RecvQueuePoll waiting on a key), park the CPU on a sentinel
    BlockedOnExitWait so the run loop's _wake_blocked_tasks can
    eventually promote one and the blocked-but-runnable branch can
    pick it up. Only if no runnable AND no blocked tasks do we tear
    down the CPU via TaskExitSignal — that's the genuinely-finished
    case where there's nobody left to run."""
    code = cpu.get_gpr(4) & 0xFF
    cur = cpu.current_task
    if cur is not None:
        cur.state = TASK_STATE_EXITED
        cur.exit_code = code
        _wake_waiters(cpu, cur)
    nxt = pick_next_runnable(cpu)
    if nxt is not None:
        context_switch(cpu, nxt)
        return
    # Are there any tasks that might yet wake?
    has_blocked = any(t.state == TASK_STATE_BLOCKED for t in cpu.tasks.values())
    if has_blocked:
        # Park the CPU. The blocked-but-runnable branch in run() will
        # context_switch into the woken task. Until then, _process_requests
        # and _wake_blocked_tasks keep firing every loop tick.
        cpu.blocked_on = BlockedOnExitWait()
        return
    raise TaskExitSignal(code)


def primitive_TaskKill(cpu: CPU) -> None:
    """Volume VI §4.1 #0x00A. Externally terminate the named task. The
    target moves to EXITED with the supplied exit code, drops out of the
    runnable queue, releases any pending IPC wait, and wakes anyone
    blocked in TaskWait on it. The caller (a different task on the same
    CPU) continues normally — no context switch.

    Killing the calling task itself is rejected with EINVAL — that's
    what TaskExit is for. Killing an already-EXITED task is a no-op
    (idempotent, so a shell can `kill` a task that just finished racing
    a `wait` without erroring).

    Phase 45d: remote refs route via TASK_KILL_REQ — see
    _try_unblock_task_kill for the response side."""
    o1 = cpu.get_opr(1)
    if o1 != 0 and cpu.system is not None and ref_home(o1) != cpu.pid:
        code = cpu.get_gpr(4) & 0xFF
        trans_id = cpu.next_trans_id & 0xFFFF
        cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
        cpu.system.crossbar.send_packet(build_task_kill_req(
            cpu.pid, ref_home(o1), trans_id, o1, code))
        raise BlockedOnTaskKill(trans_id)

    target = _resolve_task_arg(cpu)
    if target is None:
        return
    if target is cpu.current_task:
        cpu.set_gpr(2, ERR_EINVAL); return
    if target.state == TASK_STATE_EXITED:
        cpu.set_gpr(2, ERR_OK); return
    code = cpu.get_gpr(4) & 0xFF
    # Drop the target from anywhere it might be parked. RUNNABLE tasks
    # live in cpu.runnable; BLOCKED tasks have a blocked_on saved in
    # their Task struct (Phase 36) — clearing it ensures a stale
    # _try_unblock attempt can't fire on a corpse if the queue/response
    # ever gets satisfied later.
    if target.state == TASK_STATE_RUNNABLE:
        try:
            cpu.runnable.remove(target)
        except ValueError:
            pass
    target.blocked_on = None
    target.state      = TASK_STATE_EXITED
    target.exit_code  = code
    _wake_waiters(cpu, target)
    cpu.set_gpr(2, ERR_OK)


def primitive_TaskQuery(cpu: CPU) -> None:
    """Volume VI §4.2 #0x008. Return summary information about a task:
    its state, the processor it lives on, and its exit code if it
    terminated. Non-blocking from the caller's POV in the local case;
    in the remote case the CPU still suspends at the CALL while the
    home formulates the response (typically a single tick), but
    architecturally it's still a one-shot query.

    Args:
      O1: task object reference (no V cap required, like TaskWait).

    Returns:
      R2: status (OK / EFAULT / EREMOTE / EPERM / ESTALE / EINVAL).
      R3: packed state word (low 8 bits = state per TASK_STATE_*,
          next 8 bits = processor id, upper 16 bits = exit code if
          state == TASK_STATE_EXITED, else 0).

    Phase 45d: remote refs route via TASK_QUERY_REQ — see
    _try_unblock_task_query for the response side."""
    o1 = cpu.get_opr(1)
    if o1 != 0 and cpu.system is not None and ref_home(o1) != cpu.pid:
        trans_id = cpu.next_trans_id & 0xFFFF
        cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
        cpu.system.crossbar.send_packet(build_task_query_req(
            cpu.pid, ref_home(o1), trans_id, o1))
        raise BlockedOnTaskQuery(trans_id)

    target = _resolve_task_arg(cpu, require_v=False)
    if target is None:
        return
    state = target.state & 0xFF
    proc  = cpu.pid & 0xFF
    code  = (target.exit_code or 0) & 0xFFFF \
            if target.state == TASK_STATE_EXITED else 0
    packed = state | (proc << 8) | (code << 16)
    cpu.set_gpr(2, ERR_OK)
    cpu.set_gpr(3, packed)


def primitive_TaskWait(cpu: CPU, faulting_pc: int) -> None:
    """Block the calling task until O1 has terminated. The exit code is
    returned in R3 (Volume VI §4.1). If O1 is already EXITED the call
    returns immediately.

    Phase 45d: when O1's home isn't this CPU, queue a TASK_WAIT_REQ on
    the home and raise BlockedOnTaskWait — the CALL stays at PC until
    the matching TASK_WAIT_RESP arrives, then _try_unblock_task_wait
    delivers status into R2 and exit_code into R3 and advances PC."""
    o1 = cpu.get_opr(1)
    if o1 != 0 and cpu.system is not None and ref_home(o1) != cpu.pid:
        # Remote target. Issuer-side fast-fail: ref must have V cap?
        # No — TaskWait is require_v=False per Vol VI §4.1, same as the
        # local path. Home does the descriptor check via
        # _resolve_remote_task. Issue the request and block.
        trans_id = cpu.next_trans_id & 0xFFFF
        cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
        cpu.system.crossbar.send_packet(build_task_wait_req(
            cpu.pid, ref_home(o1), trans_id, o1))
        raise BlockedOnTaskWait(trans_id)

    target = _resolve_task_arg(cpu, require_v=False)
    if target is None:
        return
    if target.state == TASK_STATE_EXITED:
        cpu.set_gpr(2, ERR_OK)
        cpu.set_gpr(3, target.exit_code & 0xFF)
        return
    cur = cpu.current_task
    if cur is None or cur is target:
        cpu.set_gpr(2, ERR_EINVAL); return
    # The waiter resumes at the instruction after the CALL. R2/R3 will
    # be overwritten by _wake_waiters when the target exits, so we don't
    # set them here. Bump PC before save so that's where it lands on
    # resume.
    cpu.pc      = (faulting_pc + 4) & 0xFFFFFFFF
    cpu.next_pc = (cpu.pc + 4)      & 0xFFFFFFFF
    cur.state = TASK_STATE_BLOCKED
    target.waiters.append(cur)
    nxt = pick_next_runnable(cpu)
    if nxt is not None:
        context_switch(cpu, nxt)
        return
    # No other runnable task — but the target itself, or some other
    # task, may yet wake on an external event (a wire packet, a key,
    # a remote response). Park the CPU idle: save `cur`'s state to
    # its Task struct (so when the target's eventual TaskExit fires
    # _wake_waiters, the gpr[2]=OK / gpr[3]=exit_code writes land in
    # the right place to be loaded back), set current_task=None to
    # signal "no task is running," and arm BlockedOnExitWait so the
    # run loop's idle-with-blocked-tasks branch keeps the CPU alive
    # to service in-flight wire requests.
    #
    # When `cur` later becomes RUNNABLE (added to cpu.runnable by
    # _wake_waiters), the run loop's blocked-but-runnable branch
    # picks it up: cur was None so the "nxt is not cur" condition
    # triggers a clean load_task_to_cpu, which paints cur's saved
    # gpr/pc/blocked_on (=None at save time, before we armed the
    # sentinel) onto the CPU and resumes past the CALL.
    #
    # (Phase 48 bugfix: the previous "return EBUSY when no other
    # runnable" policy was incorrect — TaskWait isn't deadlocked just
    # because the CPU is currently idle. login.orx hit this when its
    # task_wait(shell) ran AFTER the shell had already blocked in
    # term_getkey: pick_next_runnable was empty because shell was
    # BLOCKED, so login got EBUSY back, fell through orx_unload, and
    # spun the welcome-banner loop instead of waiting for shell to
    # exit.)
    has_blocked = any(t.state == TASK_STATE_BLOCKED for t in cpu.tasks.values())
    if has_blocked:
        save_cpu_to_task(cpu, cur)
        cpu.current_task = None
        cpu.blocked_on = BlockedOnExitWait()
        return
    # Genuinely nothing can wake — preserve the original EBUSY
    # semantics so a single-task program waiting on a never-runnable
    # peer gets a useful error.
    target.waiters.remove(cur)
    cur.state = TASK_STATE_RUNNING
    cpu.pc      = faulting_pc & 0xFFFFFFFF
    cpu.next_pc = (faulting_pc + 4) & 0xFFFFFFFF
    cpu.set_gpr(2, ERR_EBUSY)

def primitive_ReadCycles(cpu: CPU) -> None:
    cpu.set_gpr(2, 0)
    cpu.set_gpr(3, cpu.cycles & 0xFFFFFFFF)

def primitive_TimeNow(cpu: CPU) -> None:
    """Vol VI #0x400. Returns microseconds elapsed since the System's
    boot_time, low 32 bits in R3. The spec puts the high 32 bits in
    the side-channel buffer (Vol VI §11), but this firmware doesn't
    yet implement the side-channel; programs that need a 64-bit span
    will have to track epoch wraps themselves. 32-bit microseconds
    wrap at ~71.6 minutes — fine for benchmarks and typical
    interactive use."""
    if cpu.system is None:
        cpu.set_gpr(2, ERR_OK)
        cpu.set_gpr(3, 0)
        return
    elapsed = time.time() - cpu.system.boot_time
    micros = int(elapsed * 1_000_000) & 0xFFFFFFFFFFFFFFFF
    cpu.set_gpr(2, ERR_OK)
    cpu.set_gpr(3, micros & 0xFFFFFFFF)
    # High 32 bits would go to the side-channel; not implemented.

def primitive_ClockResolution(cpu: CPU) -> None:
    """Vol VI #0x410. Returns ticks per second of the clock TimeNow
    counts. Picked to be 1_000_000 (microseconds) — a 1980s-Unix-
    typical value, comfortably finer than anything Dhrystone or a
    cmd-line shell needs to measure."""
    cpu.set_gpr(2, ERR_OK)
    cpu.set_gpr(3, 1_000_000)

def primitive_ConsoleWrite(cpu: CPU, faulting_pc: int) -> None:
    o1   = cpu.get_opr(1)
    off  = cpu.get_gpr(4)
    n    = cpu.get_gpr(5)

    if o1 == 0:
        cpu.set_gpr(2, ERR_EFAULT); cpu.set_gpr(3, 0); return
    home = ref_home(o1)
    if cpu.system is None or home == cpu.pid:
        descriptors = cpu.descriptors
    else:
        descriptors = cpu.system.cpus[home].descriptors
    idx = ref_index(o1)
    if idx >= len(descriptors) or descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
    desc = descriptors[idx]
    if not desc.live or desc.generation != ref_generation(o1):
        cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
    if (ref_caps(o1) & CAP_R) == 0:
        cpu.set_gpr(2, ERR_EPERM);  cpu.set_gpr(3, 0); return
    end = off + n
    if end < off or end > desc.length:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
    payload = bytes(desc.storage[off:off+n])
    sys.stdout.buffer.write(payload)
    sys.stdout.flush()
    cpu.set_gpr(2, ERR_OK); cpu.set_gpr(3, n)

def primitive_ObjAlloc(cpu: CPU) -> None:
    length = cpu.get_gpr(4)
    type_tag = cpu.get_gpr(5) & 0xFFFF
    init_caps = cpu.get_gpr(6) & 0xFF
    if length == 0 or length > (1 << 24):
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_opr(1, 0); return
    try:
        ref = cpu.alloc_object(length, type_tag=type_tag, max_caps=init_caps)
    except Exception:
        cpu.set_gpr(2, ERR_ENOMEM); cpu.set_opr(1, 0); return
    cpu.set_gpr(2, ERR_OK); cpu.set_opr(1, ref)

def primitive_ObjAllocFramebuffer(cpu: CPU) -> None:
    """Phase 60 — allocate a TAG_FRAMEBUFFER object backed by a host
    display surface (when --display tk is on; just a plain bytearray
    otherwise).  The WM normally writes pixels into this object via
    ObjStoreBytes; the host display worker mirrors the bytes into a
    Tk PhotoImage with no wire round-trip — replaces the per-pixel /
    per-row ObjStoreBytes-to-oriscterm path with a same-CPU store.

    Inputs:
      R4 = width  (pixels, 1..4096)
      R5 = height (pixels, 1..4096)
      R6 = caps mask (typically R|W|C for the WM's own use)
      R7 = flags
            bit 0: FB_FLAG_OFFSCREEN — skip host display worker
                   registration.  Used for per-window backing stores
                   that the WM composites onto a separate "screen"
                   framebuffer; we don't want a Tk window per window.
                   Default 0 = mirror to display (Phase-60-step-1
                   behaviour).

    Outputs:
      R2 = status (ERR_OK / ERR_EINVAL / ERR_ENOMEM)
      O1 = ref to the new object on success, null on failure

    Object size = width × height bytes (1 byte per palette index,
    matching the existing oriscterm framebuffer convention).  The
    palette interpretation lives entirely in the host display worker;
    the firmware only sees raw bytes. """
    width  = cpu.get_gpr(4) & 0xFFFF
    height = cpu.get_gpr(5) & 0xFFFF
    init_caps = cpu.get_gpr(6) & 0xFF
    flags = cpu.get_gpr(7)
    offscreen = bool(flags & 0x1)
    if width == 0 or height == 0 or width > 4096 or height > 4096:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_opr(1, 0); return
    size = width * height
    try:
        ref = cpu.alloc_object(size, type_tag=TAG_FRAMEBUFFER,
                               max_caps=init_caps)
    except Exception:
        cpu.set_gpr(2, ERR_ENOMEM); cpu.set_opr(1, 0); return
    idx = ref_index(ref)
    desc = cpu.descriptors[idx]
    desc.fb_width  = width
    desc.fb_height = height
    desc.fb_dirty  = True   # initial paint
    # Notify the host display worker (if any) so it can create a Tk
    # window for this framebuffer.  Headless / no-display runs leave
    # the object as a plain bytearray; ObjStoreBytes still works.
    # OFFSCREEN flag skips this — per-window backing stores composite
    # onto a separate screen FB and shouldn't own their own Tk window.
    if not offscreen:
        worker = getattr(cpu, "display_worker", None)
        if worker is not None:
            worker.register_framebuffer(cpu, idx, desc)
    cpu.set_gpr(2, ERR_OK); cpu.set_opr(1, ref)


# 'WMF1' — magic word at the head of a self-describing WM font object
# (the extended ObjBlitGlyphs mode below).  Never collides with a legacy
# font_8x16-style table: byte 0 there is glyph-row data (the space glyph
# is all-zero), never 0x57.
FONT_MAGIC = 0x574D4631


def _font_u16(storage, off):
    return (storage[off] << 8) | storage[off + 1]


def _blit_glyphs_extended(cpu, fb_desc, font_desc, text_desc,
                          r4, n_chars, fg, bg, transparent,
                          font_off, text_off, clip_lo=0, clip_hi=0):
    """Extended ObjBlitGlyphs render path — proportional, pixel-positioned
    chrome.  The font (O2) is a self-describing object the WM's font
    manager bakes (tools/gen_wm_font.py):

        off  0  magic 'WMF1'        (u32, big-endian)
        off  4  cell_w              (u16) glyph bounding-box width, px
        off  6  cell_h              (u16) rows per glyph
        off  8  codepoint_base      (u16) first codepoint in the face
        off 10  n_glyphs            (u16)
        off 12  flags               (u16) bit0 = proportional (advisory)
        off 14  bytes_per_row       (u16) = ceil(cell_w / 8)
        off 16  width_table[n_glyphs]    (u8 advance px each; padded to a
                                          4-byte boundary)
        ...     bitmaps[n_glyphs * bytes_per_row * cell_h]  (u8, MSB-first)

    Per-glyph advance comes from width_table (monospace faces just store a
    uniform width).  R4 packs an absolute top-left PIXEL position, not a
    cell index.  When `transparent`, only set (fg) pixels are written, so
    a pre-filled background (e.g. a title bar) shows through the gaps
    between proportional glyphs."""
    font_storage = font_desc.storage
    flen = font_desc.length
    if font_off < 0 or font_off + 16 > flen:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
    magic = ((font_storage[font_off]     << 24) |
             (font_storage[font_off + 1] << 16) |
             (font_storage[font_off + 2] << 8)  |
              font_storage[font_off + 3])
    if magic != FONT_MAGIC:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
    cell_w   = _font_u16(font_storage, font_off + 4)
    cell_h   = _font_u16(font_storage, font_off + 6)
    base     = _font_u16(font_storage, font_off + 8)
    n_glyphs = _font_u16(font_storage, font_off + 10)
    # flags  = _font_u16(font_storage, font_off + 12)  # bit0 proportional
    bpr      = _font_u16(font_storage, font_off + 14)
    if cell_w <= 0 or cell_h <= 0 or bpr <= 0:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    widths_off  = font_off + 16
    # width_table is padded up to a 4-byte boundary so the generator can
    # emit the whole blob as uint32 .word data (pcc-orisc .ascii bug).
    bitmaps_off = widths_off + ((n_glyphs + 3) & ~3)
    glyph_bytes = bpr * cell_h
    if (widths_off + n_glyphs > flen or
            bitmaps_off + n_glyphs * glyph_bytes > flen):
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    text_end = text_off + n_chars
    if text_off < 0 or text_end > text_desc.length:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    fb_w = fb_desc.fb_width
    fb_h = fb_desc.fb_height
    fb_storage   = fb_desc.storage
    text_storage = text_desc.storage

    # Optional clip rectangle (from R8/R9), so a client compositing into a
    # sub-surface (e.g. the WM drawing content-pane text) cannot scribble onto
    # window chrome above/below the pane.  lo = (x0<<16)|y0, hi = (x1<<16)|y1 in
    # this FB's pixels; hi == 0 (x1 == y1 == 0) means "no clip" -> the whole FB,
    # which is the legacy / chrome path, byte-identical to before.
    cx1 = (clip_hi >> 16) & 0xFFFF
    cy1 =  clip_hi        & 0xFFFF
    if cx1 == 0 and cy1 == 0:
        cx0, cy0, cx1, cy1 = 0, 0, fb_w, fb_h
    else:
        cx0 = (clip_lo >> 16) & 0xFFFF
        cy0 =  clip_lo        & 0xFFFF
        if cx1 > fb_w: cx1 = fb_w
        if cy1 > fb_h: cy1 = fb_h

    pen_x = (r4 >> 16) & 0xFFFF
    pen_y = r4 & 0xFFFF
    rendered = 0
    for g in range(n_chars):
        if pen_x >= cx1:
            break
        ch = text_storage[text_off + g]
        gi = ch - base
        if gi < 0 or gi >= n_glyphs:
            pen_x += cell_w          # unknown glyph: blank cell, default advance
            continue
        advance = font_storage[widths_off + gi]
        gbase = bitmaps_off + gi * glyph_bytes
        for r in range(cell_h):
            row_y = pen_y + r
            if row_y < cy0 or row_y >= cy1:
                continue
            row_off  = gbase + r * bpr
            row_base = row_y * fb_w
            for col in range(cell_w):
                px = pen_x + col
                if px < cx0:
                    continue
                if px >= cx1:
                    break
                byte = font_storage[row_off + (col >> 3)]
                if (byte >> (7 - (col & 7))) & 1:
                    fb_storage[row_base + px] = fg
                elif not transparent:
                    fb_storage[row_base + px] = bg
        pen_x += advance
        rendered += 1

    fb_desc.fb_dirty = True
    cpu.set_gpr(2, ERR_OK)
    cpu.set_gpr(3, rendered)


def primitive_ObjBlitGlyphs(cpu: CPU) -> None:
    """Phase 60 step 4 — bulk-render a strip of glyphs into a
    TAG_FRAMEBUFFER.  Replaces oriscwm's flush_strip inner loop
    (per-pixel decode + 16 ObjStoreBytes per strip) with a single
    Python-side render — cuts the rendering cost of one 80-char strip
    from ~80K simulated WM instructions to one firmware-call's worth.

    Two modes, selected by R5 bit 31:

    LEGACY (bit 31 clear) — the terminal-body fast path, unchanged.
    Models a 1bpp-source blitter device: glyph bytes are 8 pixels
    each, MSB-first; output pixels are palette indices (fg if bit
    set, bg otherwise).  The font is laid out as 16 bytes per
    glyph (1 byte per row), 95 glyphs starting at codepoint 32 —
    same shape oriscwm's font_8x16[] uses.

      O1 = framebuffer ref      (TAG_FRAMEBUFFER, must be local)
      O2 = font ref             (any tag with R caps, must be local;
                                 for oriscwm this is its boot data
                                 ref O15)
      O3 = text ref             (any tag with R caps, must be local;
                                 for oriscwm this is its boot stack O11)
      R4 = packed (cell_x << 16) | cell_y     — destination cell
                                                position in the FB
                                                (cell = 8x16 px)
      R5 = packed (n_chars << 16) | (fg << 8) | bg — render shape
      R6 = font_off                            — byte offset of font
                                                table in O2
      R7 = text_off                            — byte offset of glyph
                                                bytes in O3

    EXTENDED (bit 31 set) — proportional, pixel-positioned chrome for
    the WM's OPEN LOOK font manager.  O2 is a self-describing font
    object (see _blit_glyphs_extended); R4 packs an absolute pixel
    position; advance widths come from the font's own width_table.

      R5 = (1<<31) | (transparent<<30) | (n_chars<<16) | (fg<<8) | bg
      R4 = packed (pixel_x << 16) | pixel_y

    Outputs (both modes):
      R2 = status (ERR_OK / ERR_EFAULT / ERR_EPERM / ERR_EREMOTE /
                   ERR_ESTALE / ERR_EINVAL)
      R3 = number of glyphs actually rendered (<= n_chars; clipped
           to the framebuffer)

    Off-screen rows / cells drop silently.  In legacy mode, non-printable
    bytes (ch < 32 or ch > 126) render as a space.  Caller is responsible
    for stashing source data in O11/O15 before invoking — the WM
    pre-builds its strip on the stack and uses the boot OPRs directly. """
    fb_ref   = cpu.get_opr(1)
    font_ref = cpu.get_opr(2)
    text_ref = cpu.get_opr(3)
    if fb_ref == 0 or font_ref == 0 or text_ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); cpu.set_gpr(3, 0); return

    r4 = cpu.get_gpr(4)
    r5 = cpu.get_gpr(5)
    extended = (r5 >> 31) & 1
    font_off = sext32(cpu.get_gpr(6))
    text_off = sext32(cpu.get_gpr(7))

    # Validate caps (shared by both modes).  Both fonts and text need R;
    # FB needs W.
    if (ref_caps(fb_ref)   & CAP_W) == 0 or \
       (ref_caps(font_ref) & CAP_R) == 0 or \
       (ref_caps(text_ref) & CAP_R) == 0:
        cpu.set_gpr(2, ERR_EPERM); cpu.set_gpr(3, 0); return
    # Locality: all three must be local.  Cross-CPU blits would
    # need a wire round-trip per source byte — defeats the purpose.
    if ref_home(fb_ref)   != cpu.pid or \
       ref_home(font_ref) != cpu.pid or \
       ref_home(text_ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); cpu.set_gpr(3, 0); return

    fb_idx   = ref_index(fb_ref)
    font_idx = ref_index(font_ref)
    text_idx = ref_index(text_ref)
    for idx, ref in ((fb_idx, fb_ref), (font_idx, font_ref),
                     (text_idx, text_ref)):
        if idx <= 0 or idx >= len(cpu.descriptors) \
                or cpu.descriptors[idx] is None:
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
        d = cpu.descriptors[idx]
        if not d.live or d.generation != ref_generation(ref):
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return

    fb_desc   = cpu.descriptors[fb_idx]
    font_desc = cpu.descriptors[font_idx]
    text_desc = cpu.descriptors[text_idx]
    if fb_desc.type_tag != TAG_FRAMEBUFFER:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    if extended:
        n_chars     = (r5 >> 16) & 0x3FFF
        transparent = (r5 >> 30) & 1
        fg          = (r5 >> 8)  & 0xFF
        bg          =  r5        & 0xFF
        clip_lo     = cpu.get_gpr(8)   # (x0<<16)|y0, or 0 for no clip
        clip_hi     = cpu.get_gpr(9)   # (x1<<16)|y1, or 0 for no clip
        _blit_glyphs_extended(cpu, fb_desc, font_desc, text_desc,
                              r4, n_chars, fg, bg, transparent,
                              font_off, text_off, clip_lo, clip_hi)
        return

    # --- legacy 8x16 cell-grid path (terminal body; byte-for-byte
    # identical to the pre-font-manager primitive) ---
    cell_x = (r4 >> 16) & 0xFFFF
    cell_y = r4 & 0xFFFF
    n_chars = (r5 >> 16) & 0xFFFF
    fg      = (r5 >> 8)  & 0xFF
    bg      = r5 & 0xFF

    fb_w = fb_desc.fb_width
    fb_h = fb_desc.fb_height
    base_x = cell_x * 8
    base_y = cell_y * 16
    if base_y < 0 or base_y >= fb_h:
        cpu.set_gpr(2, ERR_OK); cpu.set_gpr(3, 0); return

    # Bounds-check inputs against descriptor lengths.
    text_end = text_off + n_chars
    if text_off < 0 or text_end > text_desc.length:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
    # Each glyph: 16 bytes.  Need (last_codepoint - 32 + 1) * 16
    # bytes available at font_off, but we'd have to scan the text
    # to know.  Cheap upper bound: enough room for codepoint 126.
    font_max_end = font_off + 95 * 16
    if font_off < 0 or font_max_end > font_desc.length:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    fb_storage   = fb_desc.storage
    font_storage = font_desc.storage
    text_storage = text_desc.storage

    rendered = 0
    for g in range(n_chars):
        ch = text_storage[text_off + g]
        if ch < 32 or ch > 126:
            ch = 32  # space
        glyph_off = font_off + (ch - 32) * 16
        cell_left = base_x + g * 8
        if cell_left >= fb_w:
            break
        for r in range(16):
            row_y = base_y + r
            if row_y < 0 or row_y >= fb_h:
                continue
            byte = font_storage[glyph_off + r]
            row_base = row_y * fb_w + cell_left
            # Emit each of the 8 pixels.  Inner loop in Python is
            # still ~500K assignments/sec, fast enough that an
            # 80-char strip renders in single-digit ms.
            for x in range(8):
                px = cell_left + x
                if px >= fb_w:
                    break
                bit = (byte >> (7 - x)) & 1
                fb_storage[row_base + x] = fg if bit else bg
        rendered += 1

    fb_desc.fb_dirty = True
    cpu.set_gpr(2, ERR_OK)
    cpu.set_gpr(3, rendered)


def primitive_ObjFillRect(cpu: CPU) -> None:
    """Phase 60 step 5 — fill a rectangle in a TAG_FRAMEBUFFER with a
    single palette index.  Companion to ObjBlitGlyphs; lets oriscwm
    paint window chrome (background, border lines) in one firmware
    call instead of N per-row ObjStoreBytes.

    Inputs:
      O1 = framebuffer ref      (TAG_FRAMEBUFFER, must be local)
      R4 = packed (x << 16) | y      — top-left pixel
      R5 = packed (w << 16) | h      — rectangle size in pixels
      R6 = color                     — low byte = palette index

    Outputs:
      R2 = status (ERR_OK / ERR_EFAULT / ERR_EPERM / ERR_EREMOTE /
                   ERR_ESTALE / ERR_EINVAL)

    Off-screen pixels clip silently; (w, h) of 0 is a no-op. """
    fb_ref = cpu.get_opr(1)
    if fb_ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(fb_ref) & CAP_W) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(fb_ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    fb_idx = ref_index(fb_ref)
    if fb_idx <= 0 or fb_idx >= len(cpu.descriptors) \
            or cpu.descriptors[fb_idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    fb_desc = cpu.descriptors[fb_idx]
    if not fb_desc.live or fb_desc.generation != ref_generation(fb_ref):
        cpu.set_gpr(2, ERR_ESTALE); return
    if fb_desc.type_tag != TAG_FRAMEBUFFER:
        cpu.set_gpr(2, ERR_EINVAL); return

    r4 = cpu.get_gpr(4)
    x = sext32((r4 >> 16) & 0xFFFF)
    y = sext32(r4 & 0xFFFF)
    r5 = cpu.get_gpr(5)
    w = (r5 >> 16) & 0xFFFF
    h = r5 & 0xFFFF
    color = cpu.get_gpr(6) & 0xFF

    fb_w = fb_desc.fb_width
    fb_h = fb_desc.fb_height
    # Clip to FB bounds.
    x0 = max(0, x)
    y0 = max(0, y)
    x1 = min(fb_w, x + w)
    y1 = min(fb_h, y + h)
    if x1 <= x0 or y1 <= y0:
        cpu.set_gpr(2, ERR_OK); return

    fb_storage = fb_desc.storage
    span = x1 - x0
    fill = bytes((color,)) * span
    for row_y in range(y0, y1):
        row_base = row_y * fb_w + x0
        fb_storage[row_base:row_base + span] = fill
    fb_desc.fb_dirty = True
    cpu.set_gpr(2, ERR_OK)


def primitive_ObjFbScroll(cpu: CPU) -> None:
    """Phase 60 step 6 — shift a rectangular region of a TAG_FRAMEBUFFER
    vertically by `dy` pixels and fill the freshly-exposed strip with
    a single palette index.  Used by oriscwm's render_buffer to
    scroll the inner cell area up by one cell when text overflows
    the bottom row.

    Inputs:
      O1 = framebuffer ref            (TAG_FRAMEBUFFER, must be local)
      R4 = packed (x << 16) | y       — top-left of region
      R5 = packed (w << 16) | h       — region size in pixels
      R6 = packed (dy << 8) | fill    — dy is signed 24-bit, positive
                                         shifts content UP toward y=0;
                                         fill is the palette index
                                         used to clear the dy pixel
                                         rows freshly exposed at the
                                         bottom (or top, for negative
                                         dy).

    Outputs:
      R2 = status (ERR_OK / ERR_EFAULT / ERR_EPERM / ERR_EREMOTE /
                   ERR_ESTALE / ERR_EINVAL)

    Region clips to FB bounds.  |dy| >= h is equivalent to "fill the
    whole region with `fill`."  dy == 0 is a no-op. """
    fb_ref = cpu.get_opr(1)
    if fb_ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(fb_ref) & CAP_W) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(fb_ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    fb_idx = ref_index(fb_ref)
    if fb_idx <= 0 or fb_idx >= len(cpu.descriptors) \
            or cpu.descriptors[fb_idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    fb_desc = cpu.descriptors[fb_idx]
    if not fb_desc.live or fb_desc.generation != ref_generation(fb_ref):
        cpu.set_gpr(2, ERR_ESTALE); return
    if fb_desc.type_tag != TAG_FRAMEBUFFER:
        cpu.set_gpr(2, ERR_EINVAL); return

    r4 = cpu.get_gpr(4)
    rx = sext32((r4 >> 16) & 0xFFFF)
    ry = sext32(r4 & 0xFFFF)
    r5 = cpu.get_gpr(5)
    rw = (r5 >> 16) & 0xFFFF
    rh = r5 & 0xFFFF
    r6 = cpu.get_gpr(6)
    fill = r6 & 0xFF
    # dy is the upper 24 bits, sign-extended.
    dy_raw = (r6 >> 8) & 0xFFFFFF
    if dy_raw & 0x800000:
        dy = dy_raw - 0x1000000
    else:
        dy = dy_raw

    fb_w = fb_desc.fb_width
    fb_h = fb_desc.fb_height
    # Clip region to FB.
    x0 = max(0, rx)
    y0 = max(0, ry)
    x1 = min(fb_w, rx + rw)
    y1 = min(fb_h, ry + rh)
    if x1 <= x0 or y1 <= y0:
        cpu.set_gpr(2, ERR_OK); return
    cw = x1 - x0
    ch = y1 - y0

    if dy == 0:
        cpu.set_gpr(2, ERR_OK); return

    fb_storage = fb_desc.storage
    fill_row = bytes((fill,)) * cw

    if abs(dy) >= ch:
        # Whole region clears.
        for y in range(y0, y1):
            base = y * fb_w + x0
            fb_storage[base:base + cw] = fill_row
    elif dy > 0:
        # Shift up: dst[y] = src[y + dy] for y in [y0, y1 - dy).
        # Iterate top-down so we don't trample reads.
        for y in range(y0, y1 - dy):
            src = (y + dy) * fb_w + x0
            dst = y * fb_w + x0
            fb_storage[dst:dst + cw] = fb_storage[src:src + cw]
        for y in range(y1 - dy, y1):
            base = y * fb_w + x0
            fb_storage[base:base + cw] = fill_row
    else:
        # Shift down: dst[y] = src[y - |dy|], iterate bottom-up.
        absdy = -dy
        for y in range(y1 - 1, y0 + absdy - 1, -1):
            src = (y - absdy) * fb_w + x0
            dst = y * fb_w + x0
            fb_storage[dst:dst + cw] = fb_storage[src:src + cw]
        for y in range(y0, y0 + absdy):
            base = y * fb_w + x0
            fb_storage[base:base + cw] = fill_row

    fb_desc.fb_dirty = True
    cpu.set_gpr(2, ERR_OK)


def primitive_ObjBlitCopy(cpu: CPU) -> None:
    """Phase 60 step 7 — copy a rectangular region from one
    TAG_FRAMEBUFFER to another (or in-place within one) as a single
    firmware call.  The compositor for per-window backing stores:
    the WM keeps each window's pixels in an offscreen FB and blits
    its visible region onto the on-screen FB after each paint.

    Inputs:
      O1 = destination framebuffer ref (TAG_FRAMEBUFFER, local).
      O2 = source framebuffer ref      (TAG_FRAMEBUFFER, local).
            May be the same ref as O1 for in-FB copy (e.g. scroll-via-
            blit if ObjFbScroll didn't fit); pre-handled by the caller.
      R4 = packed (src_x << 16) | src_y — top-left in source.
      R5 = packed (dst_x << 16) | dst_y — top-left in destination.
      R6 = packed (w << 16) | h         — region size in pixels.

    Outputs:
      R2 = status (ERR_OK / ERR_EFAULT / ERR_EPERM / ERR_EREMOTE /
                   ERR_ESTALE / ERR_EINVAL)

    Both rects clip to their respective FB bounds independently; the
    actual transfer takes the intersection so the visible result is
    well-defined even when one side overflows.  Same-FB overlapping
    src/dst with src_y < dst_y iterates bottom-up so we don't trample
    reads (the in-FB scroll-down case). """
    dst_ref = cpu.get_opr(1)
    src_ref = cpu.get_opr(2)
    if dst_ref == 0 or src_ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(dst_ref) & CAP_W) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if (ref_caps(src_ref) & CAP_R) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(dst_ref) != cpu.pid or ref_home(src_ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    dst_idx = ref_index(dst_ref)
    src_idx = ref_index(src_ref)
    for idx, ref in ((dst_idx, dst_ref), (src_idx, src_ref)):
        if idx <= 0 or idx >= len(cpu.descriptors) \
                or cpu.descriptors[idx] is None:
            cpu.set_gpr(2, ERR_ESTALE); return
        d = cpu.descriptors[idx]
        if not d.live or d.generation != ref_generation(ref):
            cpu.set_gpr(2, ERR_ESTALE); return
    dst_desc = cpu.descriptors[dst_idx]
    src_desc = cpu.descriptors[src_idx]
    if dst_desc.type_tag != TAG_FRAMEBUFFER \
       or src_desc.type_tag != TAG_FRAMEBUFFER:
        cpu.set_gpr(2, ERR_EINVAL); return

    r4 = cpu.get_gpr(4)
    sx = sext32((r4 >> 16) & 0xFFFF)
    sy = sext32(r4 & 0xFFFF)
    r5 = cpu.get_gpr(5)
    dx = sext32((r5 >> 16) & 0xFFFF)
    dy = sext32(r5 & 0xFFFF)
    r6 = cpu.get_gpr(6)
    rw = (r6 >> 16) & 0xFFFF
    rh = r6 & 0xFFFF
    if rw == 0 or rh == 0:
        cpu.set_gpr(2, ERR_OK); return

    sw, sh = src_desc.fb_width, src_desc.fb_height
    dw, dh = dst_desc.fb_width, dst_desc.fb_height
    # Clip rw/rh so neither the source nor destination overflows.
    if sx < 0:
        rw += sx; dx -= sx; sx = 0
    if sy < 0:
        rh += sy; dy -= sy; sy = 0
    if dx < 0:
        rw += dx; sx -= dx; dx = 0
    if dy < 0:
        rh += dy; sy -= dy; dy = 0
    rw = min(rw, sw - sx, dw - dx)
    rh = min(rh, sh - sy, dh - dy)
    if rw <= 0 or rh <= 0:
        cpu.set_gpr(2, ERR_OK); return

    src_storage = src_desc.storage
    dst_storage = dst_desc.storage
    same = (dst_idx == src_idx)
    # In-place overlapping case: copy bottom-up if dst_y > src_y so
    # we read each row before it's overwritten.  Distinct FBs: always
    # safe to iterate top-down.
    if same and dy > sy:
        rows = range(rh - 1, -1, -1)
    else:
        rows = range(rh)
    for ry in rows:
        s = (sy + ry) * sw + sx
        d = (dy + ry) * dw + dx
        dst_storage[d:d + rw] = src_storage[s:s + rw]
    dst_desc.fb_dirty = True
    cpu.set_gpr(2, ERR_OK)


def primitive_ObjAllocInputSink(cpu: CPU) -> None:
    """Phase 60 step 3 — allocate a TAG_INPUT_SINK object that
    receives synthetic SEND_DELIVER events from simorisc's host
    display worker.  When --display tk is on and a Toplevel
    framebuffer window has focus, Tk key / pointer events are
    translated and enqueued into the matching sink (one per kind
    per CPU).  The receiver (oriscwm) polls via the standard
    ReceiveQueuePoll path — same shape as receiving events from
    a remote oriscterm, just constructed in-process.

    This is the firmware piece of the "terminal-firmware" step:
    the simorisc instance hosting the WM also owns its display +
    input, eliminating the wire round-trip to a separate oriscterm
    process.

    Inputs:
      R4 = kind (0 = keyboard, 1 = pointer)
      R5 = caps mask (typically R|W|S for the WM's own use)

    Outputs:
      R2 = status (ERR_OK / ERR_EINVAL / ERR_ENOMEM)
      O1 = ref to the new sink object on success, null on failure

    The sink object has a queue auto-attached at depth 64; the
    caller does NOT need to ReceiveQueueAttach.  Subsequent
    ObjAllocInputSink calls for the same kind on the same CPU
    REPLACE the registered sink (the previous one stays alive and
    polleable but new events route to the new one). """
    kind = cpu.get_gpr(4) & 0xFF
    init_caps = cpu.get_gpr(5) & 0xFF
    if kind not in (0, 1):
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_opr(1, 0); return
    try:
        ref = cpu.alloc_object(0, type_tag=TAG_INPUT_SINK,
                               max_caps=init_caps)
    except Exception:
        cpu.set_gpr(2, ERR_ENOMEM); cpu.set_opr(1, 0); return
    idx = ref_index(ref)
    desc = cpu.descriptors[idx]
    desc.queue = []
    desc.queue_max_depth = 64
    desc.input_kind = kind
    if not hasattr(cpu, "input_sinks"):
        cpu.input_sinks = {0: None, 1: None}
    cpu.input_sinks[kind] = idx
    cpu.set_gpr(2, ERR_OK); cpu.set_opr(1, ref)


def primitive_ObjAllocStore(cpu: CPU) -> None:
    """Like ObjAlloc but the new object's storage is OR-typed: OREFLD/
    OREFST may access it; integer OL/OS trap. Length must be a multiple
    of 8 bytes (one OR slot)."""
    length = cpu.get_gpr(4)
    type_tag = cpu.get_gpr(5) & 0xFFFF
    init_caps = cpu.get_gpr(6) & 0xFF
    if length == 0 or length > (1 << 24) or (length & 0x07) != 0:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_opr(1, 0); return
    try:
        ref = cpu.alloc_object(length, type_tag=type_tag,
                               max_caps=init_caps, objstore=True)
    except Exception:
        cpu.set_gpr(2, ERR_ENOMEM); cpu.set_opr(1, 0); return
    cpu.set_gpr(2, ERR_OK); cpu.set_opr(1, ref)


def primitive_ObjFree(cpu: CPU) -> None:
    o1 = cpu.get_opr(1)
    if o1 == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(o1) & CAP_V) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    home = ref_home(o1)
    if home != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    idx = ref_index(o1)
    if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    desc = cpu.descriptors[idx]
    if not desc.live or desc.generation != ref_generation(o1):
        cpu.set_gpr(2, ERR_ESTALE); return
    # Reaping a TAG_TASK descriptor: only legal once the task has
    # exited, and we evict the Python Task struct alongside the
    # descriptor so cpu.tasks doesn't accumulate dead entries. A live
    # task can't be freed — that would silently strand the running
    # context (or the runnable queue would hold a dangling pointer).
    if desc.type_tag == TAG_TASK:
        task = cpu.tasks.get(idx)
        if task is not None:
            if task.state != TASK_STATE_EXITED:
                cpu.set_gpr(2, ERR_EBUSY); return
            cpu.tasks.pop(idx, None)
    cpu.free_object(idx)
    cpu.set_gpr(2, ERR_OK)

def primitive_ObjFreeDeferred(cpu: CPU) -> None:
    """Volume VI #0x107. Like ObjFree, but the descriptor stays live
    for at least R4 milliseconds before being torn down. Designed for
    the case where a guest task has just SENT data through this
    object's storage (e.g., a term_print payload) and the receiver
    may still issue OBJ_READ_REQs for it after the sender has moved
    on. Freeing immediately would lose those bytes; freeing after a
    drain window matches the chunkboot RESET_DRAIN_SECONDS idiom.

    Args:
      O1:  ref to free (must carry V).
      R4:  drain delay in milliseconds; clamped to [0, 60_000].

    Returns: R2 = OK on success; the same error codes as ObjFree
    apply (EFAULT/EPERM/EREMOTE/ESTALE/EBUSY).

    The descriptor is freed regardless of whether anyone is still
    reading from it when the deadline elapses; this is a hint for
    receivers to drain, not a hard reference count."""
    o1 = cpu.get_opr(1)
    delay_ms = cpu.get_gpr(4) & 0xFFFFFFFF
    if delay_ms > 60_000:
        delay_ms = 60_000
    if o1 == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(o1) & CAP_V) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(o1) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    idx = ref_index(o1)
    if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    desc = cpu.descriptors[idx]
    if not desc.live or desc.generation != ref_generation(o1):
        cpu.set_gpr(2, ERR_ESTALE); return
    # TAG_TASK descriptors carry a Python Task struct in cpu.tasks
    # that the immediate-free path evicts; if anyone ever uses the
    # deferred path on a task, refuse — the deferral semantics
    # (descriptor stays live) interact badly with the scheduler's
    # task-state machine.
    if desc.type_tag == TAG_TASK:
        cpu.set_gpr(2, ERR_EINVAL); return
    deadline = time.time() + (delay_ms / 1000.0)
    cpu.deferred_frees.append((deadline, idx))
    cpu.set_gpr(2, ERR_OK)


def primitive_ObjDerive(cpu: CPU) -> None:
    o1 = cpu.get_opr(1)
    mask = cpu.get_gpr(4) & 0xFF
    if o1 == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(o1) & CAP_C) == 0:
        cpu.set_gpr(2, ERR_EPERM); cpu.set_opr(1, 0); return
    new_caps = ref_caps(o1) & mask
    derived = make_ref(generation=ref_generation(o1),
                       home=ref_home(o1),
                       index=ref_index(o1),
                       caps=new_caps)
    cpu.set_opr(1, derived)
    cpu.set_gpr(2, ERR_OK)


def primitive_ObjFetchBytes(cpu: CPU) -> None:
    """Vol VI #0x108 (Phase 45e). Copy R6 bytes from O1+R4 to O2+R5.
    Source O1 may be local or remote; destination O2 must be local
    and non-objstore (we'd otherwise corrupt OR refs). Bridges the
    OL-immediate-offset gap for cross-CPU bulk reads — OBJ_READ_REQ
    already supports arbitrary widths on the wire, but no instruction
    or primitive previously exposed that to programs.

    Args:
      O1: source object ref (CAP_R required)
      O2: destination object ref (CAP_W required, must be local,
          must not be objstore)
      R4: source offset (signed 32-bit)
      R5: destination offset (signed 32-bit)
      R6: byte count (unsigned 32-bit)

    Returns:
      R2: status (OK / EFAULT / EREMOTE / EPERM / ESTALE / EINVAL)
      R3: bytes actually copied (R6 on success, 0 on error)

    Wire behaviour: when ref_home(O1) != cpu.pid, issues a single
    OBJ_READ_REQ for the full range and raises BlockedOnObjFetch.
    The handler at response time writes payload bytes into the
    local destination descriptor. RESP_* fault flags map to ERR_*
    (STALE/BOUNDS/CAP/BUS_ERROR) — same mapping OL/OS uses.
    """
    src = cpu.get_opr(1)
    dst = cpu.get_opr(2)
    src_off = cpu.get_gpr(4)
    if src_off & 0x80000000: src_off -= 0x100000000
    dst_off = cpu.get_gpr(5)
    if dst_off & 0x80000000: dst_off -= 0x100000000
    n = cpu.get_gpr(6) & 0xFFFFFFFF

    if src == 0 or dst == 0:
        cpu.set_gpr(2, ERR_EFAULT); cpu.set_gpr(3, 0); return
    if (ref_caps(src) & CAP_R) == 0:
        cpu.set_gpr(2, ERR_EPERM); cpu.set_gpr(3, 0); return
    if (ref_caps(dst) & CAP_W) == 0:
        cpu.set_gpr(2, ERR_EPERM); cpu.set_gpr(3, 0); return
    if ref_home(dst) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); cpu.set_gpr(3, 0); return

    # Validate destination locally.
    dst_idx = ref_index(dst)
    if dst_idx <= 0 or dst_idx >= len(cpu.descriptors) \
            or cpu.descriptors[dst_idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
    dst_desc = cpu.descriptors[dst_idx]
    if not dst_desc.live or dst_desc.generation != ref_generation(dst):
        cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
    if dst_desc.objstore:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
    if n == 0:
        cpu.set_gpr(2, ERR_OK); cpu.set_gpr(3, 0); return
    if dst_off < 0 or dst_off + n > dst_desc.length:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    if cpu.system is None or ref_home(src) == cpu.pid:
        # Local source: validate, then bytes copy.
        src_idx = ref_index(src)
        if src_idx <= 0 or src_idx >= len(cpu.descriptors) \
                or cpu.descriptors[src_idx] is None:
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
        src_desc = cpu.descriptors[src_idx]
        if not src_desc.live or src_desc.generation != ref_generation(src):
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
        if src_off < 0 or src_off + n > src_desc.length:
            cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
        dst_desc.storage[dst_off:dst_off+n] = \
            src_desc.storage[src_off:src_off+n]
        cpu.set_gpr(2, ERR_OK)
        cpu.set_gpr(3, n)
        return

    # Remote source: issue OBJ_READ_REQ, block. Home does the
    # validation and answers with the bytes (or a fault flag).
    trans_id = cpu.next_trans_id & 0xFFFF
    cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
    packet = build_obj_read_req(cpu.pid, ref_home(src), trans_id,
                                src, src_off, n)
    cpu.system.crossbar.send_packet(packet)
    raise BlockedOnObjFetch(trans_id, dst_idx, dst_off, n)


def primitive_ObjStoreBytes(cpu: CPU) -> None:
    """Vol VI #0x109 (Phase 59).  Mirror of ObjFetchBytes for the
    write direction.  Copy R6 bytes from O1+R4 (must be local) to
    O2+R5 (may be local or remote).

    The WM's glyph renderer is the headline consumer: drawing one
    8×16 bitmap-font cell to the remote framebuffer = 128 byte
    writes; per-byte OSB on a remote ref would block the CPU on
    128 wire RTTs.  ObjStoreBytes packs the whole 128-byte row into
    one OBJ_WRITE_REQ → one RTT.  Symmetric counterpart of
    ObjFetchBytes (#0x108): together they cover bulk transfers in
    either direction as long as one side is local.

    Args:
      O1: source object ref (CAP_R required, must be local, must
          not be objstore — we'd otherwise be reading OR-typed
          storage as plain bytes)
      O2: destination object ref (CAP_W required, may be local or
          remote)
      R4: source offset (signed 32-bit)
      R5: destination offset (signed 32-bit)
      R6: byte count (unsigned 32-bit)

    Returns:
      R2: status (OK / EFAULT / EREMOTE / EPERM / ESTALE / EINVAL)
      R3: bytes actually written (R6 on success, 0 on error)

    Wire behaviour: when ref_home(O2) != cpu.pid, issues a single
    OBJ_WRITE_REQ carrying all R6 bytes and raises BlockedOnObjStore.
    The matching OBJ_WRITE_RESP delivers the status; RESP_* fault
    flags map to ERR_* the same way ObjFetchBytes maps OBJ_READ_RESP
    faults."""
    src = cpu.get_opr(1)
    dst = cpu.get_opr(2)
    src_off = cpu.get_gpr(4)
    if src_off & 0x80000000: src_off -= 0x100000000
    dst_off = cpu.get_gpr(5)
    if dst_off & 0x80000000: dst_off -= 0x100000000
    n = cpu.get_gpr(6) & 0xFFFFFFFF

    if src == 0 or dst == 0:
        cpu.set_gpr(2, ERR_EFAULT); cpu.set_gpr(3, 0); return
    if (ref_caps(src) & CAP_R) == 0:
        cpu.set_gpr(2, ERR_EPERM); cpu.set_gpr(3, 0); return
    if (ref_caps(dst) & CAP_W) == 0:
        cpu.set_gpr(2, ERR_EPERM); cpu.set_gpr(3, 0); return
    if ref_home(src) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); cpu.set_gpr(3, 0); return

    # Validate source locally and read the bytes.
    src_idx = ref_index(src)
    if src_idx <= 0 or src_idx >= len(cpu.descriptors) \
            or cpu.descriptors[src_idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
    src_desc = cpu.descriptors[src_idx]
    if not src_desc.live or src_desc.generation != ref_generation(src):
        cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
    if src_desc.objstore:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
    if n == 0:
        cpu.set_gpr(2, ERR_OK); cpu.set_gpr(3, 0); return
    if src_off < 0 or src_off + n > src_desc.length:
        cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return

    data = bytes(src_desc.storage[src_off:src_off + n])

    if cpu.system is None or ref_home(dst) == cpu.pid:
        # Local destination: validate, then bytes copy.
        dst_idx = ref_index(dst)
        if dst_idx <= 0 or dst_idx >= len(cpu.descriptors) \
                or cpu.descriptors[dst_idx] is None:
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
        dst_desc = cpu.descriptors[dst_idx]
        if not dst_desc.live or dst_desc.generation != ref_generation(dst):
            cpu.set_gpr(2, ERR_ESTALE); cpu.set_gpr(3, 0); return
        if dst_desc.objstore:
            cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
        if dst_off < 0 or dst_off + n > dst_desc.length:
            cpu.set_gpr(2, ERR_EINVAL); cpu.set_gpr(3, 0); return
        dst_desc.storage[dst_off:dst_off + n] = data
        # Phase 60: TAG_FRAMEBUFFER objects mirror their bytes into a
        # host display surface — flag the descriptor so the display
        # worker repaints on its next tick.
        if dst_desc.type_tag == TAG_FRAMEBUFFER:
            dst_desc.fb_dirty = True
        cpu.set_gpr(2, ERR_OK)
        cpu.set_gpr(3, n)
        return

    # Remote destination: issue OBJ_WRITE_REQ with all the bytes,
    # block. The home processes and replies with OBJ_WRITE_RESP.
    trans_id = cpu.next_trans_id & 0xFFFF
    cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
    packet = build_obj_write_req(cpu.pid, ref_home(dst), trans_id,
                                 dst, dst_off, n, data)
    cpu.system.crossbar.send_packet(packet)
    raise BlockedOnObjStore(trans_id, n)


def primitive_ReceiveQueueAttach(cpu: CPU) -> None:
    """Replace handler-dispatch behaviour on a target object with a
    queue. Subsequent SENDs to the object are appended to the queue
    instead of spawning a handler task."""
    target = cpu.get_opr(1)
    max_depth = cpu.get_gpr(4)

    if target == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(target) & (CAP_S | CAP_V)) != (CAP_S | CAP_V):
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(target) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    if max_depth <= 0 or max_depth > 1024:
        cpu.set_gpr(2, ERR_EINVAL); return

    idx = ref_index(target)
    if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    desc = cpu.descriptors[idx]
    if not desc.live or desc.generation != ref_generation(target):
        cpu.set_gpr(2, ERR_ESTALE); return

    desc.queue = []
    desc.queue_max_depth = max_depth
    cpu.set_gpr(2, ERR_OK)


def _deliver_queue_msg(cpu: CPU, packet: bytes) -> None:
    """Populate registers from a queued SEND_DELIVER packet per Volume VI
    Section 6: R3..R6 receive the integer payload; O1..O4 receive the OR
    payload verbatim (no self-override, unlike handler dispatch)."""
    msg = PendingSend.from_wire(packet)
    cpu.set_gpr(2, ERR_OK)
    for i in range(4):
        cpu.set_gpr(3 + i, msg.int_payload[i])
    for i in range(4):
        cpu.set_opr(1 + i, msg.or_payload[i])


def primitive_ReceiveQueuePoll(cpu: CPU) -> None:
    target = cpu.get_opr(1)
    timeout = cpu.get_gpr(4)

    if target == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(target) & CAP_V) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(target) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return

    idx = ref_index(target)
    if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    desc = cpu.descriptors[idx]
    if not desc.live or desc.generation != ref_generation(target):
        cpu.set_gpr(2, ERR_ESTALE); return
    if desc.queue is None:
        cpu.set_gpr(2, ERR_EINVAL); return

    if desc.queue:
        _deliver_queue_msg(cpu, desc.queue.pop(0))
        return

    if timeout == 0:
        cpu.set_gpr(2, ERR_ETIMEOUT)
        cpu.set_gpr(3, 0)
        return

    # Block. The scheduler holds the CPU at this CALL until the queue
    # receives a message (delivered then) or the timeout expires.
    raise BlockedOnQueue(
        descriptor_idx=idx,
        timeout=-1 if timeout == 0xFFFFFFFF else timeout,
    )


def primitive_WaitAnyQueue(cpu: CPU) -> None:
    """#0x206 (Object RISC Vol VI §6). A pure readiness wait over a SET
    of receive queues — the multi-queue companion to ReceiveQueuePoll.
    Blocks until at least one listed queue is non-empty, then returns
    WITHOUT delivering any message; the caller drains the actual
    messages with its existing per-queue ReceiveQueuePoll calls. This
    keeps the firmware change small and the caller's demux untouched:
    it's the missing "wait on many queues at once" primitive that lets a
    multiplexing server (the window manager) idle-block instead of
    busy-polling each queue on a timeout.

    Args:
      O2: an OBJSTORE object holding up to R5 packed 64-bit queue
          references (one 8-byte slot each, OREFST layout). Must carry
          R (we read it like an OREFLD source).
      R5: number of references to read from the list (count).
      R6: optional timeout in MICROSECONDS — 0 means infinite block (the
          historic behaviour); >0 resumes the CALL with ERR_ETIMEOUT if no
          listed queue becomes ready within that wall-clock span. Lets the
          WM idle-block yet still wake for a timer (e.g. scrollbar auto-repeat)
          without busy-polling.

    The queue set is dynamic and larger than the O-registers (a window
    manager has a per-window queue that comes and goes), so it's passed
    by memory rather than in registers. Each listed reference is checked
    exactly like ReceiveQueuePoll's target — V cap, home == this CPU,
    live descriptor, matching generation, a receive queue attached — but
    an entry that FAILS validation (null slot, freed/stale window queue,
    not-a-queue) is SKIPPED, not fatal: the set legitimately holds slots
    that come and go, and the caller rebuilds it each loop. A genuinely
    malformed *list object* (O2) still errors.

    Returns:
      R2: ERR_OK once a listed queue is non-empty (immediately if one
          already is); ERR_ETIMEOUT if the R6 timeout expired first; ERR_*
          if the list object itself is unusable.
      R3: 0 (no payload — this is a readiness wait, not a dequeue)."""
    listref    = cpu.get_opr(2)
    count      = cpu.get_gpr(5) & 0xFFFFFFFF
    timeout_us = cpu.get_gpr(6) & 0xFFFFFFFF

    # Validate the list object itself (mirror ReceiveQueuePoll's target
    # checks, but require R since we read its slots like OREFLD does).
    if listref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(listref) & CAP_R) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(listref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    lidx = ref_index(listref)
    if lidx >= len(cpu.descriptors) or cpu.descriptors[lidx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    ldesc = cpu.descriptors[lidx]
    if not ldesc.live or ldesc.generation != ref_generation(listref):
        cpu.set_gpr(2, ERR_ESTALE); return
    if not ldesc.objstore:
        cpu.set_gpr(2, ERR_EINVAL); return
    if count == 0 or count * 8 > len(ldesc.storage):
        cpu.set_gpr(2, ERR_EINVAL); return

    # Resolve each listed reference to a local descriptor index, skipping
    # any entry that doesn't currently name one of our receive queues.
    indices = []
    for i in range(count):
        ref = struct.unpack(">Q",
                            bytes(ldesc.storage[i*8:i*8+8]))[0]
        if ref == 0:
            continue                                   # empty slot
        if (ref_caps(ref) & CAP_V) == 0:
            continue
        if ref_home(ref) != cpu.pid:
            continue
        idx = ref_index(ref)
        if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
            continue
        d = cpu.descriptors[idx]
        if not d.live or d.generation != ref_generation(ref):
            continue                                   # stale window queue
        if d.queue is None:
            continue                                   # not a receive queue
        indices.append(idx)

    # Immediate return if any resolved queue already has a message.
    for idx in indices:
        if cpu.descriptors[idx].queue:
            cpu.set_gpr(2, ERR_OK); cpu.set_gpr(3, 0)
            return

    # Otherwise park. The scheduler resumes us the instant any listed
    # queue receives a message (cross-CPU: poll_incoming appends to the
    # home queue, then _try_unblock_queue_set advances past this CALL), or
    # at the optional wall-clock deadline (ERR_ETIMEOUT).
    cpu.set_gpr(3, 0)
    deadline = None if timeout_us == 0 else time.time() + (timeout_us / 1_000_000.0)
    raise BlockedOnQueueSet(descriptor_indices=indices, deadline=deadline)


def primitive_InstallTrapHandler(cpu: CPU) -> None:
    """Volume VI #0x520. Install a supervisor-mode trap handler for the
    given cause code. Subsequent traps with that cause are delivered to
    `R5` (a virtual address mapped in the trapping task's address space)
    in supervisor mode, instead of going through the firmware-only
    VECBASE table.

    Args:
      R4: cause code (0x01..0x21 — must appear in CAUSE_VECTOR_OFFSET).
      R5: handler virtual address.

    Returns: R2 = OK on success, EINVAL if cause is not a recognised
    architectural exception."""
    cause = cpu.get_gpr(4) & 0xFF
    va    = cpu.get_gpr(5) & 0xFFFFFFFF
    if cause not in CAUSE_VECTOR_OFFSET:
        cpu.set_gpr(2, ERR_EINVAL); return
    cpu.trap_handlers[cause] = va
    # Snapshot the supervisor's mappings at install time. When the trap
    # eventually fires from a child task whose own address space doesn't
    # cover this handler VA (e.g. an orx_run-spawned guest faults under
    # a shell that registered the handler), deliver_trap swaps these
    # mappings in for the duration of the handler. ERET then restores
    # the trapping task's mappings via load_task_to_cpu.
    cpu.trap_handler_mappings[cause] = list(cpu.mappings)
    cpu.set_gpr(2, ERR_OK)


def primitive_InstallHandler(cpu: CPU) -> None:
    target = cpu.get_opr(1)
    handler = cpu.get_opr(2)
    handler_off = cpu.get_gpr(4)

    if target == 0 or handler == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if (ref_caps(target) & (CAP_S | CAP_V)) != (CAP_S | CAP_V):
        cpu.set_gpr(2, ERR_EPERM); return
    if (ref_caps(handler) & CAP_X) == 0:
        cpu.set_gpr(2, ERR_EPERM); return
    if ref_home(target) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return

    # Find an executable mapping for the handler code object on this CPU,
    # so dispatch knows the VA at which to begin execution. Boot text is
    # mapped at 0x10000 by init_cpu; loadable modules are mapped wherever
    # MapObject placed them.
    handler_idx = ref_index(handler)
    handler_va = None
    for (lo, hi, idx, base, prot) in cpu.mappings:
        if idx == handler_idx and (prot & CAP_X) and \
                base <= handler_off < base + (hi - lo):
            handler_va = lo + (handler_off - base)
            break
    if handler_va is None:
        cpu.set_gpr(2, ERR_EINVAL); return

    idx = ref_index(target)
    if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    desc = cpu.descriptors[idx]
    if not desc.live or desc.generation != ref_generation(target):
        cpu.set_gpr(2, ERR_ESTALE); return

    desc.send_handler_ref = handler
    desc.send_handler_off = handler_off
    desc.send_handler_va  = handler_va
    cpu.set_gpr(2, ERR_OK)


def primitive_InstallProgram(cpu: CPU) -> None:
    """Atomically replace the running program with one loaded into a
    fresh code/(optional) data object pair, and jump to its entry.

    Used by chunkboot.s after fetching all chunks of a guest .orx:
    the loader hands control to the guest at CODE_VA + entry_offset,
    with the guest seeing the same VA layout as a standalone simorisc
    boot would have produced.

    Args:
        O1 = code reference (must have R+X effective caps)
        O3 = data reference (must have R; null for code-only programs)
        R4 = entry offset within the new code

    Effects:
        - Drops all mappings whose descriptors aren't TAG_STACK; the
          stack mapping (whatever VA range it lives in) is preserved
          so the guest can keep using the inherited stack.
        - Maps code at CODE_VA with prot=R+X.
        - Maps data at DATA_VA with prot=R (only if O3 != 0).
        - Resets all GPRs except R7 (PROCID), R29 (SP=STACK_TOP-16),
          R30 (FP=0), R31 (RA=0).
        - Sets PC = CODE_VA + R4 and next_PC = PC + 4.
        - Sets cpu._call_redirected_pc=True so the dispatch_call site
          knows to skip the post-call PC advance.

    The CPU's OR slots are NOT cleared (the guest inherits whatever
    O5..O15 the loader has arranged, e.g. terminal/keyboard/hostfsd
    refs after the loader's pre-jump shift). O1 is set to the new
    code ref; O3 is set to the new data ref or zero."""
    code_ref = cpu.get_opr(1)
    data_ref = cpu.get_opr(3)
    entry    = cpu.get_gpr(4) & 0xFFFFFFFF
    if entry & 0x80000000:
        entry -= 0x100000000

    if code_ref == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if ref_home(code_ref) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    if (ref_caps(code_ref) & (CAP_R | CAP_X)) != (CAP_R | CAP_X):
        cpu.set_gpr(2, ERR_EPERM); return
    code_idx = ref_index(code_ref)
    if code_idx >= len(cpu.descriptors) or cpu.descriptors[code_idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    code_desc = cpu.descriptors[code_idx]
    if not code_desc.live or code_desc.generation != ref_generation(code_ref):
        cpu.set_gpr(2, ERR_ESTALE); return
    code_size = code_desc.length
    if entry < 0 or entry >= code_size:
        cpu.set_gpr(2, ERR_EINVAL); return

    data_size = 0
    if data_ref != 0:
        if ref_home(data_ref) != cpu.pid:
            cpu.set_gpr(2, ERR_EREMOTE); return
        if (ref_caps(data_ref) & CAP_R) != CAP_R:
            cpu.set_gpr(2, ERR_EPERM); return
        data_idx = ref_index(data_ref)
        if data_idx >= len(cpu.descriptors) or cpu.descriptors[data_idx] is None:
            cpu.set_gpr(2, ERR_ESTALE); return
        data_desc = cpu.descriptors[data_idx]
        if not data_desc.live or data_desc.generation != ref_generation(data_ref):
            cpu.set_gpr(2, ERR_ESTALE); return
        data_size = data_desc.length

    # Keep only stack mappings; toss everything else (loader's own
    # code/data, any temp R+W mappings the loader created during the
    # chunk copy, etc.). The stack VA range is inherited.
    stack_idx = None
    new_mappings = []
    for m in cpu.mappings:
        d = cpu.descriptors[m[2]]
        if d is not None and d.type_tag == TAG_STACK:
            new_mappings.append(m)
            stack_idx = m[2]
    cpu.mappings = new_mappings

    cpu.map_object(code_ref, va=CODE_VA, offset=0, length=code_size,
                   prot=CAP_R | CAP_X)
    if data_size > 0:
        # Match init_cpu: data is R+W so guests can mutate globals.
        # (Caller is responsible for the data ref carrying CAP_W.)
        cpu.map_object(data_ref, va=DATA_VA, offset=0, length=data_size,
                       prot=CAP_R | CAP_W)

    # Match init_cpu's GPR state — minus R0 (always zero), and with
    # PROCID restored to cpu.pid (some loaders may have shuffled R7).
    for i in range(32):
        cpu.gpr[i] = 0
    cpu.set_gpr(7, cpu.pid)
    cpu.set_gpr(29, STACK_TOP - 16)
    cpu.set_gpr(30, 0)
    cpu.set_gpr(31, 0)

    cpu.set_opr(1, code_ref)
    cpu.set_opr(3, data_ref)
    # O2 = stack ref so term_init's `omov o11, o2` lands the right
    # thing. Reconstruct from the surviving stack descriptor (its
    # index is fixed by init_cpu, but we look it up to be tolerant of
    # future layout changes).
    if stack_idx is not None:
        sd = cpu.descriptors[stack_idx]
        stack_ref = make_ref(generation=sd.generation, home=cpu.pid,
                             index=stack_idx, caps=sd.max_caps)
        cpu.set_opr(2, stack_ref)

    cpu.pc      = (CODE_VA + entry) & 0xFFFFFFFF
    cpu.next_pc = (cpu.pc + 4)      & 0xFFFFFFFF
    cpu._call_redirected_pc = True
    cpu.set_gpr(2, ERR_OK)


def primitive_MapObject(cpu: CPU) -> None:
    target  = cpu.get_opr(1)
    va_hint = cpu.get_gpr(4)
    offset  = cpu.get_gpr(5)
    prot    = cpu.get_gpr(6) & (CAP_R | CAP_W | CAP_X)
    length  = cpu.get_gpr(7)

    if target == 0:
        cpu.set_gpr(2, ERR_EFAULT); return
    if ref_home(target) != cpu.pid:
        cpu.set_gpr(2, ERR_EREMOTE); return
    # Requested protection must be a subset of the reference's effective
    # capabilities (Volume VI Section 5.2).
    if (ref_caps(target) & prot) != prot:
        cpu.set_gpr(2, ERR_EPERM); return

    idx = ref_index(target)
    if idx >= len(cpu.descriptors) or cpu.descriptors[idx] is None:
        cpu.set_gpr(2, ERR_ESTALE); return
    desc = cpu.descriptors[idx]
    if not desc.live or desc.generation != ref_generation(target):
        cpu.set_gpr(2, ERR_ESTALE); return

    if length <= 0 or offset < 0 or offset + length > desc.length:
        cpu.set_gpr(2, ERR_EINVAL); return

    # Choose VA. With va_hint == 0, pick a fresh region above the loadable-
    # module floor (0x00100000); with va_hint != 0, honour it verbatim
    # without checking for collisions (the program is responsible).
    if va_hint == 0:
        va = 0x00100000
        while any(lo <= va < hi or va <= lo < va + length
                  for (lo, hi, _, _, _) in cpu.mappings):
            va += (length + 0xFFF) & ~0xFFF
    else:
        va = va_hint & 0xFFFFFFFF

    cpu.map_object(target, va=va, offset=offset, length=length, prot=prot)
    cpu.set_gpr(2, ERR_OK)
    cpu.set_gpr(3, va)


def primitive_Unmap(cpu: CPU) -> None:
    """Volume VI #0x111. Drop the mapping that starts at exactly R4 and
    has exactly R5 length. The simulator's mapping list permits
    duplicates (older entries shadow newer ones — first-match-wins in
    lookup_va), so a clean replace-via-MapObject sequence is
    `Unmap(va,len); MapObject(...,va,len,...)`. Unmapping a range that
    isn't a current mapping returns EINVAL.

    Args:
      R4: virtual address of the mapping to drop.
      R5: length of the mapping (must match the original MapObject).

    Returns: R2 = OK on success, EINVAL if no exact match.
    """
    va  = cpu.get_gpr(4) & 0xFFFFFFFF
    length = cpu.get_gpr(5)
    for i, (lo, hi, _, _, _) in enumerate(cpu.mappings):
        if lo == va and hi == va + length:
            del cpu.mappings[i]
            cpu.set_gpr(2, ERR_OK); return
    cpu.set_gpr(2, ERR_EINVAL)


# Per-primitive minimum caller mode (Volume VI Section 2.4 + Volume II
# Section 13). Anything not listed defaults to MODE_USER on the theory
# that callable-from-user-code is the common case; exposing a privileged
# capability is an explicit decision made here.
PRIMITIVE_MIN_MODE = {
    0x000: MODE_SUPERVISOR,  # TaskCreate       — installs a child task
    0x001: MODE_USER,        # TaskExit
    0x002: MODE_SUPERVISOR,  # TaskResume       — drives the scheduler
    0x003: MODE_SUPERVISOR,  # TaskSuspend
    0x004: MODE_USER,        # TaskYield
    0x005: MODE_USER,        # TaskCurrent
    0x008: MODE_USER,        # TaskQuery
    0x007: MODE_USER,        # TaskWait
    0x009: MODE_SUPERVISOR,  # InstallProgram   — replaces task image
    0x00A: MODE_USER,        # TaskKill         — external termination by ref
    0x100: MODE_USER,        # ObjAlloc
    0x101: MODE_USER,        # ObjFree
    0x10A: MODE_USER,        # ObjAllocFramebuffer (Phase 60; moved off
                             # 0x102, which Vol VI reserves for ObjRevoke)
    0x10B: MODE_USER,        # ObjAllocInputSink (Phase 60 step 3)
    0x10C: MODE_USER,        # ObjBlitGlyphs (Phase 60 step 4)
    0x10D: MODE_USER,        # ObjFillRect (Phase 60 step 5)
    0x10E: MODE_USER,        # ObjFbScroll (Phase 60 step 6)
    0x10F: MODE_USER,        # ObjBlitCopy (Phase 60 step 7)
    0x107: MODE_USER,        # ObjFreeDeferred — drain-window wrapper
    0x103: MODE_USER,        # ObjDerive
    0x106: MODE_USER,        # ObjAllocStore
    0x108: MODE_USER,        # ObjFetchBytes (Phase 45e)
    0x109: MODE_USER,        # ObjStoreBytes (Phase 59)
    0x110: MODE_SUPERVISOR,  # MapObject        — manipulates VA layout
    0x111: MODE_SUPERVISOR,  # Unmap            — manipulates VA layout
    0x200: MODE_SUPERVISOR,  # InstallHandler   — registers trap-like callback
    0x203: MODE_USER,        # ReceiveQueueAttach
    0x204: MODE_USER,        # ReceiveQueuePoll
    0x206: MODE_USER,        # WaitAnyQueue — readiness wait over a queue set
    0x301: MODE_USER,        # ReadCycles
    0x320: MODE_USER,        # ConsoleWrite     — debug primitive, will move
    0x400: MODE_USER,        # TimeNow
    0x410: MODE_USER,        # ClockResolution
    0x520: MODE_SUPERVISOR,  # InstallTrapHandler — registers per-cause vector
}

def dispatch_call(cpu: CPU, prim: int, faulting_pc: int) -> None:
    min_mode = PRIMITIVE_MIN_MODE.get(prim)
    if min_mode is None:
        cpu.set_gpr(2, ERR_ENOSYS)
        cpu.set_gpr(3, 0)
        return
    if cpu.mode < min_mode:
        cpu.set_gpr(2, ERR_EPERM)
        cpu.set_gpr(3, 0)
        return

    if prim == 0x000:
        primitive_TaskCreate(cpu)
    elif prim == 0x001:
        primitive_TaskExit(cpu)
    elif prim == 0x002:
        primitive_TaskResume(cpu)
    elif prim == 0x003:
        primitive_TaskSuspend(cpu)
    elif prim == 0x004:
        primitive_TaskYield(cpu, faulting_pc)
    elif prim == 0x005:
        primitive_TaskCurrent(cpu)
    elif prim == 0x007:
        primitive_TaskWait(cpu, faulting_pc)
    elif prim == 0x008:
        primitive_TaskQuery(cpu)
    elif prim == 0x009:
        primitive_InstallProgram(cpu)
    elif prim == 0x00A:
        primitive_TaskKill(cpu)
    elif prim == 0x100:
        primitive_ObjAlloc(cpu)
    elif prim == 0x101:
        primitive_ObjFree(cpu)
    elif prim == 0x10A:
        primitive_ObjAllocFramebuffer(cpu)
    elif prim == 0x10B:
        primitive_ObjAllocInputSink(cpu)
    elif prim == 0x10C:
        primitive_ObjBlitGlyphs(cpu)
    elif prim == 0x10D:
        primitive_ObjFillRect(cpu)
    elif prim == 0x10E:
        primitive_ObjFbScroll(cpu)
    elif prim == 0x10F:
        primitive_ObjBlitCopy(cpu)
    elif prim == 0x107:
        primitive_ObjFreeDeferred(cpu)
    elif prim == 0x103:
        primitive_ObjDerive(cpu)
    elif prim == 0x106:
        primitive_ObjAllocStore(cpu)
    elif prim == 0x108:
        primitive_ObjFetchBytes(cpu)
    elif prim == 0x109:
        primitive_ObjStoreBytes(cpu)
    elif prim == 0x110:
        primitive_MapObject(cpu)
    elif prim == 0x111:
        primitive_Unmap(cpu)
    elif prim == 0x200:
        primitive_InstallHandler(cpu)
    elif prim == 0x203:
        primitive_ReceiveQueueAttach(cpu)
    elif prim == 0x204:
        primitive_ReceiveQueuePoll(cpu)
    elif prim == 0x206:
        primitive_WaitAnyQueue(cpu)
    elif prim == 0x301:
        primitive_ReadCycles(cpu)
    elif prim == 0x320:
        primitive_ConsoleWrite(cpu, faulting_pc)
    elif prim == 0x400:
        primitive_TimeNow(cpu)
    elif prim == 0x410:
        primitive_ClockResolution(cpu)
    elif prim == 0x520:
        primitive_InstallTrapHandler(cpu)


# ---------------------------------------------------------------------------
# Disassembly (for trace)
# ---------------------------------------------------------------------------

def fmt_instr(pc: int, word: int, cpu: CPU) -> str:
    op = (word >> 26) & 0x3F
    rs = (word >> 21) & 0x1F
    rt = (word >> 16) & 0x1F
    rd = (word >> 11) & 0x1F
    sh = (word >>  6) & 0x1F
    fn = word & 0x3F
    imm = word & 0xFFFF
    simm = sext16(imm)
    target = word & 0x03FFFFFF

    if op == 0x00:
        m = {
            0x00:"sll", 0x02:"srl", 0x03:"sra",
            0x04:"sllv",0x06:"srlv",0x07:"srav",
            0x08:"jr",  0x09:"jalr",
            0x10:"mfhi",0x12:"mflo",
            0x18:"mult",0x19:"multu",0x1A:"div",0x1B:"divu",
            0x20:"add", 0x21:"addu",0x22:"sub", 0x23:"subu",
            0x24:"and", 0x25:"or",  0x26:"xor", 0x27:"nor",
            0x2A:"slt", 0x2B:"sltu",
        }.get(fn, f"special?fn={fn:#x}")
        if fn in (0x00,0x02,0x03):       return f"{m} r{rd}, r{rt}, {sh}"
        if fn in (0x04,0x06,0x07):       return f"{m} r{rd}, r{rt}, r{rs}"
        if fn == 0x08:                   return f"{m} r{rs}"
        if fn == 0x09:                   return f"{m} r{rd}, r{rs}"
        if fn in (0x10,0x12):            return f"{m} r{rd}"
        if fn in (0x18,0x19,0x1A,0x1B):  return f"{m} r{rs}, r{rt}"
        return f"{m} r{rd}, r{rs}, r{rt}"
    if op == 0x01:
        m = {0x00:"bltz",0x01:"bgez",0x10:"bltzal",0x11:"bgezal"}.get(rt, f"regimm?{rt:#x}")
        return f"{m} r{rs}, 0x{(pc + 4 + simm*4) & 0xFFFFFFFF:08x}"
    if op == 0x02:                       return f"j 0x{(((pc+4) & 0xF0000000) | (target<<2)):08x}"
    if op == 0x03:                       return f"jal 0x{(((pc+4) & 0xF0000000) | (target<<2)):08x}"
    if op == 0x04:                       return f"beq r{rs}, r{rt}, 0x{(pc+4+simm*4)&0xFFFFFFFF:08x}"
    if op == 0x05:                       return f"bne r{rs}, r{rt}, 0x{(pc+4+simm*4)&0xFFFFFFFF:08x}"
    if op == 0x06:                       return f"blez r{rs}, 0x{(pc+4+simm*4)&0xFFFFFFFF:08x}"
    if op == 0x07:                       return f"bgtz r{rs}, 0x{(pc+4+simm*4)&0xFFFFFFFF:08x}"
    if op == 0x08:                       return f"addi r{rt}, r{rs}, {simm}"
    if op == 0x09:                       return f"addiu r{rt}, r{rs}, {simm}"
    if op == 0x0A:                       return f"slti r{rt}, r{rs}, {simm}"
    if op == 0x0B:                       return f"sltiu r{rt}, r{rs}, {simm}"
    if op == 0x0C:                       return f"andi r{rt}, r{rs}, 0x{imm:04x}"
    if op == 0x0D:                       return f"ori r{rt}, r{rs}, 0x{imm:04x}"
    if op == 0x0E:                       return f"xori r{rt}, r{rs}, 0x{imm:04x}"
    if op == 0x0F:                       return f"lui r{rt}, 0x{imm:04x}"
    if op == 0x10:
        if rs == 0x00: return f"lctrl r{rt}, ${rd}"
        if rs == 0x04: return f"sctrl ${rd}, r{rt}"
        if rs == 0x10:
            return {0x01:"tlbr", 0x02:"tlbwi", 0x06:"tlbwr",
                    0x08:"tlbp", 0x18:"eret",  0x20:"wait"
                    }.get(fn, f"system?co.fn={fn:#x}")
        return f"system?rs={rs:#x}"
    if op == 0x20:                       return f"lb r{rt}, {simm}(r{rs})"
    if op == 0x21:                       return f"lh r{rt}, {simm}(r{rs})"
    if op == 0x23:                       return f"lw r{rt}, {simm}(r{rs})"
    if op == 0x24:                       return f"lbu r{rt}, {simm}(r{rs})"
    if op == 0x25:                       return f"lhu r{rt}, {simm}(r{rs})"
    if op == 0x28:                       return f"sb r{rt}, {simm}(r{rs})"
    if op == 0x29:                       return f"sh r{rt}, {simm}(r{rs})"
    if op == 0x2B:                       return f"sw r{rt}, {simm}(r{rs})"
    if op == 0x30:
        os_  = (word >> 22) & 0xF
        ot   = (word >> 18) & 0xF
        ord_ = (word >> 13) & 0x1F
        ofn  = (word >>  4) & 0xF
        m = {0x0:"omov",0x1:"onull",0x2:"oeq",0x3:"oisn",
             0x4:"olen",0x5:"otag",0x6:"ohome",0x7:"ocap",
             0x8:"ofence"}.get(ofn, f"obj?fn={ofn:#x}")
        if ofn == 0x0: return f"omov o{os_}, o{ot}"
        if ofn == 0x1: return f"onull o{os_}"
        if ofn == 0x2: return f"oeq r{ord_}, o{os_}, o{ot}"
        if ofn == 0x8: return "ofence"
        return f"{m} r{ord_}, o{os_}"
    if op in (0x31,0x32,0x33,0x34,0x35,0x38,0x39,0x3B):
        os_ = (word >> 22) & 0xF
        rt_ = (word >> 16) & 0x3F
        off = sext16(word & 0xFFFF)
        m = {0x31:"olb",0x32:"olh",0x33:"olw",0x34:"olbu",
             0x35:"olhu",0x38:"osb",0x39:"osh",0x3B:"osw"}[op]
        return f"{m} r{rt_ & 0x1F}, {off}(o{os_})"
    if op in (0x36, 0x37):
        os_ = (word >> 22) & 0xF
        od  = (word >> 18) & 0xF
        m = "orefld" if op == 0x36 else "orefst"
        if (word >> 16) & 0x1:   # register-indexed form
            return f"{m}x o{od}, r{word & 0x1F}(o{os_})"
        off = sext16(word & 0xFFFF)
        return f"{m} o{od}, {off}(o{os_})"
    if op == 0x3C:
        os_ = (word >> 22) & 0xF
        return f"send o{os_}"
    if op == 0x3D:
        return f"call #{target:#x}"
    return f"???op={op:#x}"


def emit_trace(cpu: CPU, pc: int, word: int,
               pre_gpr: List[int], pre_opr: List[int],
               pre_hi: int, pre_lo: int) -> None:
    if not cpu.trace_enabled:
        return
    diffs: List[str] = []
    for i in range(32):
        if cpu.gpr[i] != pre_gpr[i]:
            diffs.append(f"r{i} = 0x{cpu.gpr[i]:08x}")
    for i in range(16):
        if cpu.opr[i] != pre_opr[i]:
            diffs.append(f"o{i} = 0x{cpu.opr[i]:016x}")
    if cpu.hi != pre_hi:
        diffs.append(f"hi = 0x{cpu.hi:08x}")
    if cpu.lo != pre_lo:
        diffs.append(f"lo = 0x{cpu.lo:08x}")
    decoded = fmt_instr(pc, word, cpu)
    prefix = f"CPU{cpu.pid} " if cpu.system and cpu.system.n_cpus > 1 else ""
    line = f"{prefix}0x{pc:08x}  {decoded:<32s}"
    if diffs:
        line += "  ; " + ", ".join(diffs)
    print(line, file=sys.stderr)


# ---------------------------------------------------------------------------
# Instruction step
# ---------------------------------------------------------------------------

def step(cpu: CPU) -> None:
    pc = cpu.pc
    if pc == 0:
        raise Trap(CAUSE_BUS_ERROR_I, pc, "main returned without TaskExit")
    # Timer interrupt: fire before fetching the next instruction so EPC
    # ends up pointing at the would-be-next instruction (which is what
    # ERET will resume). compare_reg = 0 disables the timer (default).
    # Defer firing while the CPU is in a branch delay slot — Vol II §14
    # would have us record the branch's address in EPC with the BD bit
    # set; the simulator doesn't track BD yet, so we just wait one
    # instruction and fire on the branch target instead. (Sync traps
    # inside delay slots have the same architectural concern; they're
    # rare in current programs and will be fixed when BD is wired in.)
    in_delay_slot = (cpu.next_pc != to_u32(cpu.pc + 4))
    if (not in_delay_slot
            and cpu.status_ie and cpu.compare_reg != 0
            and cpu.cycles >= cpu.compare_reg):
        raise Trap(CAUSE_EXTERNAL_INTERRUPT, pc, "timer")
    word = cpu.fetch_instr(pc)
    op = (word >> 26) & 0x3F

    # Snapshot the register file for the instruction trace ONLY when tracing
    # is on. emit_trace (the sole consumer) early-returns when trace is off,
    # so copying the whole GPR+OPR file on every instruction was pure
    # overhead in the normal untraced case — it showed up as ~2 list copies
    # per instruction in the profile.
    if cpu.trace_enabled:
        pre_gpr = cpu.gpr.copy()
        pre_opr = cpu.opr.copy()
        pre_hi, pre_lo = cpu.hi, cpu.lo
    else:
        pre_gpr = pre_opr = None
        pre_hi = pre_lo = 0

    branch_target: Optional[int] = None

    rs = (word >> 21) & 0x1F
    rt = (word >> 16) & 0x1F
    rd = (word >> 11) & 0x1F
    sh = (word >>  6) & 0x1F
    fn = word & 0x3F
    imm = word & 0xFFFF
    simm = sext16(imm)
    target26 = word & 0x03FFFFFF

    gpr = cpu.get_gpr
    sgpr = cpu.get_sgpr

    if op == 0x00:  # SPECIAL
        if   fn == 0x00:
            cpu.set_gpr(rd, to_u32(gpr(rt) << sh))
        elif fn == 0x02:
            cpu.set_gpr(rd, to_u32(gpr(rt) >> sh))
        elif fn == 0x03:
            cpu.set_gpr(rd, to_u32(sgpr(rt) >> sh))
        elif fn == 0x04:
            cpu.set_gpr(rd, to_u32(gpr(rt) << (gpr(rs) & 0x1F)))
        elif fn == 0x06:
            cpu.set_gpr(rd, to_u32(gpr(rt) >> (gpr(rs) & 0x1F)))
        elif fn == 0x07:
            cpu.set_gpr(rd, to_u32(sgpr(rt) >> (gpr(rs) & 0x1F)))
        elif fn == 0x08:
            branch_target = gpr(rs) & 0xFFFFFFFF
        elif fn == 0x09:
            cpu.set_gpr(rd if rd else 31, to_u32(pc + 8))
            branch_target = gpr(rs) & 0xFFFFFFFF
        elif fn == 0x10:
            cpu.set_gpr(rd, cpu.hi)
        elif fn == 0x12:
            cpu.set_gpr(rd, cpu.lo)
        elif fn == 0x18:
            prod = sgpr(rs) * sgpr(rt)
            cpu.lo = to_u32(prod); cpu.hi = to_u32(prod >> 32)
        elif fn == 0x19:
            prod = gpr(rs) * gpr(rt)
            cpu.lo = to_u32(prod); cpu.hi = to_u32(prod >> 32)
        elif fn == 0x1A:
            a, b = sgpr(rs), sgpr(rt)
            if b == 0:
                cpu.lo, cpu.hi = 0, to_u32(a)
            else:
                q = abs(a) // abs(b)
                if (a < 0) ^ (b < 0):
                    q = -q
                r = a - q * b
                cpu.lo, cpu.hi = to_u32(q), to_u32(r)
        elif fn == 0x1B:
            a, b = gpr(rs), gpr(rt)
            if b == 0:
                cpu.lo, cpu.hi = 0, a
            else:
                cpu.lo, cpu.hi = a // b, a % b
        elif fn == 0x20:
            a, b = sgpr(rs), sgpr(rt); r = a + b
            if r < -0x80000000 or r > 0x7FFFFFFF:
                raise Trap(CAUSE_ARITH_OVERFLOW, pc, "ADD overflow")
            cpu.set_gpr(rd, to_u32(r))
        elif fn == 0x21:
            cpu.set_gpr(rd, to_u32(gpr(rs) + gpr(rt)))
        elif fn == 0x22:
            a, b = sgpr(rs), sgpr(rt); r = a - b
            if r < -0x80000000 or r > 0x7FFFFFFF:
                raise Trap(CAUSE_ARITH_OVERFLOW, pc, "SUB overflow")
            cpu.set_gpr(rd, to_u32(r))
        elif fn == 0x23: cpu.set_gpr(rd, to_u32(gpr(rs) - gpr(rt)))
        elif fn == 0x24: cpu.set_gpr(rd, gpr(rs) & gpr(rt))
        elif fn == 0x25: cpu.set_gpr(rd, gpr(rs) | gpr(rt))
        elif fn == 0x26: cpu.set_gpr(rd, gpr(rs) ^ gpr(rt))
        elif fn == 0x27: cpu.set_gpr(rd, to_u32(~(gpr(rs) | gpr(rt))))
        elif fn == 0x2A: cpu.set_gpr(rd, 1 if sgpr(rs) < sgpr(rt) else 0)
        elif fn == 0x2B: cpu.set_gpr(rd, 1 if gpr(rs)  < gpr(rt)  else 0)
        else:
            raise Trap(CAUSE_RESERVED_INSTR, pc, f"SPECIAL funct {fn:#x}")
    elif op == 0x01:
        cond_target = to_u32(pc + 4 + (simm * 4))
        if   rt == 0x00: cond = sgpr(rs) <  0
        elif rt == 0x01: cond = sgpr(rs) >= 0
        elif rt == 0x10:
            cpu.set_gpr(31, to_u32(pc + 8)); cond = sgpr(rs) < 0
        elif rt == 0x11:
            cpu.set_gpr(31, to_u32(pc + 8)); cond = sgpr(rs) >= 0
        else:
            raise Trap(CAUSE_RESERVED_INSTR, pc, f"REGIMM rt {rt:#x}")
        if cond: branch_target = cond_target & 0xFFFFFFFF
    elif op == 0x02:
        ds = pc + 4
        branch_target = ((ds & 0xF0000000) | (target26 << 2)) & 0xFFFFFFFF
    elif op == 0x03:
        cpu.set_gpr(31, to_u32(pc + 8))
        ds = pc + 4
        branch_target = ((ds & 0xF0000000) | (target26 << 2)) & 0xFFFFFFFF
    elif op == 0x04:
        if gpr(rs) == gpr(rt): branch_target = to_u32(pc + 4 + simm*4)
    elif op == 0x05:
        if gpr(rs) != gpr(rt): branch_target = to_u32(pc + 4 + simm*4)
    elif op == 0x06:
        if sgpr(rs) <= 0:      branch_target = to_u32(pc + 4 + simm*4)
    elif op == 0x07:
        if sgpr(rs) > 0:       branch_target = to_u32(pc + 4 + simm*4)
    elif op == 0x08:
        a = sgpr(rs); b = simm; r = a + b
        if r < -0x80000000 or r > 0x7FFFFFFF:
            raise Trap(CAUSE_ARITH_OVERFLOW, pc, "ADDI overflow")
        cpu.set_gpr(rt, to_u32(r))
    elif op == 0x10:  # SYSTEM (privileged) — Volume II Section 13
        # rs selects the sub-operation; rd carries the control-register
        # number for LCTRL / SCTRL. All sub-ops trap in user mode; the
        # TLB-management ops trap in supervisor mode too.
        if rs == 0x00:    # LCTRL Rt, ctrl(Rd)
            if cpu.mode < MODE_SUPERVISOR:
                raise Trap(CAUSE_PRIV_INSTR, pc, "LCTRL in user mode")
            if rd > CTRL_SV_MAX and cpu.mode < MODE_FIRMWARE:
                raise Trap(CAUSE_PRIV_INSTR, pc,
                           f"LCTRL ctrl{rd} requires firmware mode")
            cpu.set_gpr(rt, cpu.ctrl_read(rd))
        elif rs == 0x04:  # SCTRL ctrl(Rd), Rt
            if cpu.mode < MODE_SUPERVISOR:
                raise Trap(CAUSE_PRIV_INSTR, pc, "SCTRL in user mode")
            if rd > CTRL_SV_MAX and cpu.mode < MODE_FIRMWARE:
                raise Trap(CAUSE_PRIV_INSTR, pc,
                           f"SCTRL ctrl{rd} requires firmware mode")
            cpu.ctrl_write(rd, cpu.get_gpr(rt))
        elif rs == 0x10:  # CO — sub-decoded by funct
            if cpu.mode < MODE_SUPERVISOR:
                raise Trap(CAUSE_PRIV_INSTR, pc,
                           f"SYSTEM.CO funct {fn:#x} in user mode")
            if fn == 0x18:    # ERET — return from exception or CALL
                cur = cpu.current_task
                # Reflect any handler-side SCTRL of EPC/STATUS into the
                # outgoing task's resume image so the trapped task picks
                # up at the right post-handler location whether we
                # ERET-resume or yield-then-resume.
                if cur is not None:
                    cur.pc      = cpu.saved_pc & 0xFFFFFFFF
                    cur.next_pc = (cpu.saved_pc + 4) & 0xFFFFFFFF
                    cur.mode    = cpu.saved_mode

                if cpu.yield_pending:
                    # The handler asked for a context switch via
                    # TaskYield — honor it now, on the way out. The
                    # outgoing task struct is already a valid resume
                    # image (saved at trap delivery + reflected above);
                    # just pick the next runnable and load it without
                    # re-saving cpu state (which would clobber the
                    # outgoing task struct with the handler's mid-
                    # execution gprs).
                    cpu.yield_pending   = False
                    cpu.in_trap_handler = False
                    nxt = pick_next_runnable(cpu)
                    if nxt is not None and nxt is not cur and cur is not None:
                        cur.state = TASK_STATE_RUNNABLE
                        cpu.runnable.append(cur)
                        load_task_to_cpu(cpu, nxt)
                        nxt.state = TASK_STATE_RUNNING
                        cpu.current_task = nxt
                        cpu.cycles += 1
                        emit_trace(cpu, pc, word, pre_gpr, pre_opr, pre_hi, pre_lo)
                        return
                    # Nothing else runnable (or we're somehow without a
                    # current task): fall through to a normal ERET.

                # Normal ERET: restore the trapped task's user GPRs/
                # OPRs (so handler clobbers don't leak), then jump to
                # the post-handler EPC in the post-handler mode.
                cpu.in_trap_handler = False
                if cur is not None:
                    saved_pc_final   = cpu.saved_pc
                    saved_mode_final = cpu.saved_mode
                    load_task_to_cpu(cpu, cur)
                    cpu.pc       = saved_pc_final & 0xFFFFFFFF
                    cpu.next_pc  = (cpu.pc + 4) & 0xFFFFFFFF
                    cpu.mode     = saved_mode_final
                else:
                    cpu.mode = cpu.saved_mode
                    cpu.pc = cpu.saved_pc
                    cpu.next_pc = to_u32(cpu.pc + 4)
                cpu.cycles += 1
                emit_trace(cpu, pc, word, pre_gpr, pre_opr, pre_hi, pre_lo)
                return
            elif fn == 0x20:  # WAIT — halt until interrupt
                pass          # no interrupt model in this simulator
            elif fn in (0x01, 0x02, 0x06, 0x08):  # TLBR/TLBWI/TLBWR/TLBP
                if cpu.mode < MODE_FIRMWARE:
                    raise Trap(CAUSE_PRIV_INSTR, pc,
                               f"TLB op funct {fn:#x} requires firmware mode")
                # No real TLB in this simulator — VAs are tracked by
                # cpu.mappings, populated through MapObject. Treat as no-op
                # so firmware code that blindly issues TLBWR survives.
                pass
            else:
                raise Trap(CAUSE_RESERVED_INSTR, pc,
                           f"SYSTEM.CO funct {fn:#x}")
        else:
            raise Trap(CAUSE_RESERVED_INSTR, pc,
                       f"SYSTEM rs {rs:#x}")
    elif op == 0x09: cpu.set_gpr(rt, to_u32(gpr(rs) + simm))
    elif op == 0x0A: cpu.set_gpr(rt, 1 if sgpr(rs) < simm else 0)
    elif op == 0x0B: cpu.set_gpr(rt, 1 if gpr(rs) < (simm & 0xFFFFFFFF) else 0)
    elif op == 0x0C: cpu.set_gpr(rt, gpr(rs) & imm)
    elif op == 0x0D: cpu.set_gpr(rt, gpr(rs) | imm)
    elif op == 0x0E: cpu.set_gpr(rt, gpr(rs) ^ imm)
    elif op == 0x0F: cpu.set_gpr(rt, to_u32(imm << 16))
    elif op in (0x20,0x21,0x23,0x24,0x25):
        ea = to_u32(gpr(rs) + simm)
        if   op == 0x20: cpu.set_gpr(rt, cpu.load_gpr_mem(ea, 1, True,  pc))
        elif op == 0x21: cpu.set_gpr(rt, cpu.load_gpr_mem(ea, 2, True,  pc))
        elif op == 0x23: cpu.set_gpr(rt, cpu.load_gpr_mem(ea, 4, False, pc))
        elif op == 0x24: cpu.set_gpr(rt, cpu.load_gpr_mem(ea, 1, False, pc))
        elif op == 0x25: cpu.set_gpr(rt, cpu.load_gpr_mem(ea, 2, False, pc))
    elif op in (0x28,0x29,0x2B):
        ea = to_u32(gpr(rs) + simm)
        if   op == 0x28: cpu.store_gpr_mem(ea, 1, gpr(rt), pc)
        elif op == 0x29: cpu.store_gpr_mem(ea, 2, gpr(rt), pc)
        elif op == 0x2B: cpu.store_gpr_mem(ea, 4, gpr(rt), pc)
    elif op == 0x30:  # OBJECT R-R
        os_  = (word >> 22) & 0xF
        ot   = (word >> 18) & 0xF
        ord_ = (word >> 13) & 0x1F
        ofn  = (word >>  4) & 0xF
        if ofn == 0x0:
            cpu.set_opr(os_, cpu.get_opr(ot))
        elif ofn == 0x1:
            cpu.set_opr(os_, 0)
        elif ofn == 0x2:
            a = cpu.get_opr(os_); b = cpu.get_opr(ot)
            mask = 0xFFFFFFFFFFFF0000
            cpu.set_gpr(ord_, 1 if (a & mask) == (b & mask) else 0)
        elif ofn == 0x3:
            cpu.set_gpr(ord_, 1 if cpu.get_opr(os_) == 0 else 0)
        elif ofn in (0x4,0x5,0x6,0x7):
            desc, home = cpu.inspect_obj(os_, pc)
            if   ofn == 0x4: cpu.set_gpr(ord_, desc.length & 0xFFFFFFFF)
            elif ofn == 0x5: cpu.set_gpr(ord_, desc.type_tag & 0xFFFF)
            elif ofn == 0x6: cpu.set_gpr(ord_, home)
            elif ofn == 0x7: cpu.set_gpr(ord_, ref_caps(cpu.get_opr(os_)))
        elif ofn == 0x8:  # OFENCE — no-op in this simulator (no reordering to fence)
            pass
        else:
            raise Trap(CAUSE_RESERVED_INSTR, pc, f"OBJECT funct {ofn:#x}")
    elif op in (0x31,0x32,0x33,0x34,0x35,0x38,0x39,0x3B):
        os_ = (word >> 22) & 0xF
        rt_full = (word >> 16) & 0x3F
        if rt_full & 0x20:
            raise Trap(CAUSE_RESERVED_INSTR, pc,
                       "O-load/store rt' high bit reserved must be zero")
        rt5 = rt_full & 0x1F
        offset = sext16(word & 0xFFFF)
        # Width and signedness per opcode.
        op_meta = {
            0x31: (1, True,  False),  # OLB
            0x32: (2, True,  False),  # OLH
            0x33: (4, False, False),  # OLW
            0x34: (1, False, False),  # OLBU
            0x35: (2, False, False),  # OLHU
            0x38: (1, False, True),   # OSB
            0x39: (2, False, True),   # OSH
            0x3B: (4, False, True),   # OSW
        }
        width, signed, is_write = op_meta[op]
        ref = cpu.get_opr(os_)
        # Issuer-side fast-fail checks (no need to send a packet).
        if ref == 0:
            raise Trap(CAUSE_NULL_DEREF, pc, f"null O{os_} dereference")
        required_cap = CAP_W if is_write else CAP_R
        if (ref_caps(ref) & required_cap) != required_cap:
            raise Trap(CAUSE_CAP_VIOLATION, pc,
                       f"O{os_} caps {ref_caps(ref):#x} lacks {required_cap:#x}")
        home = ref_home(ref)
        if cpu.system is None or home == cpu.pid:
            # Local fast path: full validation, direct read/write.
            desc, off, _ = cpu.deref_obj(os_, offset, width,
                                         required_cap, pc)
            if is_write:
                val = cpu.get_gpr(rt5) & ((1 << (width*8)) - 1)
                desc.storage[off:off+width] = val.to_bytes(width, "big")
            else:
                raw = bytes(desc.storage[off:off+width])
                v = int.from_bytes(raw, "big")
                if signed and v & (1 << (width*8 - 1)):
                    v -= 1 << (width*8)
                cpu.set_gpr(rt5, to_u32(v))
        else:
            # Remote: build OBJ_READ_REQ or OBJ_WRITE_REQ, queue it on the
            # home CPU's request queue, and block at this OL/OS instruction
            # until the corresponding *_RESP arrives.
            trans_id = cpu.next_trans_id & 0xFFFF
            cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
            if is_write:
                val = cpu.get_gpr(rt5) & ((1 << (width*8)) - 1)
                data = val.to_bytes(width, "big")
                packet = build_obj_write_req(cpu.pid, home, trans_id,
                                             ref, offset, width, data)
            else:
                packet = build_obj_read_req(cpu.pid, home, trans_id,
                                            ref, offset, width)
            cpu.system.crossbar.send_packet(packet)
            raise BlockedOnResponse(trans_id, target_reg=rt5,
                                    width=width, signed=signed,
                                    is_write=is_write)
    elif op in (0x36, 0x37):  # OREFLD / OREFST
        os_  = (word >> 22) & 0xF
        od   = (word >> 18) & 0xF
        i_mode = (word >> 16) & 0x1   # bit 16: 1 = register-indexed (orefldx/orefstx)
        if (word >> 17) & 0x1:        # bit 17 is still reserved
            raise Trap(CAUSE_RESERVED_INSTR, pc, "OREF reserved bit 17 must be zero")
        if i_mode:
            if (word >> 5) & 0x7FF:    # bits 15:5 reserved in the indexed form
                raise Trap(CAUSE_RESERVED_INSTR, pc,
                           "OREFx reserved bits 15:5 must be zero")
            # Element index in a GPR, scaled by the 8-byte OREF slot size.
            # The <<3 makes the byte offset inherently 8-aligned; deref_obj
            # then applies the identical bounds/caps/objstore/generation
            # checks as the immediate form (an out-of-range index traps
            # bounds, so no OREF can be forged from adjacent storage).
            offset = cpu.get_gpr(word & 0x1F) << 3
        else:
            offset = sext16(word & 0xFFFF)
        if op == 0x36:  # OREFLD Od, offset(Os)
            desc, off, _ = cpu.deref_obj(os_, offset, 8, CAP_R, pc,
                                         expect_objstore=True)
            ref_value = struct.unpack(">Q", bytes(desc.storage[off:off+8]))[0]
            cpu.set_opr(od, ref_value)
        else:           # OREFST Od, offset(Os)
            ref_value = cpu.get_opr(od)
            desc, off, _ = cpu.deref_obj(os_, offset, 8, CAP_W, pc,
                                         expect_objstore=True)
            desc.storage[off:off+8] = struct.pack(">Q", ref_value)
    elif op == 0x3C:  # SEND
        os_ = (word >> 22) & 0xF
        ref = cpu.get_opr(os_)
        if ref == 0:
            raise Trap(CAUSE_NULL_DEREF, pc, f"SEND on null O{os_}")
        if (ref_caps(ref) & CAP_S) == 0:
            raise Trap(CAUSE_CAP_VIOLATION, pc, f"SEND lacks S on O{os_}")
        # Validate against the home CPU's descriptor table only when that
        # CPU is reachable from this process (in-process multi-CPU mode).
        # In socket-mode the home lives behind the crossbar; the home
        # validates on receipt and silently drops on mismatch. Note that
        # `system.cpus` is positionally indexed, not pid-indexed: in
        # socket mode it has a single entry whose pid may be any value,
        # so we must search by pid rather than index by it.
        home = ref_home(ref)
        target_descriptors = None
        if cpu.system is not None:
            if home == cpu.pid:
                target_descriptors = cpu.descriptors
            else:
                for c in cpu.system.cpus:
                    if c.pid == home:
                        target_descriptors = c.descriptors
                        break
        if target_descriptors is not None:
            idx = ref_index(ref)
            if idx >= len(target_descriptors) or target_descriptors[idx] is None:
                raise Trap(CAUSE_STALE_REF, pc, f"SEND stale O{os_}")
            desc = target_descriptors[idx]
            if not desc.live or desc.generation != ref_generation(ref):
                raise Trap(CAUSE_STALE_REF, pc, f"SEND stale O{os_}")
        # Build payload: int = R4..R7, OR = O1..O4 (per Vol II Section 10).
        msg = PendingSend(
            recipient_ref=ref,
            int_payload=[cpu.get_gpr(4 + i) for i in range(4)],
            or_payload =[cpu.get_opr(1 + i) for i in range(4)],
            src_pid=cpu.pid,
            trans_id=cpu.next_trans_id & 0xFFFF,
        )
        cpu.next_trans_id = (cpu.next_trans_id + 1) & 0xFFFF
        if cpu.system is not None:
            cpu.system.queue_send(msg)
    elif op == 0x3D:  # CALL — no delay slot.
        prim = target26
        cpu._call_redirected_pc = False
        try:
            dispatch_call(cpu, prim, pc)
        except BlockedSignal as b:
            # Hold the CPU at this CALL; on resume the scheduler will
            # populate registers, advance PC by 4, and clear blocked_on.
            cpu.blocked_on = b
            cpu.cycles += 1
            emit_trace(cpu, pc, word, pre_gpr, pre_opr, pre_hi, pre_lo)
            return
        if not cpu._call_redirected_pc:
            cpu.pc = to_u32(pc + 4)
            cpu.next_pc = to_u32(cpu.pc + 4)
        # Else: primitive_InstallProgram already set PC to the new
        # entry point — don't advance past it.
        cpu.cycles += 1
        emit_trace(cpu, pc, word, pre_gpr, pre_opr, pre_hi, pre_lo)
        return
    else:
        raise Trap(CAUSE_RESERVED_INSTR, pc, f"opcode {op:#x}")

    if branch_target is None:
        cpu.pc = cpu.next_pc
        cpu.next_pc = to_u32(cpu.pc + 4)
    else:
        cpu.pc = cpu.next_pc
        cpu.next_pc = branch_target

    cpu.cycles += 1
    emit_trace(cpu, pc, word, pre_gpr, pre_opr, pre_hi, pre_lo)


# ---------------------------------------------------------------------------
# Trap reporter
# ---------------------------------------------------------------------------

def deliver_trap(cpu: CPU, t: Trap) -> bool:
    """Vector-driven trap delivery (Volume II Section 14 + Appendix B).

    Populates EPC/CAUSE/BADVADDR, saves the current mode, and either:

    1. Jumps to a supervisor-installed handler for this cause (mode
       switches to supervisor — installed via Volume VI primitive
       #0x520 InstallTrapHandler). Per-CPU map; the handler runs in
       the trapping task's address space.
    2. Falls back to `VECBASE + offset[cause]` (mode switches to
       firmware) when no per-cause handler is registered.

    Returns True when delivered; False when neither path applies, in
    which case the caller should fall back to the fatal-trap report.

    External-interrupt delivery (cause 0x01) auto-clears `STATUS.IE`
    so the handler runs without immediately re-firing on the same
    instruction; the handler re-enables IE on ERET (typically by
    SCTRL-ing STATUS or letting the saved-IE bit ride back via ERET
    — the latter not yet wired, today the handler must explicitly
    re-set IE).

    The handler returns by `ERET`, which restores `saved_mode` from
    STATUS and resumes at `EPC`. To skip the trapping instruction, the
    handler must add 4 to EPC before issuing ERET — re-execute is the
    default since most causes (TLB miss, future page faults) want it."""
    handler_va = cpu.trap_handlers.get(t.cause)
    if handler_va is None and cpu.vecbase == 0:
        return False
    if handler_va is None:
        offset = CAUSE_VECTOR_OFFSET.get(t.cause)
        if offset is None:
            return False
        target_pc   = (cpu.vecbase + offset) & 0xFFFFFFFF
        target_mode = MODE_FIRMWARE
    else:
        target_pc   = handler_va & 0xFFFFFFFF
        target_mode = MODE_SUPERVISOR

    # Checkpoint the user task's full state into its Task struct
    # BEFORE we overwrite cpu.pc / cpu.mode for the handler. This is
    # what makes TaskYield-from-handler safe — when the handler
    # eventually sets yield_pending and ERETs, the outgoing task
    # struct already holds a valid resume image of the trapped task.
    # Without this, we'd save the handler's mid-execution state
    # instead and resume into junk on the next schedule. The ERET
    # path also uses this to restore user GPRs the handler may have
    # clobbered. (Phase 35.)
    if cpu.current_task is not None:
        save_cpu_to_task(cpu, cpu.current_task)

    cpu.saved_mode    = cpu.mode
    cpu.saved_pc      = t.faulting_pc & 0xFFFFFFFF
    cpu.cause_reg     = t.cause & 0xFFFFFFFF
    cpu.badvaddr_reg  = t.bad_vaddr & 0xFFFFFFFF
    cpu.mode          = target_mode
    cpu.pc            = target_pc
    cpu.next_pc       = (cpu.pc + 4) & 0xFFFFFFFF
    cpu.in_trap_handler = True
    # If we're delivering to an installed supervisor handler, swap in
    # the mappings the supervisor had at install time. The handler VA
    # may not be reachable in the trapping task's address space, but
    # save_cpu_to_task above already captured the trapping task's
    # mappings; ERET via load_task_to_cpu restores them.
    if handler_va is not None and t.cause in cpu.trap_handler_mappings:
        cpu.mappings = list(cpu.trap_handler_mappings[t.cause])
    if t.cause == CAUSE_EXTERNAL_INTERRUPT:
        cpu.status_ie = False
    # If we trapped while parked at a CALL waiting on a primitive (or at
    # a remote OL/OS waiting on a response), the handler is taking over.
    # Drop the wait state — ERET will return us to the trapping
    # instruction, which can re-issue the CALL/load if it needs to.
    cpu.blocked_on    = None
    return True


def report_trap(cpu: CPU, t: Trap) -> None:
    prefix = f"CPU{cpu.pid} " if (cpu.system and cpu.system.n_cpus > 1) else ""
    print(f"simorisc: {prefix}trap {CAUSE_NAMES.get(t.cause, hex(t.cause))} "
          f"(cause 0x{t.cause:02x}) at PC=0x{t.faulting_pc:08x}: {t.detail}",
          file=sys.stderr)
    print(f"  PC=0x{cpu.pc:08x}  next_PC=0x{cpu.next_pc:08x}  "
          f"cycles={cpu.cycles}", file=sys.stderr)
    for i in range(0, 32, 4):
        row = "  " + "  ".join(f"r{j:>2}=0x{cpu.gpr[j]:08x}"
                               for j in range(i, i+4))
        print(row, file=sys.stderr)
    for i in range(0, 16, 2):
        print(f"  o{i:>2}=0x{cpu.opr[i]:016x}  "
              f"o{i+1:>2}=0x{cpu.opr[i+1]:016x}", file=sys.stderr)


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------

SERVICE_SPEC_RE = re.compile(
    r'^(?P<pid>\d+)=(?P<idx>\d+)@(?P<caps>0[xX][0-9a-fA-F]+|\d+)$')


def install_external_services(cpu: CPU, specs: List[str]) -> None:
    """Synthesize references to remote services and install them in
    O5..O5+len(specs)-1. Each spec is `PID=INDEX@CAPS` (caps may be
    decimal or 0x-hex). Generation is fixed at 1 by convention; the
    remote endpoint is responsible for using the same generation."""
    slot = 5
    for spec in specs:
        m = SERVICE_SPEC_RE.match(spec)
        if not m:
            sys.exit(f"simorisc: bad --service spec: {spec!r}; "
                     f"expected PID=INDEX@CAPS")
        pid_v = int(m.group("pid"))
        idx_v = int(m.group("idx"))
        caps_v = int(m.group("caps"), 0)
        if pid_v < 0 or pid_v > 255 or idx_v < 0 or idx_v >= (1 << 24) \
                or caps_v < 0 or caps_v > 0xFF:
            sys.exit(f"simorisc: --service spec out of range: {spec!r}")
        if slot > 15:
            sys.exit("simorisc: too many --service specs (O5..O15 limit)")
        # "0=0@0" is the conventional pad/skip placeholder. Emit a
        # literal-zero ref rather than make_ref(gen=1, ...)'s
        # 0x0001000000000000 sentinel — a literal zero is what
        # OISN considers null and what callers expect when checking
        # "is this slot empty." (Pre-Phase-45a code that just used
        # the slot as scratch isn't affected — both encodings have
        # caps=0 and would trap on inspect either way.)
        if pid_v == 0 and idx_v == 0 and caps_v == 0:
            cpu.set_opr(slot, 0)
        else:
            ref = make_ref(generation=1, home=pid_v, index=idx_v, caps=caps_v)
            cpu.set_opr(slot, ref)
        slot += 1


def populate_self_service(cpu: CPU) -> None:
    """In socket-mode single-CPU configurations, allocate a service
    object on the local CPU and install its full-cap reference in O4
    (mirrors the role of populate_service_objects in multi-CPU)."""
    ref = cpu.alloc_object(SERVICE_OBJ_SIZE, type_tag=TAG_SERVICE,
                           max_caps=CAP_R | CAP_W | CAP_S | CAP_V | CAP_C)
    cpu.set_opr(4, ref)


def _maybe_reexec_under_pypy() -> None:
    """Headless perf (simulator-perf-proposals #1): re-exec the sim under PyPy
    for ~12x throughput when opted in via ORISC_USE_PYPY.  Skipped when already
    on PyPy, when pypy3 isn't installed, or when the opt-in isn't set — all fall
    back to CPython silently.  (Tk runs fine under PyPy — it ships tkinter 8.6 —
    so --display tk is NOT skipped; the WM gets PyPy too, verified pixel-
    identical against CPython.)  The re-exec replaces this process (inherits stdio/cwd/env) so it
    doesn't return on success; a guard env var prevents an exec loop.  Devices
    (oriscbar/oriscdir/hostfsd) stay on whatever invoked them — they're
    I/O-bound, not JIT-helped, and start faster under CPython."""
    import os, sys, shutil
    if os.environ.get("ORISC_USE_PYPY", "") in ("", "0", "no", "false"):
        return
    if sys.implementation.name == "pypy":
        return
    if os.environ.get("_ORISC_PYPY_ACTIVE"):
        return
    argv = sys.argv[1:]
    pypy = shutil.which("pypy3")
    if not pypy:
        return
    os.environ["_ORISC_PYPY_ACTIVE"] = "1"
    if sys.stderr.isatty():   # interactive only — keep piped/test stderr byte-clean
        sys.stderr.write("simorisc: re-exec under PyPy for speed "
                         "(set ORISC_USE_PYPY=0 to disable)\n")
        sys.stderr.flush()
    os.execv(pypy, [pypy, os.path.abspath(sys.argv[0])] + argv)


def main(argv: List[str]) -> int:
    _maybe_reexec_under_pypy()
    ap = argparse.ArgumentParser(prog="simorisc",
        description="Object RISC instruction-set simulator")
    ap.add_argument("orx", help="path to .orx binary")
    ap.add_argument("--processors", type=int, default=1,
                    help="number of Object RISC processors (in-process; "
                         "default 1). Mutually exclusive with --connect.")
    ap.add_argument("--connect", default=None, metavar="SOCKET",
                    help="connect to an external oriscbar at this UNIX "
                         "socket path; runs as a single-CPU process")
    ap.add_argument("--pid", type=int, default=0,
                    help="processor identifier this CPU presents to the "
                         "external crossbar (default 0; ignored without "
                         "--connect)")
    ap.add_argument("--service", action="append", default=[],
                    metavar="PID=INDEX@CAPS",
                    help="install a synthesized remote service reference "
                         "in O5..O15. Repeatable; ignored without "
                         "--connect.")
    ap.add_argument("--serve", action="store_true",
                    help="in --connect mode: don't exit when the local "
                         "task goes idle; keep polling the crossbar for "
                         "incoming SENDs and handler dispatches until "
                         "the socket closes or a signal arrives. Use this "
                         "for server-style CPUs.")
    ap.add_argument("--reset-on-exit", action="store_true",
                    help="in --connect mode: when the running task hits "
                         "TaskExit, don't terminate the process — wipe all "
                         "state and re-run init from the loaded .orx. "
                         "Used for MVP program-spawning: pre-spawned spare "
                         "CPUs run the chunkboot loader, run a guest "
                         "program, exit, reset, re-announce — making the "
                         "CPU a reusable boot target.")
    ap.add_argument("--trace", action="store_true",
                    help="print each retired instruction with register effects")
    ap.add_argument("--profile", action="store_true",
                    help="run a daemon-thread statistical sampler that flushes "
                         "a main-thread phase breakdown + per-CPU instruction "
                         "counts to /tmp/orisc-profile-pid<N>.txt every ~2s "
                         "(survives the SIGKILL oriscrun uses to tear down "
                         "Tk-blocked WM CPUs). Also enabled by the "
                         "ORISC_PROFILE env var, so `ORISC_PROFILE=1 make boot` "
                         "profiles every CPU in the fleet (WMs are pid 2/3).")
    ap.add_argument("--max-cycles", type=int, default=None,
                    help="cycle bound. Default 10_000_000 in standalone "
                         "mode (a CI-friendly safety net for runaway "
                         "tests); 0 / unset in --connect (socket) mode "
                         "means unlimited — interactive sessions are "
                         "owned by the crossbar lifecycle, not by an "
                         "instruction count. Pass an explicit value to "
                         "override either default.")
    ap.add_argument("--display", choices=["none", "tk"], default="none",
                    help="Phase 60 — host display backend for "
                         "TAG_FRAMEBUFFER objects (allocated via "
                         "ObjAllocFramebuffer). 'tk' opens a Tk "
                         "window per framebuffer this CPU allocates "
                         "and mirrors stores into it; 'none' (default) "
                         "leaves framebuffers as plain bytearrays — "
                         "the firmware path still works, just nothing "
                         "appears on screen.  Headless CI keeps the "
                         "default; interactive boots pass --display tk.")
    ap.add_argument("--init-r4", type=int, default=0,
                    help="initial R4 value for the loaded program. "
                         "Read by libc task_init via crt0's "
                         "_orisc_init_r4 stash; programs use it to "
                         "carry a small int from boot args (e.g., "
                         "oriscwm uses it as its terminal index). "
                         "Defaults to 0 (== task_my_terminal_idx() "
                         "of -1 'no info' for libc-aware programs).")
    ap.add_argument("--mode", choices=["user", "supervisor", "firmware"],
                    default="supervisor",
                    help="initial privilege mode of the loaded task "
                         "(Volume II §13). Default 'supervisor' so all "
                         "existing programs keep working; pass 'user' to "
                         "verify a guest stays out of LCTRL/SCTRL/MapObject/"
                         "InstallProgram, or 'firmware' to allow TLB ops.")
    args = ap.parse_args(argv)
    initial_mode = {
        "user": MODE_USER,
        "supervisor": MODE_SUPERVISOR,
        "firmware": MODE_FIRMWARE,
    }[args.mode]

    if args.connect is not None and args.processors != 1:
        sys.exit("simorisc: --connect implies single-CPU; --processors "
                 "must be 1 (its default)")
    if args.processors < 1 or args.processors > 16:
        sys.exit("simorisc: --processors must be in [1, 16]")

    text_bytes, data_bytes, entry, stack_size = load_orx_file(args.orx)

    system = System(args.processors)
    system.trace_enabled = args.trace

    if args.connect is not None:
        # Replace the default in-process crossbar with a socket one
        # bound to the user-specified pid.
        cpu = system.cpus[0]
        cpu.pid = args.pid
        socket_xbar = SocketCrossbar(args.connect, args.pid,
                                     trace_enabled=args.trace)
        system.crossbar = socket_xbar
        system.serve_mode = args.serve
        socket_xbar.attach_port(args.pid, cpu)
        cpu.trace_enabled = args.trace
        # Stash the boot inputs so reset_cpu can re-init verbatim on
        # TaskExit. --reset-on-exit only meaningful in --connect mode
        # (otherwise there's no socket to keep alive).
        cpu.reset_args = {
            "text":       text_bytes,
            "data":       data_bytes,
            "entry":      entry,
            "stack_size": stack_size,
            "services":   args.service,
            "init_r4":    args.init_r4,
        }
        cpu.reset_on_exit = args.reset_on_exit
        cpu.initial_mode  = initial_mode
        init_cpu(cpu, text_bytes, data_bytes, entry, stack_size)
        if args.init_r4:
            cpu.set_gpr(4, args.init_r4 & 0xFFFFFFFF)
        populate_self_service(cpu)
        install_external_services(cpu, args.service)
        snapshot_boot_state(cpu)
        cpu.mode = initial_mode
        if args.display == "tk":
            cpu.display_worker = TkDisplayWorker()
    else:
        system.crossbar.trace_enabled = args.trace
        for cpu in system.cpus:
            cpu.trace_enabled = args.trace
            cpu.initial_mode  = initial_mode
            init_cpu(cpu, text_bytes, data_bytes, entry, stack_size)
            if args.init_r4:
                cpu.set_gpr(4, args.init_r4 & 0xFFFFFFFF)
            cpu.mode = initial_mode
            if args.display == "tk":
                cpu.display_worker = TkDisplayWorker()
        populate_service_objects(system)
        for cpu in system.cpus:
            snapshot_boot_state(cpu)

    # Resolve the cycle bound. Default is 10M for standalone (a CI
    # safety net for runaway tests); 0 / unset in --connect mode means
    # unlimited because interactive sessions are owned by the
    # crossbar lifecycle, not by an instruction count.
    if args.max_cycles is None:
        max_cycles = 0 if args.connect is not None else 10_000_000
    else:
        max_cycles = args.max_cycles

    import os
    profile_on = args.profile or (
        os.environ.get("ORISC_PROFILE", "") not in ("", "0"))
    if not profile_on:
        try:
            return system.run(max_cycles)
        finally:
            system.crossbar.close()

    # --profile: a statistical sampler running in a DAEMON thread that
    # flushes to disk every ~2s.  Why not cProfile: the WM CPUs run Tk on
    # their main thread (oriscrun's own note: "Tcl/Tk's runloop on macOS can
    # sit on signals briefly") and oriscrun SIGKILLs ~2s after SIGTERM, so a
    # clean exit-time dump races the kill and loses — only the lighter
    # supervisor CPUs win it.  A daemon sampler is independent of main-thread
    # signal delivery, SURVIVES SIGKILL (the last 2s flush is already on
    # disk), only READS frames (thread-safe), and still yields the
    # function-level split that decides whether direct-handoff is the right
    # lever.  Each simorisc is its own process → per-pid file; WMs are 2/3.
    import threading, collections, atexit
    import time as _time
    prof_pid = args.pid if args.connect is not None else 0
    outpath = "/tmp/orisc-profile-pid%d.txt" % prof_pid
    # co_name -> coarse phase bucket; first match walking innermost->outer.
    # NB: C builtins (time.sleep, socket.recv) have no Python frame, so a
    # main thread parked in them shows as its Python CALLER — `run` itself
    # (the idle time.sleep at the bottom of the loop) or `poll_incoming`
    # (the blocking socket recv).  Hence `run` -> idle/loop overhead.
    PHASE = {
        "run": "idle / loop overhead (mostly time.sleep waiting for input)",
        "step": "instruction execution (step)",
        "dispatch_call": "CALL primitives (render blits / ObjAlloc / fetch)",
        "_repaint": "display (Tk repaint)",
        "_drain_pending": "display (Tk repaint)",
        "tick": "display (Tk pump/repaint)",
        "_process_requests": "memory requests (OBJ_READ/WRITE byte-fetch)",
        "_handle_obj_read_req": "memory requests (OBJ_READ/WRITE byte-fetch)",
        "_handle_obj_write_req": "memory requests (OBJ_READ/WRITE byte-fetch)",
        "poll_incoming": "crossbar transport (IPC)",
        "_wake_blocked_tasks": "scheduling (wake/unblock)",
        "_try_unblock": "scheduling (wake/unblock)",
        "_try_unblock_queue": "scheduling (wake/unblock)",
        "_try_unblock_response": "scheduling (wake/unblock)",
        "dispatch_handler": "scheduling (handler dispatch)",
    }
    _buckets = collections.Counter()
    _inner = collections.Counter()
    _nsamp = [0]
    _main_tid = threading.main_thread().ident
    _stop = threading.Event()
    _lock = threading.Lock()

    def _write_profile(*_a):
        try:
            with _lock:
                buckets = dict(_buckets)
                inner = _inner.most_common(30)
                n = _nsamp[0] or 1
            with open(outpath, "w") as fh:
                fh.write("=== simorisc sampling profile  pid=%d ===\n"
                         % prof_pid)
                fh.write("samples=%d  (daemon sampler; flush 2s)\n\n"
                         % _nsamp[0])
                tot = 0
                for c in system.cpus:
                    tot += c.cycles
                    fh.write("CPU%d instructions=%d\n" % (c.pid, c.cycles))
                fh.write("total instructions=%d\n\n" % tot)
                fh.write("--- main-thread time by PHASE (%% of samples) ---\n")
                for name, cnt in sorted(buckets.items(),
                                        key=lambda kv: -kv[1]):
                    fh.write("  %6.2f%%  %s\n" % (100.0 * cnt / n, name))
                fh.write("\n--- innermost functions (detail) ---\n")
                for (short, lineno, func), cnt in inner:
                    fh.write("  %6.2f%%  %s:%d(%s)\n"
                             % (100.0 * cnt / n, short, lineno, func))
        except Exception as e:
            sys.stderr.write("simorisc: profile write failed: %s\n" % e)

    def _classify(fr):
        f = fr
        inner_name = None
        bucket = None
        while f is not None:
            nm = f.f_code.co_name
            if inner_name is None:
                inner_name = (f.f_code.co_filename.rsplit("/", 1)[-1],
                              f.f_lineno, nm)
            if nm == "sleep":
                bucket = "idle (loop waiting on input/socket)"
                break
            if nm in PHASE:
                bucket = PHASE[nm]
                break
            f = f.f_back
        return (bucket or "other"), inner_name

    def _sampler():
        last = _time.time()
        while not _stop.is_set():
            try:
                fr = sys._current_frames().get(_main_tid)
                if fr is not None:
                    bucket, inner_name = _classify(fr)
                    with _lock:
                        _buckets[bucket] += 1
                        if inner_name is not None:
                            _inner[inner_name] += 1
                        _nsamp[0] += 1
            except Exception:
                pass
            if _time.time() - last >= 2.0:
                _write_profile()
                last = _time.time()
            _time.sleep(0.002)
        _write_profile()

    threading.Thread(target=_sampler, daemon=True).start()
    atexit.register(_write_profile)
    try:
        return system.run(max_cycles)
    finally:
        _stop.set()
        _write_profile()
        system.crossbar.close()


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))