One per-AgentId moltzapd and structurally compatible HarnessClient implementations

[chughtapan]

Harness vocabulary and implementation slate

Status: implementation handoff; non-normative

Normative authority lives in the current ADRs and docs/spec/. This slate
orders that work. It does not invent contracts absent from those sources.

Outcome

Build one local Harness shape for both implementation tracks:

generic MCP client ───────────────┐
OpenClaw ── HarnessClient ────────┼──> moltzapd
NanoClaw ── HarnessClient ────────┘      ├─ /register/mcp
                                         └─ /mcp

• Harness is the subsystem and deep package: v2/harness and
  @moltzap/v2-harness.
• moltzapd is the sole local daemon for one named profile slot.
• HarnessClient is the sole public adapter-facing Effect capability.
• Daemon internals use narrowly named private services. There is no public
  Harness, HarnessApplication, HarnessBootstrap, or
  HarnessManagement service.
• Backings retain different raw MCP messages and implementations while their
  HarnessClient service values interoperate structurally at compile time.
• The target state has no runtime generation selection, shared production
  implementation package, FastMCP dependency, bespoke CLI, Unix RPC socket,
  second MCP process, or generic send. The implementation-state section below
  distinguishes that target from landed production and open candidate work.

Scope rule

This implementation changes only decisions supported by the source transcript
or retained accepted repository authority. An unmentioned failure mode,
configuration key, retry rule, storage algorithm, resource limit, wire field,
or error mapping is not an implementation requirement.

In particular, this slate does not add:

• daemon or client quota profiles, N+1 behavior, queue sizes, or byte budgets;
• a new raw reply ConversationId or ReplyFingerprint;
• a replacement MCP extension identifier;
• checkpoint file, fsync, sharding, cache, rescan-marker, or corruption
  algorithms;
• a five-state daemon lifecycle or activation deadline;
• an exhaustive portable error taxonomy; or
• a second serialization of an in-memory runtime turn.

The retained clean-slate MCP, OpenFloor, Ledger, reply receipt, retry,
reconciliation, supervision, and explicit resource-limit deferrals remain the
implementation baseline.

Implementation state

This section reports repository state as of 2026-08-04. It does not admit or
supersede a contract.

• Landed production: origin/main@27bd6f4e includes the daemon-owned
  receive/reply foundation from Add daemon-backed HarnessClient receive path #942. Production has no dispatch package,
  LeaseId, conversation_busy, server-side reply grant, or local
  duplicate-reply guard. The daemon publishes one nonempty same-conversation
  Message batch, and HarnessClient retains the originating
  ConversationId privately for reply(payload). Every reply invocation
  sends.
• Open production candidates: refactor(client): isolate presentation state #943 isolates presentation state; feat(harness): add MCP read plane #944 adds
  paginated MCP search/history; feat(harness): add client context reconstruction #945 reconstructs context with an injected
  local Effect KeyValueStore; feat(harness): project client-owned turns #946 adds MCP-local conversation participants
  and the public presentation turn; feat(client): package moltzapd process #947 packages moltzapd; and feat(harness): start conversations through MCP #948 adds
  start_conversation. None of these candidates is present in origin/main.
• Still pending in production: durable profile-to-MCP endpoint
  acquisition, registration through /register/mcp, OpenClaw and NanoClaw
  cutover, replacement of every remaining operator workflow, and deletion of
  the generic send, bespoke CLI, and Unix socket.
• Clean-slate: origin/v2@7329cfb0 contains the reviewed Harness
  vocabulary and package rename, but v2/harness remains a scaffold and its
  moltzapd executable is not implemented. v2/transcript is also a scaffold;
  its exact representation owner and public Ledger contract remain
  prerequisites for a real clean-slate Harness composition.

Local MCP and management

One moltzapd listener serves a registration path and an active path.
Registration remains a Registry bootstrap operation presented at
/register/mcp; /mcp presents active operations.

Former CLI workflows become MCP tools. The common operator/model catalog is
formed from:

• register on the registration path;
• status as active management;
• search_agents;
• search_conversations;
• read_conversation;
• start_conversation; and
• backing-specific raw reply.

Receive remains subscriptions/listen, not a tool. On landed production, the
active catalog contains only status and reply; the registration catalog is
empty. Candidate #944 adds search_agents, search_conversations, and
read_conversation using the selected production exact-match/blank-browse
paginated behavior. Candidate #948 adds start_conversation. Those candidates
do not assign the clean-slate backing's result representations or errors.

Candidate #946 enriches the production MCP-local Conversation passed to the
HarnessClient implementation with participants. Participants are local
presentation data: the canonical production Conversation and the main
WebSocket protocol remain unchanged, and the client does not write the
enrichment back onto that wire.

The lower-layer Registry, Router, and Ledger method names and network contracts
do not change. The local MCP presentation does not create a new network plane.

Branch-owned registration work

The clean-slate daemon presents its accepted Registry bootstrap through
/register/mcp; its OperationId, admission, verification, and recovery
contracts remain clean-slate-owned.

Production registration is not implemented at /register/mcp.
origin/main still uses the existing HTTP bootstrap and CLI profile
persistence. This slate does not introduce a production OperationId,
crash-recovery, credential-staging, fingerprint, changed-input, or storage
contract. Production must either translate already owned behavior or wait for
a separately admitted main-owned registration contract. The current
clean-slate management spec describes a selected production recovery contract;
that cross-branch authority mismatch requires reconciliation before
implementation relies on it.

HarnessClient boundary

Both tracks are planned to independently implement the same consumer behavior
after their exact branch-owned contracts are admitted:

• start a conversation with other-agent names and initial content; and
• listen for turns carrying conversation-labelled context and a bound
  reply(payload) function.

Registration, status, search, and history are MCP management operations, not
public HarnessClient methods. The client uses conversation search and history
privately for checkpoint reconstruction.

Raw backing correlation stays private. The production client retains the
originating ConversationId in private MCP request metadata and every call to
the bound reply(payload) closure sends. It has no dispatch lease, reply token,
action identifier, turn identifier, or duplicate-reply suppression. The
clean-slate client retains its backing-owned TxnId and action selection
internally; plural-action projection remains with the OpenFloor/task owner.
OpenClaw and NanoClaw see none of those fields and never construct daemon or
protocol services.

Production notifications are reply-capable nonempty coalesced Message
batches, not separate content and grant events. Candidate #945 reconstructs
other-conversation content from search/history and stores stable presentation
checkpoints through an injected local KeyValueStore; candidate #946 projects
that state into the public turn. The checkpoint storage path and durable
profile integration remain unselected. The clean-slate backing retains its
separately owned content/grant and recovery mechanics.

Runtime slice 1: dispatch and ingress

Implement the receive path as equivalent track-owned applications behind the
common client behavior.

Production work:

1. Treat Add daemon-backed HarnessClient receive path #942's daemon-owned receive/reply foundation as landed.
2. Do not recreate dispatch leases, conversation_busy, server-side
   reservation, grants, holds, or local duplicate-reply suppression removed by
   refactor!: remove app principals, dispatch leases, and at-rest encryption; add programmable simulator links #941.
3. Land the read, reconstruction, participant-enrichment, and public-turn
   candidates in dependency order (refactor(client): isolate presentation state #943 through feat(harness): project client-owned turns #946).
4. Preserve the production event as one nonempty same-conversation raw
   Message batch whose reply closure privately retains its originating
   ConversationId.
5. Add durable profile-to-MCP endpoint acquisition before adapters depend on
   the packaged daemon.

Clean-slate work:

1. Admit the Transcript representation owner and exact public Ledger contract,
   then implement v2/transcript; do not invent those representations inside
   v2/harness.
2. Admit the exact management projections, content-only ingress,
   HarnessClient contract, checkpoint representation, and any required
   plural-action mapping before implementing those respective surfaces.
3. Build only admitted v2/harness daemon and client slices around the
   implemented Registry, Router, Ledger, SharedCore, and OpenFloor services.
4. Retain per-conversation grants, TxnId/action authority, Ledger recovery, the
   accepted MCP subscription, and raw reply behavior.
5. Move runtime context presentation from daemon attention watermarks to the
   clean-slate HarnessClient checkpoints.
6. Keep the raw extension backing-owned; do not introduce a shared replacement
   wire in this slice.

The clean-slate conversation-search projection waits for its Transcript-owned
result contract. This slice does not choose Conversation versus
ConversationId, invent a Harness summary, or add timestamps and read-view
persistence to close that dependency.

Common acceptance:

• production serializes and coalesces inbound work in its endpoint-local
  consumer and routes every bound reply invocation to the originating
  conversation;
• clean-slate same-conversation authority remains governed by its retained
  grant/TxnId mechanics;
• no production lease, conversation_busy, or server grant is recreated;
• listen remains sole-owner, acknowledgment-first, transient, and at most
  once; and
• after each backing's search/history representation exists, restart can
  rebuild presentation context without reconstructing reply authority.

Runtime slice 2: model output

Production work:

1. Land feat(harness): start conversations through MCP #948's start_conversation candidate: other-agent names plus required
   initial content, self implicit, using existing create-then-send mechanics
   without a new atomicity or recovery promise.
2. Migrate OpenClaw and NanoClaw from direct
   MoltZapService/MoltZapChannelCore ownership to HarnessClient and prove
   each real daemon/MCP path.
3. Remove generic send from the production server, protocol, client, CLI,
   exports, and first-party callers only after start and bound reply cover
   their required model-output behavior.
4. Remove the bespoke CLI and Unix RPC only after every first-party operator
   workflow has an MCP replacement. There is no production lease-retirement
   step; refactor!: remove app principals, dispatch leases, and at-rest encryption; add programmable simulator links #941 already removed that system.

Clean-slate work:

1. Keep direct START OperationId behavior unchanged beneath
   HarnessClient.startConversation.
2. Keep raw reply(TxnId, actionId, payload), ReplyFingerprint, certificates,
   durable results, receipts, retry, reconciliation, and errors unchanged.
3. Bind those raw fields into the portable payload-only closure rather than
   exposing them to runtime adapters.

Common acceptance:

• a production runtime starts with names and initial content and replies with
  payload only;
• the clean-slate client exposes payload-only reply only when the backing
  identifies one legal action unambiguously or its owner admits the
  payload-to-action mapping;
• a delayed production reply retains its originating ConversationId, while
  the clean-slate backing retains its own raw authority privately;
• production reply has no server grant and every invocation sends; the
  clean-slate backing continues to enforce its retained authority;
• no ungranted fallback or generic send remains; and
• the clean-slate raw wire conformance suite stays unchanged.

Delivery order

1. Treat the clean-slate authority/package rename (Define the Harness boundary and rename v2 endpoint #938) and the landed
   production receive/reply foundation (Add daemon-backed HarnessClient receive path #942) as completed prerequisites.
2. Land refactor(client): isolate presentation state #943 through feat(harness): start conversations through MCP #948 in stack order, preserving their distinction from
   origin/main until each PR merges.
3. Add a production profile-to-MCP endpoint acquisition contract. Candidate
   feat(client): package moltzapd process #947 currently requires a caller-supplied nonzero port; production profiles
   do not yet store or discover one.
4. Cut OpenClaw and NanoClaw to HarnessClient and add behavioral fake-client
   tests plus real daemon/MCP adapter integration.
5. Implement production registration and remaining operator MCP tools, then
   delete generic send, the bespoke CLI, and Unix RPC after all first-party
   replacements are operational.
6. Forward-merge landed production changes under repository branch policy.
7. Before clean-slate implementation relies on production claims, reconcile
   the current v2 ADR/spec references to production dispatch leases,
   conversation_busy, and a selected production registration-recovery
   contract with lease-free main and its unselected registration contract.
   This slate records those mismatches but does not amend or supersede those
   authorities.
8. Admit the Transcript representation owner and exact public Ledger contract,
   then implement v2/transcript and the Ledger process.
9. Admit the remaining exact clean-slate management, content-ingress,
   HarnessClient, checkpoint, and plural-action contracts before composing
   their corresponding Harness slices. Transcript readiness is not the only
   gate.
10. Finish clean-slate parity without v2/* -> packages/* imports, runtime
    generation selection, or a shared backing implementation.

Verification

Level	Required evidence
Unit	After the exact client contract lands, pure context grouping/deduplication, checkpoint transition, and lease-free bound-reply behavior using fake capabilities.
Server integration	Existing production message delivery plus clean-slate backing-owned authority tests; do not require a production conversation_busy path.
Production registration integration	Add lost-response/restart assertions only after a main-owned registration recovery contract is admitted; this slate selects none.
MCP integration	Real loopback HTTP/SSE, retained discovery/acknowledgment/listener behavior, plus backing-specific observations and generic management tools only after their representations are admitted.
Restart integration	Context reconstruction from stable checkpoints and history without grant reconstruction; retained daemon/Ledger recovery.
Adapter unit	Fake HarnessClient turns drive observable OpenClaw and NanoClaw session/callback behavior.
Adapter integration	A real peer message reaches each runtime through server, moltzapd, MCP, and HarnessClient; reply returns through its originating authority.
Conformance	After both exact branch-owned contracts land, the two service values pass the same consumer suite and bidirectional positive type canary.
Architecture	Adapters cannot import or construct daemon internals; clean-slate code cannot import production packages; deleted CLI/socket/send exports are absent.
Package/process	Candidate #947 proves packed moltzapd, direct WebSocket ownership, clean shutdown, and no daemon-created Unix socket. Final evidence must additionally prove profile-based endpoint acquisition and absence of the transitional moltzap executable.

Import or constructor inspection is an architecture check, not a unit test.
Transport and process ownership are integration or package tests, not unit
tests.

Completion criteria

• The clean-slate authority/package-rename prerequisite is landed. Any
  semantic ADR/spec reconciliation required by current production state must
  pass its own repository review gate before clean-slate implementation relies
  on it.
• Issue One per-AgentId moltzapd and structurally compatible HarnessClient implementations #926 mirrors this transcript-scoped slate.
• Both runtime slices pass their behavioral, integration, conformance,
  architecture, and package gates.
• OpenClaw and NanoClaw depend only on HarnessClient.
• No bespoke CLI, Unix RPC socket, generic send, runtime generation selection,
  or invented candidate-only operational profile remains.

[chughtapan]

Implementation progress (2026-08-01)

• Merged the current origin/v2 baseline (a7cd4184) into the implementation branch as e5f0cd7c.
• Renamed the clean-slate package/process surface from Endpoint to Harness in ba071305: v2/harness, @moltzap/v2-harness, and sole executable moltzapd.
• Updated workspace references, package dependencies, lockfile links, and architecture-boundary checks; removed the obsolete moltzap and moltzap-agentd bins.
• Verification passed through the standard cached Nx precommit graph. NX_DAEMON=false was used only to avoid a daemon watcher race; Nx caching and all gates remained enabled.

Next implementation slice: add the main-owned ConversationId dispatch reservation (conversation_busy, no lease on conflict, independent conversations continue) in a separate main-based worktree, then forward-merge it into v2. Deferred contracts listed in the issue remain deferred; this work will not invent the exact HarnessClient signatures, MCP management schemas, search projections, content-only event representation, or plural-action mapping.

[chughtapan]

Implementation progress (2026-08-01, v1-first order clarified)

• The behavioral refactor is proceeding in-line on main first. The earlier clean-slate Endpoint-to-Harness rename was preparatory only; it is not the source of production behavior.
• Committed the first production slice on agent/harness-production as b6937324: atomic ConversationId reservation, exact conversation_busy without a second lease or moderator fiber, owner-checked release (including HOLD), local park/retry, and independent progress for other conversations.
• Cached unit, integration, conformance, lint, type, docs, format, and precommit gates passed. NX_DAEMON=false was used only after an Nx watcher reset during cached docs restoration; cache remained enabled.
• Next production slice: move service/core/network ownership behind the one moltzapd MCP boundary, then implement the production HarnessClient and cut adapters over before forward-merging to the clean-slate branch.

Dependency note: the transitive @modelcontextprotocol/sdk 1.x line cannot implement the retained 2026-07-28 server/discover / subscriptions/listen contract. The official split 2.0 beta line supports that core contract, but its high-level listen event bus is closed to standard catalog/resource events. We will not misrepresent it as supporting the retained MoltZap extension or invent the deferred production event Schema; the next slice will keep that extension seam explicit.

[chughtapan]

Production-first implementation checkpoint:

• b6937324 reserves v1 conversations atomically, returning conversation_busy without creating a second lease.
• d89b378d adds the official modern MCP loopback HTTP boundary for /register/mcp and /mcp.
• a9a88865 translates the existing v1 daemon status behavior onto MCP: registration discovers no tools, the active path discovers exactly status, and an official modern MCP client observes the existing handler result. No generic send was added.

All three commits are on agent/harness-production, inline on the v1/main production track. Nx caching remained enabled. Client build, test typecheck, lint, architecture checks, 216 tests, and the full workspace precommit graph pass. The v2 Harness rename remains preparatory; forward merge and clean-slate backing work follow the operational v1 cutover.

[chughtapan]

Production-first implementation checkpoint

Draft implementation PRs: #937 targets main; #938 targets v2.

• 4ed819ba waits for an installed inbound handler before requesting dispatch authority, so startup cannot lose a lease to a handlerless adapter.
• 4164c53d separates lease-bound reply from unleased generic send. MoltZapChannelCore.sendReply now requires explicit or live in-flight authority and delegates to MoltZapService.reply; the existing production wire remains unchanged.
• 31b154cd gives the guarded /register/mcp + /mcp listener scoped process ownership, binds it to 127.0.0.1 at a caller-supplied port, and closes it on Effect Scope release. It selects no launch or port-allocation policy.

Verification is green with Nx caching enabled: client/OpenClaw/NanoClaw build, test typecheck, unit tests, lint, and architecture checks pass; 317 tests pass (223 client, 67 OpenClaw, 27 NanoClaw). The combined run served 15 of 18 tasks from cache, and both commits passed the full workspace precommit graph.

The next production slice needs admitted main-owned contracts before code can proceed without inventing scope:

1. the production subscriptions/listen extension and exact conversation-labelled content/grant representations;
2. exact HarnessClient Effect signatures, errors, context entry projection, and checkpoint representation;
3. management tool Schemas/errors plus search result projections and empty-query behavior;
4. the pre-registration profile slot, stable MCP port, launch contract, and recoverable credential staging;
5. cursor/stable-position history reads for restart reconstruction; and
6. the production raw reply/start replacement needed before deleting agent/message/send.

The existing CLI-oriented local RPC schemas do not satisfy those contracts by simple renaming. OpenClaw/NanoClaw migration, generic-send deletion, CLI/socket deletion, and the packed moltzapd gate remain downstream of these decisions.

Status: NEEDS_CONTEXT

Confidence: HIGH. The boundary is reproduced from the current branch, the transcript-scoped slate, and the governing spec deferrals.

Effort: (human: ~1 week / CC: ~3 hours)

Process issues: the generated-file precommit guard requires a clean unstaged tree, so the two concurrent slices had to be serialized through a path-limited temporary stash. Nx caching remained enabled throughout.

[chughtapan]

Production-first correction and implementation checkpoint (2026-08-01)

The earlier 4ed819ba / 4164c53d experiments were reconciled by 08d33a5d after review. The current production contract is:

• handlerless inbound notifications are transiently dropped before dispatch authority is requested;
• the existing generic send remains unchanged until a turn-bound reply closure replaces it atomically; and
• there is no new public raw-reply seam.

The production main branch implementation now also includes:

• e4475d2d: package-private acquireMoltzapd owns one MoltZapService, MoltZapChannelCore, long-lived WebSocket, and scoped MCP listener;
• d9ce6811, fee5425f, and a10e054f: partial acquisition rolls back, daemon scope close awaits transport teardown, shutdown starts while inbound cleanup is blocked, listener failures close handlers exactly once, and concurrent shutdown callers await the same cleanup; and
• 83df9e7a: reconnect waits for the preceding teardown instead of clearing its lifecycle gate.

Verification remains through normal cached Nx targets: 230 client unit tests, 39 real PGlite/WebSocket integration tests, and the 61-target workspace precommit graph pass. The live daemon integration proves no Unix socket is created by the new boundary and the server observes zero connected agents after both normal close and failed acquisition.

This work remains in-line on the production main track. The next safe production ingress handoff is internal lifecycle hygiene: make the inbound-handler registration disposable without stale disposers clearing replacements, and scope in-flight dispatch authority by ConversationId so unrelated conversations cannot inherit it. The deferred receive wire, exact HarnessClient, management/search Schemas, registration staging, history cursor, raw start/reply replacement, adapter cutover, and CLI/socket/send deletion remain deferred exactly as listed in the issue.

[chughtapan]

Production ingress handoff completed on main in 33455c0c.

• MoltZapChannelCore.onInbound now returns an idempotent, generation-scoped disposer; a stale disposer cannot clear a replacement even when the same handler function is re-registered.
• An in-flight dispatch captures its handler registration before asynchronous enrichment.
• Active dispatch authority is keyed by ConversationId, so an operation for conversation B cannot inherit conversation A's lease. Explicit authority still wins, and cleanup covers normal completion, failure, timeout, and interruption.
• Existing serial scheduling, coalescing, conversation_busy parking, and transient handlerless-drop behavior are unchanged.

The cached verification is green: 233 client unit tests, 26 NanoClaw unit tests, client/NanoClaw build/lint/test type-check/architecture gates, all 28 Mermaid blocks, and the complete 61-target workspace precommit graph. A separate read-only audit reported no blocking findings.

This checkpoint still does not choose or implement the deferred receive wire, exact HarnessClient signatures, management/search Schemas, registration staging, history cursor, or raw start/reply replacement. Generic send, the bespoke CLI, and Unix RPC therefore remain until those replacements are operational.

[chughtapan]

Production-first checkpoint 5de8acd5 closes the remaining contract-free dispatch evidence on main.

• One behavioral test now proves the complete path: conversation A receives conversation_busy and stays locally parked; conversation B is admitted and delivered; later inbound A traffic wakes the parked A head at attempt 1 and coalesces A's backlog.
• The owning flow documentation now states the exact liveness boundary: the existing retry is event-driven by later inbound work for the same ConversationId. No retry timer, backoff, queue policy, or new wakeup protocol was introduced.
• The focused dispatch suite, all 232 client unit tests, all 28 Mermaid blocks, and the 61-target cached workspace precommit graph pass. Nx caching remained enabled.

The follow-on audit found no other material v1 slice that can land without choosing a contract explicitly deferred in this issue. In particular:

• server-side consume-time lease-binding remains the explicit defense-in-depth follow-up from Move dispatch admission off the wire (4 PRs) #512, including its caller-binding and failure semantics; this change does not silently narrow that existing wire contract; and
• the old cli/start payload cannot simply be relabeled start_conversation: it requires a conversation name, permits AgentIds, makes initial content optional, exposes appId, uses an Effect transform that MCP JSON Schema alone does not execute, and has no admitted MCP projection for its tagged failures.

The next production implementation commit therefore starts with the admitted production receive wire plus exact HarnessClient Effect surface, or with an admitted MCP request/result/error contract for one of the replacement tools. Generic send, the bespoke CLI, and Unix RPC remain until those replacements are operational.

[chughtapan]

Clean-slate preparatory authority is now landed on v2 via #938 (08b8808f). This includes the reviewed Harness ADR/spec lineage, the v2/harness deep-package rename, and the production-first delivery order. It does not implement or forward-merge production behavior. The live implementation remains inline on main in #937; the next code slice is still the branch-owned production receive/HarnessClient contract identified in the issue.

[chughtapan]

The contract-supported production foundation is now landed inline on main via #937 (8ebee95c). Production now owns atomic ConversationId dispatch reservation, event-driven same-conversation retry with independent cross-conversation progress, ConversationId-scoped inbound authority, daemon-owned service/core/WebSocket lifetime, the single loopback /register/mcp + /mcp listener, existing status translation, and awaited single-flight teardown. The existing CLI/socket/generic-send path remains only because its MCP/HarnessClient replacements are not operational yet; no deferred receive or management wire was invented in this merge.