Expected desktop log chain:

Expected server log chain:

Model execution now goes through Pi SDK events. The old [agents/openai] manual-stream logs do not appear on the main path. See model providers.

Diagnosis:

If desktop shows Invalid signature, check signAgentAction() and make sure undefined fields are omitted before signing.

If no partial publish appears, inspect the session (desktop session page or GetSession) for a durable error event from the Pi or provider path.

If server logs skip partial; no subscription, desktop is not subscribed to the target session or account. See WebSocket subscriptions.

If desktop logs partial state updates but the UI does not render, inspect AgentSessionPage and PartialAssistantRow.

Known fixed cause:

signing an action object with afterSeq: undefined encoded differently across the sign and verify paths.

Current mitigation:

signAgentAction() recursively omits undefined fields;

Subscribe omits afterSeq when not provided.

If it happens again:

log the action shape before signing, without private content;

check that the client and server agree on the protocol version (X-Agents-Protocol), since both import their types from agents/protocol (see the signed API);

check CBOR encoding behavior (see blobs for DAG-CBOR);

add a regression test.

The Seed server receives text deltas from Pi SDK message_update events. If no deltas appear:

inspect the session for a durable error event;

verify the provider API key and model name;

check whether the provider or backend supports streaming for the selected Pi API mapping;

add temporary local diagnostics around #runPiAgent() if needed, without logging secrets or full session content.

Check the tool result event in the session log. read takes one address, and the address shape picks the source. So first check that the address has the shape the agent meant.

Common causes:

malformed HM URL or web URL;

URL cannot be resolved with hypermedia headers;

resource fetch fails;

output exceeds 256 KiB (MAX_TOOL_RESULT_BYTES);

a memory path that does not exist. A directory address without its trailing slash does not fail: read answers with the listing.

An hm:// read can return not-found for a document the agent just published. That means the service's SEED_AGENTS_HM_SERVER_URL points at a different node than the one the write went through. Check /api/health for the URL in effect. Reads never fall back to a public gateway. Every read-path HM request times out after 30s (The operation timed out in the tool result), so an unresponsive server does not hang the run.

This is touch-expand, and it is expected. A call with a missing or invalid input, or for a tool the thread has not expanded yet, answers with the tool's contract. The model reads it and calls again correctly. When the contract arrives in the transcript, it also promotes that tool to a provider tool for the rest of the thread.

If a tool keeps returning its contract, compare the model's input against the input schema in read ~/tools/<name>. If a tool is missing from ~/tools entirely, there are two causes. It is not in the agent's grants (definition.tools; ListAgentTools reports granted: false). Or the host withholds it: execute is dropped when the sandbox probe fails, and /api/health reports this as codeExec: false with a reason.

Verbs the user runs through the wrench palette append to the same log as actor: 'user' events. The agent reads them on its next turn. If the agent seems not to know:

Run GetSession and check that the tool_call and tool_result events are there with actor: 'user'.

InvokeSessionTool returns 409 while a run is live. Use the palette between turns.

The result is context for the NEXT turn. Nothing is pushed into a turn already in flight.

The server rejects secret submission to remote plain HTTP servers. Use HTTPS or local loopback.

Since the runs rework, sessions.status is a derived mirror of run state, and a crash cannot wedge it. The boot sweep requeues interrupted runs. Interrupted tool calls get synthesized results. A boot reconcile pass replays children that finalized inside a crash window. If a session still shows streaming:

Run ListRuns {sessionId} and check whether the latest root run is live (queued, claimed, running, or waiting). The mirror says streaming if and only if it is.

A run waiting with wait_cbor {reason: 'children'} is parked on delegated children. Inspect the tree with ListRuns {rootRunId} and check each child's status. reason: 'timer' (with not_before) wakes on schedule. reason: 'event' is parked on ctx.waitForEvent and needs a wake source: a SignalRun (the run's wait.answerWith names the signal, and the card's Answer button sends it), a trigger with a wake continuation, a matching activity event, or its own timeout. reason: 'budget-pause' waits for a person to resume it.

StopSession aborts the live turn AND cancels every run rooted at the session, including descendants. CancelRun on any run id is the finer kill switch, and it cascades to that run's subtree.

Restarting the service is always safe: sweep and reconcile recover every documented crash window.

The row links to its child through the parent transcript's tool_spawn event. delegate appends that event as soon as the child run and session exist, so you can open a live delegation while the child is still queued or its model is still processing the prompt. Two cases fall back to finding the child through the run tree, where the child run's parent_tool_call_id names the call: a transcript from before that event existed, and a call whose spawn threw before the child was enqueued. If a row with a live child still shows the spinner text, check GetSession for a tool_spawn with that toolCallId. If it is absent, the server that ran the turn predates the event.

Checklist, in order:

Was the child awaited? delegate with await: false is detached by design. The child joins the parent's run tree (visible in the progress card), but it never resolves a result and never wakes the parent. Check the parent transcript for the delegate input the model sent. If the model keeps detaching work whose result it needs, report it as a prompt problem. The verb's description steers the model to the awaited default.

Run ListRuns {rootRunId} on the parent's root and check whether the children are terminal while the parent is waiting. The parent's wait_cbor.toolCallIds should shrink as each child's finalizer appends the durable delegate toolresult. A restart runs #reconcileWaitingRunsAtBoot, which replays any child that finalized without resolving its parent. That pass exists because a child's terminal commit and its parent's wait resolution are separate transactions.

A child that never delivered a required typed result does not vanish quietly. The parent run records unmetObligations: [{kind: 'typed-result'}], which GetRun returns and the card shows.

Where errors surface: a failed run's error_cbor shows in RunInfo.error and on the card. Failed script effects appear as result {status: 'failed'} journal entries, visible in the card's Activity drawer and in GetRunJournal. Agent-run failures also append a durable session error event after retries run out.

In both cases the runtime is keeping the card accurate, and both show in the plan snapshot:

A step marked done with resolvedBy: 'runtime' was closed by the runtime: every child attached to that step came back succeeded. The runtime only derives success this way. It does not decide what a failed child means.

A plan with settledAt set has had every step reach a terminal status. At that point the card can leave the pinned slot and freeze into the log. An edit that reopens a step clears settledAt.

A settled plan disappears from SessionInfo.plan on the next user message. This is retirement. The new turn clears the session's snapshot so the model plans the new task from scratch. The settled copy stays on the run that owned it (RunInfo.plan), and the frozen transcript card renders that copy.

Symptom: health, API, and WebSocket requests all time out, the container stays "Up", and CPU sits at ~100% on one core. Bun runs JS on a single thread, so any synchronous infinite loop wedges the whole server (HTTP, WS, triggers) while the process looks healthy from outside.

Fast diagnosis:

docker stats: one core pegged with flat network I/O points to a JS busy loop, not load;

docker logs -t --tail 50: find the last event before the logs went silent, and look for a tool call start with no matching tool call end;

strace -p <pid> -c on the host: repeated reads of /proc/self/statm plus futex and sched_yield are GC allocation checks inside a spinning JIT loop;

full tool inputs are stored in session_events (DAG-CBOR in event_cbor) even when the log line is truncated. Decode them and replay the input against the suspect code path locally. See persistence.

One past cause (fixed 2026-07): parseMarkdown in @seed-hypermedia/client looped forever on an indented ATX heading ( ### Foo). The heading branch matched the raw line while the paragraph collector excluded the trimmed line, so the tokenizer never advanced. Agent-generated document.create and comment.create markdown hit this within minutes of every restart. The tokenizer now guarantees forward progress on each iteration.

Confirm the desktop points at the same server URL and database. The server has no unauthenticated listing. To check what an account owns, send a signed ListAgents to /api/message as that account.

For local data only:

Restart the server.