Q-07: Toolchain / KOS Contract

Status: ANSWERED Agent: opencode/ext-agent Timestamp UTC: 2026-05-11T03:25:00Z Claim: CLAIM | opencode/ext-agent | 2026-05-11T03:12:00Z

Prior Answers Checked

• Q-01 (pi-teams-fit): pi-teams has no built-in KOS integration. Toolchain must be exposed via prompt discipline + documentation.
• Q-06 (runtime-container-shape): Single Docker container with bind mounts. KOS toolchain is a mount question.
• Q-00 (architecture-synthesis): Recommends pi-teams, LLM-wiki, T0-T7 lifecycle. Did not specify toolchain contract.
• BUILD_STATUS.md: Current blocker is asset extraction, not toolchain. KOS build works once toolchain path is set.
• REALIGNMENT_BRIEF: Previous agents broke builds by drifting into CDI/ISO/IP.BIN repair loops instead of the validated KOS ELF path.

Short Answer

Expose KOS as a documented command contract with a fixed toolchain path, not as an installed service. The KOS toolchain already exists on relik-pi4 at /mnt/kitchen/collab/d3-tui/toolchains/kos/ (80MB, including kos-cc and sh-elf-* tools). The primary issue is that agents do not know this path -- the build script's detect_kos() function searches 4 locations but none match the actual install. Fix: set KOS_BASE once in the Docker container or a .env file, bind-mount the toolchain at /opt/toolchains/dc/kos, document the contract in LLM-wiki, and create a smoke test.

Evidence

1. KOS Toolchain Locations on relik-pi4 (verified 2026-05-11)

The collab path at /mnt/kitchen/collab/d3-tui/toolchains/kos/bin/ contains:

kos-cc, kos-c++, makeip, scramble,
sh-elf-addr2line, sh-elf-ar, sh-elf-as, sh-elf-c++filt, sh-elf-cpp, sh-elf-elfedit, ...

Critical gap: This path is NOT in the build script's detect_kos() search order. The build script searches: 1. $KOS_BASE env var (not set) 2. $ROOT_DIR/toolchains/kos/ (bundled with repo -- does not exist in current repo) 3. /opt/toolchains/dc/kos/ (does not exist) 4. $HOME/.pearl/staging/dc-sdk/dc/kos/ (dc/kos/ subdir missing)

The build script would fail: ERROR: KallistiOS not found.

The fix requires: - export KOS_BASE=/mnt/kitchen/collab/d3-tui/toolchains/kos - export KOS_CC_BASE=$KOS_BASE - Or bind-mount: /mnt/kitchen/collab/d3-tui/toolchains/kos -> /opt/toolchains/dc/kos inside container

2. What D3-TUI Actually Needs from KOS

From src/d3tui_main.c and build-dreamcast.sh:

D3-TUI does NOT need: - makeip, scramble -- these are for IP.BIN creation (out of scope per BUILD_TARGET_POLICY.md) - cdi4dc, mksdiso -- these are for CDI/ISO (out of scope) - dc-chain -- cross-compiler builder (toolchain is prebuilt) - KOS ports (kos-ports/) -- not used by current D3-TUI source

3. What Previously Broke

From REALIGNMENT_BRIEF (2026-05-10):

1. Build-image repair loops: Agents spent cycles fixing CDI/ISO/IP.BIN concatenation instead of using the validated KOS ELF path.
2. No canonical toolchain path: Without a fixed KOS_BASE, every agent session re-discovered the toolchain, leading to inconsistent build flags.
3. Unanchored repo: Work happened in a shared filesystem workspace, not a Forgejo-cloned repo.
4. Visual target drift: The W/A/R/P proof screen was not the D2 title menu target.

The realignment fix (repo anchoring + build target policy) resolved #3 and #4 but did not address #1 (toolchain path discoverability) for agents.

4. Current Build Target Policy

Active:  RG40XXV/Knulli FlycastVL emulator validation
Accept:  KOS ELF (fast validation), GDI/CHD (when FlycastVL requires disc image)
Reject:  CDI, ISO, MIL-CD, IP.BIN concatenation, physical hardware assumptions

This policy is clear. The gap: agents don't know HOW to invoke the correct toolchain to produce the accepted artifacts.

5. The kos.mk Contract File

The existing kos.mk provides the compilation contract: - SH-4 architecture flags: -ml -m4-single -mfsrra -mfsca - Thread-local storage: -matomic-model=soft-gusa -ftls-model=local-exec - Function/data sections: -ffunction-sections -fdata-sections and --gc-sections - Include paths: $KOS_BASE/include, $KOS_BASE/kernel/arch/dreamcast/include, $KOS_BASE/addons/include - Libraries: -lkos -lm - Platform defines: -D__DREAMCAST__ -D_DREAMCAST -D_KOS - Linker script: $KOS_BASE/utils/ldscripts/shlelf.xc

This file should be the single source of truth that agents consult for KOS compilation flags.

Fit For This Pi Workcell

Recommended Approach: Documented Command Contract

KOS should be exposed to agents as a documented command contract:

Should KOS Be In the Agent Image?

No -- mount it, don't bake it. The KOS toolchain (80MB) should be bind-mounted into the Docker container at /opt/toolchains/dc/kos. This keeps the Docker image small, allows toolchain updates without image rebuild, and fixes the build script's search path #3.

Recommended bind mount:

/mnt/kitchen/collab/d3-tui/toolchains/kos -> /opt/toolchains/dc/kos (inside container)

Then set KOS_BASE=/opt/toolchains/dc/kos in the container environment.

What Agents Should Know vs. Shouldn't Touch

Agents should: - Know that kos-cc is the only supported compiler for Dreamcast targets - Know to run make elf or scripts/build-dreamcast.sh elf for builds - Know to validate ELF entry point via sh-elf-readelf -h - Know that CDI/ISO/IP.BIN paths are out of scope - Consult kos.mk for compilation flags (not guess) - Consult kos-contract.md for KOS capabilities (not source-dive)

Agents should NOT: - Try to install KOS themselves - Modify KOS headers, libraries, or linker scripts - Run makeip, scramble, or ISO tools - Source-dive KOS internals to "fix" build issues - Ship KOS binaries as D3-TUI deliverables - Alter detect_kos() search paths without team lead approval

Integration With T0-T7 Lifecycle

Risks / Failure Modes

1. Toolchain path rot: If the collab path changes or the toolchain is moved, builds break silently. Mitigation: smoke test on session start.
2. Agent overreach: Agents may try to "fix" KOS when builds fail, editing linker scripts or recompiling KOS itself. Mitigation: explicit "do NOT touch" in contract doc.
3. CDI creep: Without constant enforcement, agents drift toward CDI/ISO packaging because it "feels more complete." Mitigation: build script exits with error if CDI targets are requested; prompt explicitly forbids CDI paths.
4. environ_dreamcast.sh missing from collab path: The archive has this file but the collab path doesn't. The build script handles this by sourcing environ_base.sh directly. Verify this works with the collab path.
5. Pi architecture mismatch: KOS toolchain is compiled for ARM64 (Raspberry Pi 4). If the Pi is replaced with x86 hardware, the toolchain must be rebuilt.
6. FlycastVL dependency: KOS ELF validation depends on FlycastVL being installed on RG40XXV. If the RG is unavailable, agents have no visual validation path. Build-only validation (sh-elf-readelf) is a partial substitute.
7. Asset extraction as prerequisite: The current build requires make d2-assets before make elf. If asset extraction is blocked (current state per BUILD_STATUS.md), KOS compilation succeeds but the binary is incomplete.

Decision Needed From Mehdi

1. Toolchain path: Should KOS_BASE be set to /mnt/kitchen/collab/d3-tui/toolchains/kos and exported as a Docker ENV? (Recommended: yes -- this is the only working path, and it must be automated.)
2. Bind mount: Should the toolchain be bind-mounted into the Docker container at /opt/toolchains/dc/kos? (Recommended: yes -- this fixes the build script's search path #3 without modifying the script.)
3. Smoke test: Should a .pi/smoke/kos-health.sh script be created that verifies kos-cc --version before agents can claim toolchain work? (Recommended: yes -- prevents agents from discovering the absent toolchain mid-task.)
4. Contract document: Should llm-wiki/wiki/toolchain/kos-contract.md be the canonical "what KOS is good for" reference? (Recommended: yes -- this is the smallest useful document that prevents agent drift.)

Next Probe

The smallest follow-up check: on the Pi4, run:

export KOS_BASE=/mnt/kitchen/collab/d3-tui/toolchains/kos
export KOS_CC_BASE=$KOS_BASE
source $KOS_BASE/environ_base.sh
kos-cc --version

If this succeeds, the toolchain works and only path configuration is needed. If it fails, the toolchain itself may be incomplete or architecture-mismatched.