> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec 086 v0 1 prism refresh no reboot runtime rehydrate

# SPEC-086 v0.1 — prism\_refresh No-Reboot Runtime Rehydrate

**Status:** draft — Donna approved direction; implementation lane open.
**Author:** Texi
**Reviewer:** Donna
**Origin:** Frank operator request, 2026-05-05

## Summary

`prism_refresh` lets an already-bootstrapped agent rehydrate runtime control
state without a full reboot or new controller registration.

The verb is intentionally distinct from `prism_start`: start means bootstrap
or re-register; refresh means "I am still the same session, give me the latest
runtime settings and delivery state."

## Contract

`prism_refresh(pid)` MUST:

* require an already bootstrapped session;
* avoid deregister/register churn;
* avoid master election or preemption churn;
* refresh the session TTL;
* return and apply current server `agent_runtime_config`;
* restart MCP-side idle tickler settings immediately;
* drain and return full pending signal envelopes;
* report BIOS/template drift and concise instruction deltas;
* mark instruction-context changes as soft until fresh bootstrap;
* enforce a minimum 5 second refresh interval per session.

## Runtime vs Instruction Boundary

Runtime config refresh is strong. If the server changes keepalive values,
`prism_refresh` applies them immediately in the MCP process.

Instruction refresh is soft. A model's already-loaded instruction context does
not change because files changed. `prism_refresh` can return concise changed
rule excerpts and ask the agent to consciously adopt them, but a fresh
bootstrap remains the hard reload boundary.

## Backend

Add:

```text theme={null}
POST /api/v1/sm/sessions/{session_id}/refresh
```

The endpoint refreshes Redis TTL using the same session-store path as
heartbeat and returns:

```json theme={null}
{
  "ok": true,
  "ttl_remaining": 90,
  "master_refreshed": false,
  "agent_runtime_config": {
    "version": 1,
    "source": "server_register",
    "idle_tickler_enabled": true,
    "idle_tickler_threshold_ms": 270000,
    "idle_tickler_min_ms": 240000,
    "idle_tickler_max_ms": 1800000,
    "idle_tickler_interval_ms": 30000,
    "idle_tickler_jitter_fraction": 0.2
  },
  "min_refresh_interval_seconds": 5
}
```

If called faster than the per-session interval, backend returns `429` with
`retry_after`. If the session no longer exists, backend returns `410` and the
agent must call `prism_start`.

## MCP Verb

`prism_refresh` returns:

* `ok`;
* `session_id`;
* `refreshed_at`;
* backend refresh response;
* previous/current tickler diagnostics;
* `pending_signals` full envelopes;
* `pending_signal_count`;
* `instruction_delta`;
* operator-facing instruction string.

When `pending_signals` is non-empty, the caller MUST follow BIOS 2.4.1 signal
discipline: ACK each signal with `model_acted`, classify and act on the
envelope, then reply via `prism_signal` when needed.

## Phase B Compatibility

This refresh substrate is compatible with future live runtime-config control:

* server-side version/epoch can be added to `agent_runtime_config`;
* `prism_refresh` remains the explicit pull path;
* a future websocket control-plane envelope can trigger refresh without using
  model-visible `signal_queue`.

## Acceptance

* `prism_refresh` works for an active session without new registration rows.
* Keepalive/tickler settings apply immediately after refresh.
* Full pending signal envelopes are returned.
* Refresh faster than 5 seconds is rate-limited.
* BIOS deltas are surfaced with `restart_required_for_instruction_context`.
* `prism_start` remains the hard bootstrap boundary.