Skip to content

Latest commit

 

History

History
314 lines (278 loc) · 33 KB

OPENCODE_COMPATIBILITY.md

File metadata and controls

314 lines (278 loc) · 33 KB

OpenCode compatibility and runtime qualification

Background shell inventory

Status consumes GET /api/experimental/job?kind=shell&status=running through the authenticated runtime transport, with a ten-second request lifetime and 4 MiB response bound. The pinned client lacks this operation, so opencode/background-shells.ts validates its shell-ID projection. The selected Location's shell.list supplies command metadata; the owned /api/workspaces/:id/background-shells route intersects the records and checks session ownership. Missing or invalid inventory produces a panel load error. Output/removal retain native Shell routes and cursors. Runtime admission remains governed by the required contracts below.

Qualification policy

Server, UI and the source pruning package use Zod 4 for application validation. Keep strict fields, collection bounds and native JSON Schema parity intact. Parsed input defaults use prefault; partial enum-keyed maps use partialRecord. Validation-admission regressions observe the actual route array parsers; qualify their observations with positive and disabled-guard controls.

Qualify the pinned client/plugin dependencies (moved together) against the technical minimum and @opencode/cli@latest before publishing; CI records the resolved runtime. Review a release from its exact tags, published npm packages and an authenticated isolated OpenAPI dump (the tagged packages/protocol/openapi.json can lag the runtime), never GitHub's compare view; release notes are at opencode.ai/changelog (GitHub Releases cover V1 only). Keep results in the PR and CI logs, never as per-version sections here.

Minimum and recommended runtime 2.3.2 (runtime-support.ts), with 2.3.2 client/schema/plugin pins and the matching effect 4.1.0. CodeNomad qualifies only the 2.3 subagent contract: every subagent call returns at once (metadata.status: "running") and the child reports to its parent through synthetic <subagent sessionID state …> messages, one per idle period, tagged running while background work remains (the subagent card in TRANSCRIPT.md, scripts/test-missions-native-trajectory.mjs, scripts/test-subagent-nesting-native.mjs). The minimum also carries the image tool contract of upstream #60258, consumed by the Images gallery, the Design agent and skills and the Images settings: one name, experimental_image_generate, for the tool, its permission action, its job type and its completion notices' metadata.source (IMAGE_TOOL in session-pruning/assets-gallery-proof.ts), and the tool offered while an image model is available unless experimental.image_generate is false (image-settings.ts reads it that way). Notices wrap their text in <image id="…" state="…">; the gallery reads the Saved image: <path> ( line. The minimum also provides the replay contract (below) consumed by the pinned reducer and Code Mode JavaScript run-to-completion, whose regression scripts/test-codemode-jobs-native.mjs runs in CI against minimum and latest. Daemons below the minimum are refused with native_contract. Plugins share the host-provided Effect/Schema runtime. Unlisted/prerelease/custom/future labels undergo authenticated contract recognition; missing canonical APIs, session environment or the replay shape give a concrete reason. OpenCode reads older stored data.

Missions schedules qualify the consumed Automation API, effective experimental.automations flag and retained plugin/provider bundle independently of general runtime admission: native contracts and transport. Recognition uses the consumed capabilities, including on future versions. Schedule delivery qualification uses the minimum/latest CI matrix, including cold scheduled passage admission with the retained product bundle and CodeNomad backend closed; keep results in PR/CI evidence. Context hooks retain native message IDs; Missions consumes the transport's native read/authority contract.

GPT-6.2 on Responses routes uses OpenCode's cacheable developer-message prefix for both ordinary steps and provider compaction. CodeNomad leaves prompt assembly and token caching to OpenCode.

Native Codex subscription usage

Beyond the usage rules in PROVIDER_ACCOUNTS.md: Codex uses only the owned session's integration's first connection and its matching active ChatGPT OAuth credential (chatgpt-browser/chatgpt-headless), never Codex CLI credentials, SQLite or another saved account; WSL uses the selected daemon's credentials. Snapshots are keyed by native connection, instance, session, directory, provider and credential identity and revalidate native selection before publication; the proxy keeps blocking browser credential export and generic RPC. Fixture: node scripts/test-provider-usage-native.mjs <cli> (synthetic credentials and mocked quota HTTP only).

Side questions (/btw)

/btw calls only native session.generate({ sessionID, prompt }) through the ownership-checked proxy and shows its single text answer; the session's environment, transcript and inbox stay untouched, and closing aborts only that request. scripts/test-session-aside-native.mjs (private daemon, local provider) runs in the minimum/latest CI matrix.

Session goal (/goal)

The Status tab's goal line consumes OpenCode's built-in goal plugin (@opencode/schema/goal): the opencode.goal RPC's get({ sessionID }), which answers the Session's own Goal.State or null, and its changed event (rpc.opencode.goal.changed, { sessionID, goal }), published in the Session's Location on every write. The instance proxy refuses plugin RPCs, so GET /api/workspaces/:id/sessions/:sessionId/goal (server/routes/session-goal.ts) is the read path: it reads the Session, checks its Location's ownership, calls the fixed method in that Location and returns only the displayed fields (opencode/goal-contract.ts). The captured connection's exact authorized Location awaits native opencode.goal activation through plugin-activation.ts, within the request deadline, then revalidates session placement before its single RPC. A native rpc.method_not_found answers unsupported; activation failure, registration loss, other failures or unreadable state answer unavailable. The line shows nothing for either. Pause, Resume and Clear run the native goal command with pause, resume or clear through the composer's command path (executeCustomCommand: session admission, instructions, profile environment at the proxy); a refused command (No active goal to pause.) shows its message in a notice. The relay routes plugin RPC events to the workspace owning their Location, so the UI applies changed directly and reads only on demand, on reconnect and after its own commands (refresh rules). scripts/test-session-goal-native.mjs (private daemon, local provider whose plain reply the goal reviewer rejects, pausing the goal) runs in the minimum/latest CI matrix.

Contract notes

Agent memory qualifies the optional session instruction entry GET/PUT/DELETE contract per authenticated connection (memory/instructions-capability.ts). A valid contract declaring the routes absent keeps memory inactive silently while preserving its preference; authentication and transient/unreadable discovery remain distinct. Native child sessions get their own entries through the awaited plugin prompt-admission hook, with instruction changes carried by native context-update notices. The isolated scripts/test-memory-instructions-native.mjs checks first-call child delivery, resumed updates and independently refused native admissions. The shipped bundle's scripts/test-memory-tool-native.mjs also qualifies title-only child delivery through the real backend policy/store, disable cleanup and unrelated Location admission. Optional memory failures attempt stale-entry cleanup and allow prompts; disabled memory bypasses discovery and storage. Failed cleanup can retain the preceding entry until the next successful refresh. Cancellation, retired connections and Missions authority checks keep their blocking contracts. See Agent memory.

  • Generated client URLs keep their baseUrl prefix and pass through unchanged; scheduling classifies API paths relative to the proxy prefix.
  • The generated experimental.session methods and their session aliases use identical experimental wire routes for instructions, wait, log, import/export and stats. Stateless experimental.generate.text uses /api/experimental/generate/text; side questions use the separate session generation API. New client domains retain the proxy's explicit allowlist.
  • The Solid reducer derives projected message IDs with Session.Message.ID.fromEvent: event fixtures must use native evt_ IDs, producing msg_ rows. Catalogue invalidations refresh only previously read resources; an active-session snapshot also fetches missing running-session metadata. Tool-file omission is opt-in; transcript and pruning reads preserve their full native projection.
  • Service discovery/header construction, RPC envelopes, SessionLegacy, Form and Permission read codecs keep their consumed contracts. The private loaded Location map canonicalizes path flavor and trailing separators; pending recovery retains its existing-only leases and identity checks. Plugin setup remains activation-scoped; native services are acquired in the request graph.
  • The proxy allowlist stays closed to pairing (/api/pair, /auth/connect/*), credential export/creation (/api/credential) and experimental voice (/api/experimental/voice/session); a runtime update never widens it or retries a mutation under another contract (instance-proxy.test.ts).
  • Session creation needs an inspectable JSON object; the proxy rejects any parentID before forwarding (native parentID ignores the location).
  • Service lifecycle uses the selected CLI's status/start/password and the registration fallback, never SDK Service.ensure/stop or an assumed default port. A user's opencode service set env value overrides CodeNomad's missing-daemon start variable of the same name; per-send session.environment applies independently.
  • Plugin bundles externalize Effect and the plugin SDK; host Schema APIs differ across releases. Local plugin directories with a package name and exports resolve their entrypoints through that manifest (session-pruning/package.test.ts). Test hosts that spread the Promise plugin context must declare the credential domain. %ProgramData%\opencode is discovered after the global plugin root that config.get consumers take first; native fixtures redirect ProgramData. Package-install fixtures pass withProductRuntime's registry option (a loopback fake npm registry, Plugin controls).
  • Relied-on upstream behaviors keep their regressions: test-output-limit-native.mjs (an output-length stop settles failed/idle with one user prompt) and test-promise-tool-failure-native.mjs (rejected Promise tools settle error; permission.rejected prevents the side effect).
  • Keep the discovery and event-relay mitigations for Bus routing before Location fanout.

Replay contract

Stored-part coverage: history query storage contract.

SQL history/search, navigation/outline, gallery and pruning consume assistant session_part rows in ordinal order followed by inline content. The shared bounded message-storage.ts relation mirrors native history, including mixed messages and stored split rows while experimental.part_rows is disabled. Pruning deletes only selected split rows and inline entries under its existing claim and transaction fences. Missions assistant-message projections use the same ordered-content SQL expression, retaining their own read budgets and source fences for mixed messages.

Text/reasoning/tool/step provider data is one native field (on a key shared by a tool call and its result, the result wins). Summary compactions reference metadata.keepID, with kept text in metadata.recent; provider compactions replay from native.messages. On read, the SessionLegacy codec (@opencode/schema) upgrades stored rows/events carrying state, providerState, providerResultState or recent without rewriting bytes, and drops a compaction's providerContext.version/provenance and a providerState stored beside a providerContext. The UI reduces events with the pinned createData (stores/opencode-data.ts); mismatched pins change reasoning identity and stores/session-actions.ts refuses pruning (session-pruning-projection.test.ts). Admission therefore requires Session.Message.Assistant.Text.native without state and Session.Message.Compaction.Completed with metadata but no recent (compatibility/negotiate.ts). planner.ts hashes the SessionLegacy projection and writes surviving stored parts back unchanged (pruning.test.ts). Session archive/restore uses native session.update with archived: true|false, authoritative time.archived and session.archived/unarchived events; scripts/test-session-archive-native.mjs covers filtered cursor pages, idempotence and transcript/child preservation. The UI compaction part keeps native (normalizers.ts). The packed pruning plugin declares every bare import, including @opencode/schema (package.test.ts).

Capability-checked loaded-only pending recovery

Rules: NATIVE_INTERRUPTION_UX.md. Pruning/history methods have their own support and write checks.

The reader uses private native LocationServiceMap, Location, Form and Permission services, scoped existing-only leases and repeated inventory/object-identity checks. It preserves global/idle Forms and native numeric JSON codecs, returning complete coverage (including empty cold directories) with the caller's actual originDirectory. Bounds: 64 requested directories/selected placements, 2048 loaded keys, 1024 Forms and Permissions per placement/directory, 4 MiB UTF-8 output, a two-second reader deadline and the broker's 30-second overall deadline (including Git ownership revalidation, eight directories at a time through the Git worker). Overflow or unsafe serialization fails rather than truncates.

The UI sends at most eight directories per request within the escaped URL budget, under its own ten-second deadline; recovering a whole history on a slow filesystem can take arbitrarily long. The broker rejects overflowing raw JSON numbers (including unknown metadata) before coverage/capability admission; native numeric codec strings pass through unchanged.

GET /api/workspaces/:id/pending-requests keeps its UI wire shape and calls only POST /api/rpc/codenomad.pending-requests/snapshot?location[directory]=<root> with { "input": { "directories": [...] } }. Legacy workspace identities are rejected and never erased; workspace/connection replacement, root or candidate deletion and changed authority fence dispatch and publication. Cold UI coverage synthesizes a location from the validated native entry directory, never the browser's alias. Only HTTP 400 with a strict bounded RpcError envelope (_tag: "RpcError", type rpc.unavailable or rpc.method_not_found, message of at most 4,096 characters) means unsupported, and only after origin and candidate revalidation. Plain 404s, other errors, malformed output, authentication failures, reader errors, timeouts and overflow return non-authoritative 503s. An unverified capability is deliberately never probed during an observed compaction.

Candidate traversal constructs no cold Locations; native HTTP middleware may warm or rebuild the single bootstrap root, and root eviction or a config rebuild constructs it again. Pending recovery waits for catalogue activation at that owned root, then rechecks ownership and compaction admission and dispatches once. The authenticated, validated snapshot itself establishes coverage. Snapshots can go stale after leases release, so per-kind mutation fences and settlement tombstones stay essential.

Fixed pruning broker admission

The session-pruning, session-history, ranked-history, navigation, Images conversation, extension assets and API 4 session reads use targeted Location preparation. Workspace-record and root-Location identities, the captured connection and monotone display/deletion fences span the wait. Session descriptors establish session ownership before any activation-capable catalogue read. History prepares the selected page directory; ranked history prepares each queried directory, including continuations.

Each broker revalidates ownership after preparation, checks the same connection and signal beside dispatch and fences publication after IO. Extension grants are checked for the exact package and permission before dispatch and publication. API 4 passes its outer connection and grant check into Images resolution; the entered Images deletion fence covers admitted work through cancellation settlement and the subsequent Git exclusion. Request budgets include preparation: 15 seconds for ordinary reads/pruning, 30 seconds for batch pruning, and API 4's 19-second route with eight-second reads. Native carrier guards use the pruning request's lifetime. The fixed navigation method adaptation remains conditional on method absence.

Agent conventions

Readiness ownership fixtures await complete request JSON before one-shot follower reconciliation. Exclusive file creation exposes its name before the write settles. Replacement fixtures hold backend ACK consumption until foreign bytes are installed; overflow fixtures cancel explicitly after observing the refused complete plan.

The bundled codenomad.memory plugin exposes codenomad_memory with list, read (exact ID or title), save (title/type/text), and revision-conditional delete. It uses the native execution session as provenance and the shared authenticated memory bridge for every operation. Backend presence admits the plugin in desktop and standalone hosts; its tool is registered only while a live memory lease requests memory (opencode/memory/preference.ts writes server.memoryEnabled into the leases through setLeaseContent), and a change reaches running sessions through ctx.tool.reload(). The server still checks current enablement and session ownership on execution. Its payload, shim, leases, integrity repair and WSL translation use the shared lifecycle. Build it with build:memory; scripts/test-memory-tool-native.mjs exercises model-driven operations, safe projections, preference-following registration, useful full errors and an uncertain write response with one dispatch. Never automatically replay a memory mutation.

All managed bundle payloads (automation, memory, session-pruning, Missions runtime and Missions carrier provider) share opencode/desktop-plugin-artifact.ts for digest verification, atomic repair and bounded lock retries. Provisioning verifies both Missions payloads before publishing its shim or lease. Failures flow through the shared provisioning error deduplication and pending-request recovery notice.

Artifact identities use exact BigInt device/inode values. When Windows pathname stats report device zero, verification opens the name independently and compares both handles' device and inode identities, then rechecks the regular, single-link pathname and its size. Windows handles require a nonzero device except under the reserved \\wsl.localhost\<distro>\ and \\wsl$\<distro>\ UNC namespaces, where both handles and pathname must agree on device zero and a nonzero inode. The payload passes full SHA-256 and EOF verification; the pre-publication recheck repeats this verification for a missing pathname or WSL handle device. Known device mismatches, inode changes and links fail closed. Verification errors identify the failed file, identity, size or digest check.

  • Desktop automation and pruning provisioning follows the authenticated OpenCode connection and its config.get global discovery directory, including reconnects. Replacing a connection aborts its in-flight provisioning: opencode/desktop-plugin-provisioning.ts logs that at debug as superseded (the new connection provisions again) and keeps errors for failures on the current connection, logging each distinct failure once with its consequence and repeats at debug until a provisioning succeeds. Bundle payloads are content-addressed (<sha256>.mjs) and shared by every backend of the namespace: opencode/desktop-plugin-installation.ts publishes one only by renaming a complete temporary copy, and replaces a name that holds other bytes or is not one regular file (an earlier write cut short, a link) the same way before the entry may point at it, so concurrent installers never read a partial payload and a damaged one never blocks later connections. Never derive a running daemon's roots from backend/startup environment or CLI debug paths. OpenCode watches the entire discovery root recursively: keep changing presence leases outside it, in the sibling .codenomad/<root-hash>/ namespace. Retain existing outside-root storage; migrate inside-root storage while reading older backends' leases without writing there. WSL translates the daemon-reported paths through the selected distro only for filesystem access. Verify heartbeat stability with the isolated native automation fixture.
  • workspaceManager.desktopPluginsReady() keeps the bounded startup wait for the current backend's <lease>.ready marker. Its targeted overload takes the exact captured connection object, authorized native {directory}, request signal, optional absolute deadline and synchronous caller authority/placement assertion. Provisioning binds the owned installation to that connection object. Targeted readiness checks the Location-local pruning catalogue and a fresh presence challenge within a shared five-second budget; missing proof fails closed. Authorization precedes catalogue reads, which load native services. Each continuation checks cancellation, connection identity and the caller's monotone workspace/placement fence before admitting another effect. Use the captured connection throughout. After preparation, brokers revalidate session/Location ownership, extension grants and deletion fences, then check signal and connection immediately adjacent to their single useful dispatch. Preserve the existing no-argument callers and never retry a refused RPC as readiness. Pruning preparation v1 lives in desktop-plugin-readiness.ts: <owned-lease>.prepare/<nonce>.json contains exactly {version:1,nonce,lease,directory,expires}; <nonce>.ack echoes those fields plus incarnation. UUIDs identify the nonce and registration scope, and expires is an integer deadline at most five seconds ahead. A follower writes an ACK only after actual registration succeeds, for its exact ctx.location.directory and a currently live owned lease. Each registration/reconstruction gets a new incarnation and an owned <incarnation>.scope record {version:1,directory,incarnation}, removed before scope disposal. The backend verifies the echoed request, live lease and scope record. Preparation uses a fresh challenge each time, keeping its observation independent of cached initial activation. The result describes registration observed for that wait; the dispatch fence and native mutation guards cover the subsequent execution interval. Bounds: 8,192-byte JSON reads, 4,096 UTF-8 directory bytes, 32 concurrent requests per backend lease, 64 leases and 64 retained ACKs per follower, and 64 directory entries per lease scan. A sequential reconciliation validates every admitted lease folder and the complete response capacity before publishing any new ACK; overflow rejects explicitly. Scope admission reserves <incarnation>.claim under presence/readiness/<SHA-256 of the exact native directory>/ and scans at most 256 entries plus one overflow entry before and after exclusive reservation. All entries in that Location's namespace count, including crash residues; a full namespace refuses that Location's new scopes while preserving existing records. Presence leases and other Locations have independent capacity. Concurrent admissions recheck the bound before publishing the root <incarnation>.scope proof. Both reservation and scope files retain their creator's handle for identity-checked cleanup, and namespace directories reject symbolic links. Lease freshness uses the fifteen-second presence expiry and tolerates a filesystem timestamp up to one second ahead of the integer wall clock. Reads accept regular single-link files with matching pathname/handle identity; request directories reject symbolic links. Unknown versions, extra fields, foreign nonces/Locations, expired leases/requests and disposed scopes fail closed. Exclusive creation acquires cleanup ownership through a retained file handle. Cleanup checks its device/inode against the current regular single-link pathname and preserves replacements; partial owned writes are cleaned and exclusive-creation collisions acquire no ownership. Backends remove only their requests. Followers remove only their ACKs and scope records, reclaiming responses after requests disappear. Lease closure joins its pending requests and removes its own identity-matched request folder only when empty; foreign entries and abrupt native shutdown residues remain preserved within the admission bounds. Follower reconciliation serializes ACK writes and joins them before removing its scope record and responses. Targeted cancellation aborts and awaits settlement of its owned catalogue transport; the shared installation retains its independent claims. The five-second budget bounds admission, with cancellation settlement joined before return. A missing or failed bundle proof returns bounded unavailability. Keep logs free of profile content and credentials. Each follower handle owns its admitted marker writes. Shutdown stops admission and its timer, joins reconciliation and registration disposal, then drains those writes before releasing its observations, including on disposal failure. Marker IO stays outside normal reconciliation; failed writes retry on a later live check. Overlapping followers keep independent lifetimes, while backend lease removal and the independently running daemon keep their own owners.
  • The Design agent and skills follow backend leases, never a command or RPC. A backend requests them while an installed, enabled panel extension declares opencode.designAgent (opencode/design/demand.ts, refreshed on every extension-store change). DesktopPluginLifecycle.setLeaseContent writes the request ({"version":1,"design":true}, or an empty lease) into every session-pruning lease the backend retains, one per configuration namespace, and each new installation starts from it. Writes happen only when the request changes, through a temporary name outside the lease pattern and a rename, serialized with the heartbeat so a removed lease is never resurrected; a failed write retries at the next heartbeat. The shared presence observation (desktop-plugin-presence.ts, versioned process key) reads at most 256 bytes of each live lease: empty, unreadable, oversized or unknown-version leases request nothing, and Design is wanted while any live lease of the plugin's presence directories requests it, so one backend's expiry withdraws only its own request. The session-pruning plugin registers its agent and skill transforms once in its effect, before followPresence (opencode/design/register.ts), with content conditioned on a Location-local flag; reconciliation at the presence interval only flips the flag and calls agent.reload() and skill.reload() on an actual change, and the content loads on the first request. Never register these transforms from presence, an RPC or a command: a late registration bypasses the user's permission rules and overrides the user's own design agent or design-* skills, which always win. A runtime without agent or skill transforms gets no Design agent. opencode/design/status.ts classifies a Location's GET /api/agent: present when the prompt starts with the content mark, user otherwise, or absent. Validate with opencode/design/*.test.ts and scripts/test-design-activation-native.mjs (build the pruning bundle first); that fixture enables project discovery, so outside CI it refuses to run under the user's home unless CODENOMAD_NATIVE_FIXTURE_PARENT names a parent outside it.
  • The shared native event relay consumes upstream events before slow routing I/O. Preserve per-session/PTY/Shell and per-recipient FIFO, validated full-location ownership, invalidation/connection/workspace fences and bounded-backlog reconnect recovery. When an ownership lookup still fails after its retry, the relay evicts that cache entry and pulses that recipient's status alone (error with event routing failed, then connected), so its clients run their reconnect reconciliation (one pass per instance, with later requests coalesced into one trailing pass, ui/src/lib/trailing-resync.ts). The same pulse answers a session event whose location lookup still fails after its retry or returns an unreadable location (the failure is cached 2 s from its retry's settlement, like a resolved location; it reaches the session's recent recipients, or every recipient when none is known, and the event itself is never broadcast), and a refusal for a recipient that already received the session's events without an intervening move or deletion (a bounded per-session recipient record, kept across ownership invalidation, released by stop/error). A location a recipient never owned stays a silent rejection. Like native location subscriptions, session.moved reaches the owners of its envelope (old) location and of its destination, plus the session's recorded recipients, so the old project learns that the session left even when the envelope names only the destination. Pulses are leading and trailing, at most every 5 s, doubling to 60 s while failures persist. Each reconciliation runs every read even when one fails, always reloads the active transcript, and a failed pass retries after 1, 2, 4, 8 and 16 s; instance removal cancels the retry. Never fail the shared subscription for one recipient's lookup: that resyncs every instance. A slow recipient must not block another or the shared SDK subscriber. Validate with the relay regressions and isolated native location fixture.
  • Native OpenCode plugins share packages/server/scripts/native-plugin-build.mjs: never embed Effect or the public plugin SDK into daemon-loaded bundles (version boundaries: Qualification policy above). Each desktop runtime builder emits // CodeNomad plugin IDs: ["..."] as the payload's first line with its actual exported IDs. The content-addressed digest covers this descriptor; plugin controls use it to identify installed plugins omitted from native runtime inventory. Keep backend-side OpenTunnel isolation separate, and run the bundle regression plus isolated plugin-runtime/pruning/automation/Missions fixtures when changing this boundary.
  • The Design agent and skills exist once, as native OpenCode files in packages/server/src/opencode/design/opencode/ (agents/design.md, skills/design-*/SKILL.md, NOTICE.md, LICENSE-APACHE-2.0.txt), which also work unchanged when copied into a project's .opencode/ or the global OpenCode configuration folder; the public help links this folder for that use (docs/help/<locale>/extensions.md#design-without-codenomad), so moving it means updating those links. Each file keeps its licence notice in frontmatter comments and its references inside its own body: never add sibling files, CLI or form protocols, URLs or brand names (design/content.test.ts checks them, with the attribution of each adapted file). design/content.ts embeds the files as text through the build's .md loader and parses them strictly: bundles call loadDesignContent(); tsx cannot import .md, so checkout code and tests read the files and call parseDesignContent(). The agent prompt starts with codenomad-design-content: <DESIGN_CONTENT_VERSION>; raise the version whenever the skill, direction or recipe identifiers change. Validate content changes with that test, the self-contained bundle test in native-plugin-build.test.mjs and scripts/test-design-content-native.mjs. That native test enables project discovery, which walks every ancestor directory: outside CI it refuses to run under the user's home unless CODENOMAD_NATIVE_FIXTURE_PARENT names a parent outside it.
  • Missions provisioning installs provider.mjs as a separate content-addressed local provider beside its content-addressed runtime. The managed shim supplies native absolute {provider:{file,sha256},runtime:{file,sha256}} paths as the factory's second argument; WSL translation applies only to backend filesystem I/O. Lease release and upgrades retain both payloads for native carrier recovery. Registration paths are acquired during arming in the current native RPC graph by missions/native-schedule-installation.ts, from the own-process record under native Global state and current ServerInfo URLs, then authenticated with exact-file public Service discovery.