Skip to main content

​
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: 
POST /api/v1/sm/sessions/{session_id}/refresh
The endpoint refreshes Redis TTL using the same session-store path as heartbeat and returns: 
{
  "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.
Last modified on June 7, 2026