> ## Documentation Index > Fetch the complete documentation index at: https://docs.tai42.ai/llms.txt > Use this file to discover all available pages before exploring further. # Soft-restart the fleet from its manifest, restarting the drifted workers whose reload built > Soft-restart the fleet from its manifest, then restart the workers whose env needs a restart. Refreshes env from the config manager, resets every settings cache, and re-initializes from the manifest, in-process. Applied on this worker (when it is a target) and broadcast to the fleet (all workers, or only ``targets``); the response embeds the per-worker fleet report. Heavy (a full re-init); meant for env/config saves, not tool edits. A convergence op: its whole purpose is aligning siblings to persisted state, so a failed local reload still broadcasts and then re-raises with the fleet report attached. Called over MCP on a worker the reload applies to (no ``targets``, or ``targets`` naming that worker), the reload answers on the session that called it and then retires that session with the generation it ran on: a later call on the same session fails (streamable HTTP answers it 404, and an SSE session's stream closes), so the client starts a new session to go on. When ``targets`` leave that worker out, nothing reloads there and the session keeps working. An applied worker's payload is ``{status: "ok", env_keys, awaiting_respawn}``; a worker whose reload was refused at its epoch build (the build discarded before its swap) replies ``failed`` with ``{status: "discarded", awaiting_respawn}``, serving its previous epoch with that drift standing; any other failed reload, a failed discard among them, carries no payload. ``awaiting_respawn`` names the recycle-class keys whose value now differs from the one that worker bound (at boot, or when the plugin that declares them was loaded) — the soft restart carries every hot key in place, and those keys take effect only on a restart. Once the reports are in, every worker the reload addressed that names such a key is restarted one at a time through the deployment's supervisor, except a worker whose reload was refused at its epoch build: the stored config did not build on it and a restart may fail the same way, so it keeps serving its current config and is named in ``awaiting_respawn``. Any worker other than this one whose state is unknown (its reload failed otherwise or did not finish, it has no row, its reply carries no ``awaiting_respawn`` list, or the bus was unreachable) is asked once it is ready and restarted unless its reply confirms it clean or states a refused build (its restart then withheld); the workers that confirmed none are left running. This worker is never asked: when its own state is unknown, it needs its own restart. ``recycle`` reports that roll (``null`` when the roll had no worker to visit: every addressed worker confirmed no recycle-class key, or the only ones naming one were refused at their epoch build) and ``awaiting_respawn`` the workers still awaiting a respawn after it. When this worker needs its own restart and the roll converged, it exits gracefully once the reply is answered and its supervisor starts it again. A soft restart run under a bound the roll's waits can outlast (a dispatched job's budget, an armed turn budget) runs no roll itself: it hands the roll to the bus member it acts for, which carries it out after the reply and departs itself last, once the roll converged, when it needs its own restart; ``roll_deferred`` is then ``true``, ``roll_deferred_to`` names that member, ``recycle`` is ``null`` and ``awaiting_respawn`` empty, the roll not judged in this reply. Otherwise ``roll_deferred`` is ``false`` and ``roll_deferred_to`` ``null``. ## OpenAPI ````yaml /openapi.json post /api/config/reload openapi: 3.1.0 info: description: >- The operator HTTP surface served under /api/*. The platform's core routes. Plugin routes are published by each plugin. title: tai42-skeleton API version: 35.0.0 servers: [] security: [] paths: /api/config/reload: post: tags: - config summary: >- Soft-restart the fleet from its manifest, restarting the drifted workers whose reload built description: >- Soft-restart the fleet from its manifest, then restart the workers whose env needs a restart. Refreshes env from the config manager, resets every settings cache, and re-initializes from the manifest, in-process. Applied on this worker (when it is a target) and broadcast to the fleet (all workers, or only ``targets``); the response embeds the per-worker fleet report. Heavy (a full re-init); meant for env/config saves, not tool edits. A convergence op: its whole purpose is aligning siblings to persisted state, so a failed local reload still broadcasts and then re-raises with the fleet report attached. Called over MCP on a worker the reload applies to (no ``targets``, or ``targets`` naming that worker), the reload answers on the session that called it and then retires that session with the generation it ran on: a later call on the same session fails (streamable HTTP answers it 404, and an SSE session's stream closes), so the client starts a new session to go on. When ``targets`` leave that worker out, nothing reloads there and the session keeps working. An applied worker's payload is ``{status: "ok", env_keys, awaiting_respawn}``; a worker whose reload was refused at its epoch build (the build discarded before its swap) replies ``failed`` with ``{status: "discarded", awaiting_respawn}``, serving its previous epoch with that drift standing; any other failed reload, a failed discard among them, carries no payload. ``awaiting_respawn`` names the recycle-class keys whose value now differs from the one that worker bound (at boot, or when the plugin that declares them was loaded) — the soft restart carries every hot key in place, and those keys take effect only on a restart. Once the reports are in, every worker the reload addressed that names such a key is restarted one at a time through the deployment's supervisor, except a worker whose reload was refused at its epoch build: the stored config did not build on it and a restart may fail the same way, so it keeps serving its current config and is named in ``awaiting_respawn``. Any worker other than this one whose state is unknown (its reload failed otherwise or did not finish, it has no row, its reply carries no ``awaiting_respawn`` list, or the bus was unreachable) is asked once it is ready and restarted unless its reply confirms it clean or states a refused build (its restart then withheld); the workers that confirmed none are left running. This worker is never asked: when its own state is unknown, it needs its own restart. ``recycle`` reports that roll (``null`` when the roll had no worker to visit: every addressed worker confirmed no recycle-class key, or the only ones naming one were refused at their epoch build) and ``awaiting_respawn`` the workers still awaiting a respawn after it. When this worker needs its own restart and the roll converged, it exits gracefully once the reply is answered and its supervisor starts it again. A soft restart run under a bound the roll's waits can outlast (a dispatched job's budget, an armed turn budget) runs no roll itself: it hands the roll to the bus member it acts for, which carries it out after the reply and departs itself last, once the roll converged, when it needs its own restart; ``roll_deferred`` is then ``true``, ``roll_deferred_to`` names that member, ``recycle`` is ``null`` and ``awaiting_respawn`` empty, the roll not judged in this reply. Otherwise ``roll_deferred`` is ``false`` and ``roll_deferred_to`` ``null``. operationId: post_api_config_reload requestBody: content: application/json: schema: $ref: '#/components/schemas/ReloadConfigRequest' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/FleetReloadResponse' required: - data type: object description: Success. '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing or invalid api key. '503': content: application/json: schema: $ref: '#/components/schemas/ReloadingError' description: The server is applying a config reload; retry shortly. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer security: - ApiKeyAuth: [] components: schemas: ReloadConfigRequest: description: >- A local reload-config request. An optional ``targets`` list restricts the fan-out of the soft-restart to named workers (all workers when omitted). properties: targets: anyOf: - items: type: string type: array - type: 'null' default: null title: Targets title: ReloadConfigRequest type: object FleetReloadResponse: description: >- A fleet soft restart's per-worker reload report, the recycle roll it ran, and its verdict. An applied worker's ``payload`` is ``{status: "ok", env_keys, awaiting_respawn}``; a worker whose reload was refused at its epoch build (the build discarded before its swap) replies ``failed`` with ``{status: "discarded", awaiting_respawn}``, serving its previous epoch with that drift standing; any other failed reload, a failed discard among them, carries no payload. ``recycle`` is the roll that restarted the workers the reload addressed whose reload built and whose ``awaiting_respawn`` named a recycle-class key, or whose state was unknown: a worker other than the answering one is asked once ready and restarted when its reply neither confirms it clean nor states a refused build; the answering worker is never asked, and when its own state is unknown its restart is its ``self-deferred`` line, present when the roll converged. A worker whose reload was refused at its epoch build is never restarted: the stored config did not build on it and a restart may fail the same way, so the roll leaves it running and lists it. ``recycle`` is ``null`` when the roll had no worker to visit: every addressed worker confirmed no recycle-class key, or the only ones naming one were refused at their epoch build. ``awaiting_respawn`` the workers still awaiting a respawn after the roll (name + keys), those left running after a refused epoch build among them. ``roll_deferred`` is ``true`` when the roll was handed to the worker ``roll_deferred_to`` names, which carries it out after the reply (``recycle`` is ``null`` and ``awaiting_respawn`` empty); ``roll_deferred_to`` is ``null`` otherwise. properties: awaiting_respawn: items: $ref: '#/components/schemas/AwaitingWorker' title: Awaiting Respawn type: array error: anyOf: - type: string - type: 'null' default: null title: Error local_only: default: false title: Local Only type: boolean ok: description: True when the bus was reachable and every worker applied. readOnly: true title: Ok type: boolean op: title: Op type: string reachable: default: true title: Reachable type: boolean recycle: anyOf: - $ref: '#/components/schemas/RecycleRoll' - type: 'null' default: null results: items: $ref: '#/components/schemas/WorkerResult' title: Results type: array roll_deferred: default: false title: Roll Deferred type: boolean roll_deferred_to: anyOf: - type: string - type: 'null' default: null title: Roll Deferred To required: - op - ok title: FleetReloadResponse type: object Error: properties: code: description: >- Stable machine-readable reason a client keys a dedicated error state on, present on refusals that opt in (e.g. a 501 not-configured refusal). Optional: absent when the error carries only a human-readable message. type: string error: type: string required: - error type: object ReloadingError: properties: error: const: reloading — the server is applying a config reload; retry shortly type: string reloading: const: true type: boolean required: - error - reloading type: object AwaitingWorker: description: >- One worker an operation names as still awaiting a respawn. Its recycle-class ``keys`` changed in the stored env since its process bound them (at boot, or when the plugin that declares them was loaded), and nothing in the operation respawns it. properties: keys: items: type: string title: Keys type: array name: title: Name type: string required: - name - keys title: AwaitingWorker type: object RecycleRoll: description: >- The report of a fleet recycle roll a reload ran for the workers that needed a restart. A worker needs a restart when its reload reported a recycle-class key moved off the value it bound. A worker whose reload was refused at its epoch build (the build discarded before its swap) is never restarted, even when it reports such a key: the stored config did not build on it and a restart may fail the same way, so it keeps serving its current config; a failed discard is no refused build, and leaves the worker's state unknown. A worker other than the writer whose state was unknown is asked once it is ready and restarted unless its reply confirms it clean or states a refused build (its line then ``withheld``). The writer is never asked at its own roll: when its own state is unknown, its restart is left to its post-response self-exit, armed only when the roll converged and the reply can carry one (then its ``self-deferred`` line). ``recycle`` the worker lines of the roll (the writer's own ``self-deferred`` line when its post-response self-exit is armed); ``skipped`` the workers whose reload confirmed no such key, at the reload or when asked once ready, left running; ``fresh`` the new ready lives seen since the change began; ``recycle_stopped`` is ``null`` when the roll ran to its end, otherwise where it stopped and why. Names only — never env values. properties: fresh: items: $ref: '#/components/schemas/FreshLife' title: Fresh type: array recycle: items: $ref: '#/components/schemas/RecycleEntry' title: Recycle type: array recycle_stopped: anyOf: - $ref: '#/components/schemas/RecycleStop' - type: 'null' default: null skipped: items: type: string title: Skipped type: array required: - recycle - skipped - fresh title: RecycleRoll type: object WorkerResult: description: >- One worker's outcome within a :class:`FleetResult`. ``payload`` carries query-op data (a read rides the same fan-out shape as a mutation); ``error`` carries a failed apply's message; ``detail`` carries the publisher's report text for a computed ``missing``/``departed``/``timed_out``. properties: detail: anyOf: - type: string - type: 'null' default: null title: Detail error: anyOf: - type: string - type: 'null' default: null title: Error name: title: Name type: string outcome: $ref: '#/components/schemas/OpOutcome' payload: anyOf: - {} - type: 'null' default: null title: Payload required: - name - outcome title: WorkerResult type: object FreshLife: description: One newly-ready worker life observed since the pre-apply snapshot. properties: generation: title: Generation type: integer kind: title: Kind type: string name: title: Name type: string required: - name - kind - generation title: FreshLife type: object RecycleEntry: description: >- One worker line of a fleet recycle roll. ``status`` is ``recycled`` (confirmed on reality), ``timed-out`` or ``failed`` (the target the roll stopped at), ``self-deferred`` (a restart the roll cannot confirm: the writer's own post-response self-exit, or a target whose exit is held by its own in-flight change and runs once that change's reply is answered), or ``withheld`` (a worker asked once ready whose reload was refused at its epoch build — the build discarded before its swap — yet reports a recycle-class key: the stored config did not build on it and a restart may fail the same way, so the roll leaves it running on its current config). ``keys`` are the recycle-class keys that worker's reload reported as moved off the value it bound them under — the reason it was restarted, or for a ``withheld`` worker the keys it still awaits; empty for a worker restarted because its state stayed unknown. A worker other than the writer whose state was unknown is asked once it is ready and restarted unless its reply confirms it clean or states a refused build (its line then ``withheld``). The writer is never asked at its own roll: when its own state is unknown, its restart is left to its post-response self-exit, armed only when the roll converged and the reply can carry one (then its ``self-deferred`` line). ``detail`` names what left that worker's state unknown (its reload outcome, no report row, a malformed reply, an unreachable bus) with what it answered when asked once ready, and why a ``timed-out`` / ``failed`` target did not converge, joined with ``"; "``; ``null`` when none applies. properties: detail: anyOf: - type: string - type: 'null' default: null title: Detail generation_before: title: Generation Before type: integer keys: items: type: string title: Keys type: array kind: title: Kind type: string name: title: Name type: string status: title: Status type: string required: - name - kind - status - generation_before - keys title: RecycleEntry type: object RecycleStop: description: >- Where a profile apply's recycle roll stopped and why. ``name`` is the target the roll stopped at (its line in ``recycle`` carries the target's own outcome), or ``null`` when the bus could not be read before a target was reached. properties: detail: title: Detail type: string kind: title: Kind type: string name: anyOf: - type: string - type: 'null' title: Name required: - kind - name - detail title: RecycleStop type: object OpOutcome: description: >- Per-worker outcome of a fleet op. ``applied`` / ``failed`` are terminal WIRE replies from a subscriber. ``missing`` / ``departed`` / ``timed_out`` are publisher-COMPUTED from the bus's record of each life (a silent worker never sends them): ``departed`` once a read of the worker's slot shows the expected life ended (its claim gone, or a newer life in the slot), the other two at the report cut. ``resyncing`` / ``recycling`` / ``stale`` are the gap outcomes for a row that fails the ready+ fresh gate: it is not an expected worker, so instead of being dropped it is landed as its own actual condition — ``resyncing`` (the worker wrote that state and converges on its resync), ``recycling`` (departing, converging by old-life-gone + fresh capacity), or ``stale`` (a quiet row past the freshness bound — reconnecting or dead, carrying no convergence promise). A decayed row is ``stale`` regardless of its written state. An expected worker that began leaving after publish and sent no terminal reply is ``recycling`` too, computed at the report cut from its row and its still-held slot claim. enum: - applied - failed - missing - departed - timed_out - resyncing - recycling - stale title: OpOutcome type: string securitySchemes: ApiKeyAuth: in: header name: x-api-key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.