@fleetless/contracts 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -3,7 +3,31 @@
 All notable changes to `@fleetless/contracts` are recorded here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project uses [semantic versioning](https://semver.org/spec/v2.0.0.html) over
-the wire shapes.
+the wire shapes. A pull request that changes what a consumer sees adds its
+entry under `## [Unreleased]`; the release renames that heading to the
+version.
+
+## [Unreleased]
+
+## [4.0.0] — 2026-09-29
+
+### Added
+
+- **Protocol 4: a job heartbeat, and a vanished action server ends its job.**
+  Protocol bumped: bridges from `5.0.0`, and protocol 3 sunsets
+  2026-12-28 (protocol 2 sunset 2026-12-21). The bridge now sends a
+  `job_update` heartbeat every `JOB_HEARTBEAT_INTERVAL_MS` for every running
+  job, and ends a job whose action server vanished `lost` with
+  `action_server_lost` instead of leaving the cloud to guess; `job_lost`
+  gains an optional `error` that can say the same. `JOB_HEARTBEAT_TIMEOUT_MS` bounds a protocol-4 job's
+  silence once it has been heard from at all; `patience_ms` now bounds only
+  the acceptance gap on such a job (unchanged for protocol 3, which sends no
+  heartbeat). `JOB_OFFLINE_GRACE_MS` (five minutes) replaces the informal
+  one-minute disconnect grace a job got before. `errors.ts` documents
+  `action_server_lost` and every job error code already in use that had
+  never been written down: `action_failed`, `goal_rejected`,
+  `goal_send_failed`, `result_failed`, `goal_uncontrollable`,
+  `bridge_disconnected`, `config_changed`.
 
 ## [3.0.0] — 2026-09-22
 

package/CONTRIBUTING.md

@@ -73,8 +73,9 @@ an issue first — so we can say what else has to move with it.
 
 **CI runs on GitHub Actions**, in this repository
 (`.github/workflows/verify.yml`) — the suite, on every push and every pull
-request. `release.yml` publishes on a release tag and calls that same file
-first, so a release is never checked by a different pipeline than a push.
+request. `release.yml` (the **Release** button) calls that same file on the
+commit it publishes, so a release is never checked by a different pipeline
+than a push.
 
 **Your pull request is verified, a fork's included** — the same file, the
 same suite. The first run by a first-time contributor waits for a maintainer
@@ -82,10 +83,11 @@ to press approve on it; that is a button on your run, not a setting anybody
 has to change, so checks sitting idle for a while are the queue and not a
 failure. The run reads code and reaches nothing else: it is granted
 `contents: read`, no secret is exposed to it, and publishing lives in a
-workflow only a tag can trigger.
+workflow only a maintainer's own **Run workflow** press can trigger.
 
-Run `pnpm typecheck && pnpm build && pnpm test && pnpm artifacts && pnpm run
-test:pack` yourself first and you've seen everything `verify` will tell you.
+Run `pnpm typecheck && pnpm build && pnpm test && node --test
+'.github/release/*.test.mjs' && pnpm artifacts && pnpm run test:pack`
+yourself first and you've seen everything `verify` will tell you.
 Mind `pnpm artifacts`: `artifacts/` is generated *and* committed, and CI
 fails if regenerating it changes a file — so commit whatever it writes
 together with the schema you changed. That is the single most common reason
@@ -123,22 +125,31 @@ is refused by a `prepublishOnly` script — the rule has a mechanism rather
 than only a sentence. (`publish` is unaffected: it publishes the tarball
 `verify` packed, and npm runs no prepare lifecycle for a tarball argument.)
 
-1. Update `CHANGELOG.md` and set the new version in `package.json`. **CI
-   checks both** (`scripts/verify-version-tag.mjs`): `package.json` must
-   equal the tag without its `v`, and `CHANGELOG.md` needs a dated heading
-   reading exactly `## [X.Y.Z] — YYYY-MM-DD`. `CHANGELOG.md` ships inside
-   the tarball — skip an entry and you've documented the wrong version to
-   every consumer, and npm won't take a version back.
-
-   The same script refuses a release tag that would move npm's `latest`
-   backwards — a backported `v1.0.1` published while `latest` is `2.0.0`
-   would make `npm i @fleetless/contracts`, the command the README gives
-   outsiders, install a package a major version behind.
-2. Commit, push, and let the `verify` job go green on the branch (the
-   Actions tab).
-3. Tag `vX.Y.Z` (or `vX.Y.Z-beta.N` for a pre-release, which publishes to
-   the `next` dist-tag) and push the tag. The tag run's `verify` job runs
-   again and then `publish`.
+**Release is a button**, not a tag you push. Press **Run workflow** on
+`release` (the Actions tab), on `main`. The version comes from the
+Conventional Commits since the last tag; a release PR turns
+`CHANGELOG.md`'s `## [Unreleased]` into that version, dated, and sets it in
+`package.json` — the same two things `scripts/verify-version-tag.mjs` always
+checked, now written by the release PR instead of by hand. That PR merges
+itself once the required `verify` check passes; the merge commit is tagged,
+`verify.yml` runs again on it and packs the tarball, and `publish` ships
+exactly that tarball.
+
+A person still writes the `## [Unreleased]` entries — in the feature's own
+pull request, as the change goes in — because the release only renames that
+heading to a version; it never writes prose. An empty `## [Unreleased]`
+refuses the release outright, before any branch or commit exists.
+
+A pull request that moves the protocol window writes one of those entries
+too, and `test/changelog.test.ts` is red until it does: some section has to
+name the newest `bridge_from` together with the date the version before it
+sunsets. It need not be the newest section — a release that leaves the
+protocol alone has nothing true to restate about it.
+
+For a pre-release — a branch elsewhere that must pin this change before it
+is final — check `prerelease` among the workflow's inputs: it publishes
+`X.Y.Z-next.N` under the `next` dist-tag, from any branch, with no tag, no
+release PR and no changelog entry.
 
 `publish` carries no npm token. It authenticates by **trusted publishing**:
 GitHub mints a short-lived credential for the job, npm checks it against the
@@ -150,12 +161,18 @@ The job refuses a missing credential by name, rather than failing on an opaque
 error from deep inside `npm publish`. There is no repository secret to add and
 no `.npmrc` anywhere.
 
-**If the publish job goes red after `npm publish` already ran, do not press
-retry.** npm refuses to republish a version — the resulting 403 reads like
-a broken run, not like a release that already happened. Check `npm view
-@fleetless/contracts@<version>` first.
-
-Removing a bad tag is an ordinary git operation here — nothing configures
-tag protection, so `git tag -d vX.Y.Z` locally and `git push origin
-:refs/tags/vX.Y.Z` remotely both just work. What that does *not* undo is a
-publish: the tag is retractable, the npm version is not.
+**If the publish job goes red after `npm publish` already ran, run Release
+again.** It sees that npm already has the version and does not publish
+twice — npm refuses to republish a version, and a second attempt would only
+read like a broken run. The rerun continues from there: it waits for the
+registry to serve it, then finishes. Check `npm view
+@fleetless/contracts@<version>` first if you want to see for yourself before
+pressing anything.
+
+Creating or deleting a `v*` tag is restricted — the organisation ruleset
+`release-tags` allows only admins and the release App, which is how the
+workflow tags a release without a maintainer pushing one by hand. An admin
+can still remove a bad tag; ask one if you are not. What removing it does
+*not* undo is a publish: the tag is retractable, the npm version is not —
+and Release computes the next version from the newest tag, so deleting one
+changes what a later run proposes.

package/artifacts/constants.json

@@ -1,6 +1,6 @@
 {
   "AUDIT_RETENTION_DAYS": 90,
-  "PROTOCOL_VERSION": 3,
+  "PROTOCOL_VERSION": 4,
   "PROTOCOL_VERSIONS": [
     {
       "version": 2,
@@ -10,13 +10,21 @@
     {
       "version": 3,
       "bridge_from": "4.0.0",
+      "deprecated_at": "2026-09-29"
+    },
+    {
+      "version": 4,
+      "bridge_from": "5.0.0",
       "deprecated_at": null
     }
   ],
   "PROTOCOL_SUNSET_DAYS": 90,
-  "LATEST_BRIDGE_VERSION": "4.0.0",
+  "LATEST_BRIDGE_VERSION": "5.0.0",
   "CLOSE_ROBOT_DELETED": 4004,
   "CLOSE_TOKEN_ROTATED": 4005,
+  "JOB_HEARTBEAT_INTERVAL_MS": 1000,
+  "JOB_HEARTBEAT_TIMEOUT_MS": 5000,
+  "JOB_OFFLINE_GRACE_MS": 300000,
   "ASSET_UPLOAD_HEADERS": {
     "kind": "x-fleetless-asset-kind",
     "name": "x-fleetless-asset-name",

package/artifacts/schema/bridge-job-lost.schema.json

@@ -13,6 +13,23 @@
         "format": "uuid",
         "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
       }
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ]
     }
   },
   "required": [

package/artifacts/schema-outgoing/bridge-job-lost.schema.json

@@ -13,6 +13,24 @@
         "format": "uuid",
         "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
       }
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [

package/dist/errors.d.ts

@@ -49,5 +49,5 @@ export type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
+export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
 export type ErrorCode = (typeof ERROR_CODES)[number];

package/dist/errors.js

@@ -71,6 +71,13 @@ export const ERROR_CODES = [
     'no_data',
     // Talking to the robot.
     'robot_offline',
+    /**
+     * The cloud has heard nothing — heartbeat or real progress — from a
+     * running job for longer than it tolerates while the bridge is connected:
+     * `patience_ms` for a protocol-3 bridge, `JOB_HEARTBEAT_TIMEOUT_MS` for a
+     * protocol-4 one once it has heard from the job at all. `job.error.code`
+     * on `lost`.
+     */
     'bridge_timeout',
     // Identity and rights. `forbidden` is deliberately the answer both
     // for "your role does not grant this" and for "there is no such slug":
@@ -140,6 +147,37 @@ export const ERROR_CODES = [
     'parameter_invalid',
     /** The bridge could not account for this job after a restart. */
     'job_lost',
+    /**
+     * The robot's action server vanished mid-goal — the bridge's own liveness
+     * check found `server_is_ready()` false for three seconds straight and
+     * gave up waiting for it to come back. A `job.error.code` on `lost`: the
+     * outcome the goal actually reached is unknown, so `lost` — not `failed` —
+     * is the honest state, and this code says why.
+     */
+    'action_server_lost',
+    /** The action ended with a ROS status other than succeeded; `job.error.code` on `failed`. */
+    'action_failed',
+    /** The action server rejected the goal outright; `job.error.code` on `failed`. */
+    'goal_rejected',
+    /** Sending the goal to the action server itself raised; `job.error.code` on `failed`. */
+    'goal_send_failed',
+    /** Asking the action server for its result raised; `job.error.code` on `failed`. */
+    'result_failed',
+    /** A goal accepted after its own timeout could not then be cancelled; `job.error.code` on `lost`. */
+    'goal_uncontrollable',
+    /**
+     * The robot stayed offline for longer than `JOB_OFFLINE_GRACE_MS` while a
+     * job was running. A late real outcome, if the robot reconnects and the
+     * bridge still has it, corrects this — it is not final the way a genuine
+     * bridge report is. `job.error.code` on `lost`.
+     */
+    'bridge_disconnected',
+    /**
+     * The job's action or service no longer exists in the published
+     * configuration — a republish invalidated it while it was running.
+     * `job.error.code` on `cancelled`.
+     */
+    'config_changed',
     /** Another user holds this publisher and has not been quiet long enough. */
     'publisher_busy',
     /** A well-formed realtime frame this server does not know — the socket stays open. */

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { SLUG_RULE, ROS_NAME_RULE, ROS_TYPE_NAME_RULE, FIELD_PATH_RULE, slug, ro
 export type { ApplyErrorKind, ApplyError } from './common.js';
 export { MCP_PROTOCOL_VERSION, MCP_ENDPOINT_PATH, mcpAppEndpointPath, MCP_APP_PATHS, MCP_TOOL_NAME_MAX, MCP_ASSET_LINK_PATH, MCP_ASSET_LINK_TTL_MS, mcpToolNamePattern, mcpToolKind, mcpExposure, mcpCapabilities, mcpRobotDatasheet, mcpRolePreviewResponse, } from './mcp.js';
 export type { McpAppPaths, McpToolKind, McpExposure, McpCapabilities, McpRobotDatasheet, McpRolePreviewResponse, } from './mcp.js';
-export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDGE_VERSION, protocolStatus, minimumProtocolVersion, sunsetOf, statusFromTable, bridgeHello, cloudHelloOk, cloudHelloError, cloudPing, bridgePong, bridgeLinkMode, datapointFrame, bridgeState, cloudConfig, bridgeConfigApplied, cloudIntrospectRequest, bridgeIntrospect, cloudTypeRequest, bridgeTypeDefinitions, cloudInvoke, cloudCancel, cloudPublish, bridgeJobUpdate, bridgeJobLost, snapshotHeader, cloudCameraStart, cloudCameraStop, bridgeCameraState, SNAPSHOT_MAX_BYTES, CLOSE_ROBOT_DELETED, CLOSE_TOKEN_ROTATED, bridgeAssetsAvailable, cloudAssetRequest, bridgeAssetProgress, activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, } from './protocol.js';
+export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDGE_VERSION, protocolStatus, minimumProtocolVersion, sunsetOf, statusFromTable, bridgeHello, cloudHelloOk, cloudHelloError, cloudPing, bridgePong, bridgeLinkMode, datapointFrame, bridgeState, cloudConfig, bridgeConfigApplied, cloudIntrospectRequest, bridgeIntrospect, cloudTypeRequest, bridgeTypeDefinitions, cloudInvoke, cloudCancel, cloudPublish, bridgeJobUpdate, bridgeJobLost, snapshotHeader, cloudCameraStart, cloudCameraStop, bridgeCameraState, SNAPSHOT_MAX_BYTES, CLOSE_ROBOT_DELETED, CLOSE_TOKEN_ROTATED, bridgeAssetsAvailable, cloudAssetRequest, bridgeAssetProgress, activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, JOB_HEARTBEAT_INTERVAL_MS, JOB_HEARTBEAT_TIMEOUT_MS, JOB_OFFLINE_GRACE_MS, } from './protocol.js';
 export type { ProtocolVersionEntry, ProtocolStatus, BridgeHello, CloudHelloOk, CloudHelloError, CloudPing, BridgePong, BridgeLinkMode, DatapointFrame, BridgeState, CloudConfig, BridgeConfigApplied, CloudIntrospectRequest, BridgeIntrospect, CloudTypeRequest, BridgeTypeDefinitions, CloudInvoke, CloudCancel, CloudPublish, BridgeJobUpdate, BridgeJobLost, SnapshotHeader, CloudCameraStart, CloudCameraStop, BridgeCameraState, ActiveJob, BridgeAssetsAvailable, CloudAssetRequest, BridgeAssetProgress, } from './protocol.js';
 export { jobState, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
 export type { JobState, Job, JobEvent, BusyDetails, PublisherBusyDetails, JobQueueFullDetails, } from './jobs.js';

package/dist/index.js

@@ -5,7 +5,7 @@ export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDG
 // Assets.
 bridgeAssetsAvailable, cloudAssetRequest, bridgeAssetProgress, 
 // Addressing.
-activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, } from './protocol.js';
+activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, JOB_HEARTBEAT_INTERVAL_MS, JOB_HEARTBEAT_TIMEOUT_MS, JOB_OFFLINE_GRACE_MS, } from './protocol.js';
 export { jobState, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
 export { JOB_RUN_PAGE_MAX, JOB_RUN_RETENTION_DAYS, jobActor, jobRunKind, jobRun, jobRunQuery, jobRunListResponse, jobRunSummaryQuery, jobRunSummary, } from './jobs.js';
 export { FLEETLESS_FORMAT_VERSION, RESERVED_SLUGS, parameterType, parameterSpec, parameterMap, serviceDescription, parameterDescription, messageTemplate, messageRef, messageBody, messageMap, PLACEHOLDER_RE, placeholderNames, actionConfig, serviceConfig, publisherConfig, cameraConfig, alertCondition, datapointAlert, rateThrottleHz, datapointNumeric, datapointRetention, datapointChart, datapointConfig, lowBandwidthSection, LOW_BANDWIDTH_DEFAULTS, robotConfigDoc, validationIssue, configState, snapshotIntervalSeconds, 

package/dist/protocol.d.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Bridge <-> cloud protocol, version 3.
+ * Bridge <-> cloud protocol, version 4.
  *
  * The version is exchanged in the hello handshake. Since 2026-09 the cloud
  * serves a **window** of versions, not one: every entry of
@@ -11,6 +11,19 @@ import { z } from 'zod';
  * which names the window and reaches the robot's detail view as
  * `last_hello_error`.
  *
+ * **4 (2026-09-29):** the bridge sends a `job_update` heartbeat at
+ * `JOB_HEARTBEAT_INTERVAL_MS` for every running job, whether or not the
+ * action said anything new, and ends a job whose action server vanished
+ * `lost` with `action_server_lost` (a terminal `job_update`; `job_lost`
+ * gains an optional `error` for the same purpose). The cloud bounds
+ * a protocol-4 job's silence by the heartbeat (`JOB_HEARTBEAT_TIMEOUT_MS`)
+ * once it has heard from the job at all; `patience_ms` still bounds
+ * acceptance, the same as before. Offline tolerance is
+ * `JOB_OFFLINE_GRACE_MS` (five minutes), up from the informal one minute a
+ * protocol-3 bridge got. A protocol-3 bridge sends no heartbeat and keeps
+ * today's behaviour exactly: `patience_ms` alone bounds the whole running
+ * job, silence included.
+ *
  * **3 (2026-09-22):** the ping carries `latency_ms` and `lag_ms`, the bridge
  * sends `link_mode`, `bridge_state` gains `low_bandwidth`, and the
  * `bridge_pressure` datapoint is gone. A protocol-2 bridge is served until
@@ -23,7 +36,7 @@ import { z } from 'zod';
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`.
  */
-export declare const PROTOCOL_VERSION = 3;
+export declare const PROTOCOL_VERSION = 4;
 /** Days between a version's deprecation and its sunset. */
 export declare const PROTOCOL_SUNSET_DAYS = 90;
 export interface ProtocolVersionEntry {
@@ -36,13 +49,15 @@ export interface ProtocolVersionEntry {
 /**
  * Every protocol version the cloud has served, oldest first. A test keeps
  * exactly one entry current and equal to `PROTOCOL_VERSION`; `test/changelog.test.ts`
- * requires the CHANGELOG's current section to name the newest `bridge_from`
- * and the previous entry's `sunsetOf(...)` date, and `scripts/verify-version-tag.mjs`
- * requires a dated heading for the tag being released.
+ * requires some CHANGELOG section — `[Unreleased]` or a dated one — to name
+ * the newest `bridge_from` together with the previous entry's `sunsetOf(...)`
+ * date, so the pull request that moves this window is the one that fails
+ * without saying so; and `scripts/verify-version-tag.mjs` requires a dated
+ * heading for the tag being released.
  */
 export declare const PROTOCOL_VERSIONS: readonly ProtocolVersionEntry[];
 /** The newest bridge package. The cloud mails organisations still below it. */
-export declare const LATEST_BRIDGE_VERSION = "4.0.0";
+export declare const LATEST_BRIDGE_VERSION = "5.0.0";
 export interface ProtocolStatus {
     status: 'current' | 'deprecated' | 'unsupported';
     /** ISO date, or null for a current or unknown version. */
@@ -128,6 +143,40 @@ export declare const MAX_PATIENCE_MS = 120000;
  * this end bounds what the caller can do to the robot.
  */
 export declare const MIN_PATIENCE_MS = 1000;
+/**
+ * How often a protocol-4 bridge sends a `job_update` heartbeat for every
+ * running job — the last known state, whether or not the action itself said
+ * anything new. One second: often enough that `JOB_HEARTBEAT_TIMEOUT_MS`
+ * can be a small multiple of it and still absorb a missed beat or two, rare
+ * enough that it costs nothing next to the datapoint traffic a busy robot
+ * already sends.
+ */
+export declare const JOB_HEARTBEAT_INTERVAL_MS = 1000;
+/**
+ * How long a protocol-4 job may go without a `job_update` — heartbeat or
+ * real progress, either counts — before the cloud settles it `lost` with
+ * `bridge_timeout`, once the bridge is connected. Five heartbeats: enough
+ * slack for an ordinary scheduling jitter, small next to `patience_ms`
+ * because it no longer has to cover the acceptance gap too. `patience_ms`
+ * bounds only the time from `invoke` to the *first* update on a protocol-4
+ * job; every rearm after that uses this constant instead. A protocol-3
+ * bridge sends no heartbeat, so this constant does not apply to it —
+ * `patience_ms` keeps bounding the whole running job there, exactly as
+ * before.
+ */
+export declare const JOB_HEARTBEAT_TIMEOUT_MS = 5000;
+/**
+ * How long a running job survives its robot going offline before the cloud
+ * gives up and settles it `lost` with `bridge_disconnected`. Five minutes:
+ * long enough that an ordinary Wi-Fi dead zone — the case this constant
+ * exists for — never costs a job, since a robot with no safety layer of its
+ * own (§ Fleetless is not a safety layer) keeps driving through one and the
+ * result the cloud is waiting for is often still coming. A robot connected
+ * the whole time never reaches this bound at all: while online, silence is
+ * `JOB_HEARTBEAT_TIMEOUT_MS`'s question (protocol 4) or `patience_ms`'s
+ * (protocol 3), never this one's.
+ */
+export declare const JOB_OFFLINE_GRACE_MS = 300000;
 /** Re-exported so consumers keep importing wire names from one place. */
 export { slug } from './common.js';
 /**
@@ -598,10 +647,23 @@ export type BridgeJobUpdate = z.infer<typeof bridgeJobUpdate>;
  * left to enumerate, so it is `hello.active_job_ids` that closes that gap.
  * Both paths end in the same place — the cloud publishes `lost` rather than
  * leaving a job reading "running" because nobody contradicted it.
+ *
+ * **`error` (since protocol 4) is optional and, when present, applies to
+ * every job named in `job_ids`.** A vanished action server is discovered
+ * once, by the bridge's own liveness check on that one goal, so a frame
+ * naming several jobs at once — plausible if several goals shared the same
+ * server — always shares the same cause. Absent means today's behaviour:
+ * the cloud settles the job `lost` with no specific code, the same as a
+ * protocol-3 bridge's frame, which carries no `error` at all and still
+ * parses under this schema unchanged.
  */
 export declare const bridgeJobLost: z.ZodObject<{
     type: z.ZodLiteral<"job_lost">;
     job_ids: z.ZodArray<z.ZodUUID>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type BridgeJobLost = z.infer<typeof bridgeJobLost>;
 /** Cloud asks for a fresh ROS graph; `request_id` correlates the answer. */

package/dist/protocol.js

@@ -7,7 +7,7 @@ import { rosGraph, typeDefinition } from './introspection.js';
 import { jobState } from './jobs.js';
 import { rosTypeName } from './common.js';
 /**
- * Bridge <-> cloud protocol, version 3.
+ * Bridge <-> cloud protocol, version 4.
  *
  * The version is exchanged in the hello handshake. Since 2026-09 the cloud
  * serves a **window** of versions, not one: every entry of
@@ -17,6 +17,19 @@ import { rosTypeName } from './common.js';
  * which names the window and reaches the robot's detail view as
  * `last_hello_error`.
  *
+ * **4 (2026-09-29):** the bridge sends a `job_update` heartbeat at
+ * `JOB_HEARTBEAT_INTERVAL_MS` for every running job, whether or not the
+ * action said anything new, and ends a job whose action server vanished
+ * `lost` with `action_server_lost` (a terminal `job_update`; `job_lost`
+ * gains an optional `error` for the same purpose). The cloud bounds
+ * a protocol-4 job's silence by the heartbeat (`JOB_HEARTBEAT_TIMEOUT_MS`)
+ * once it has heard from the job at all; `patience_ms` still bounds
+ * acceptance, the same as before. Offline tolerance is
+ * `JOB_OFFLINE_GRACE_MS` (five minutes), up from the informal one minute a
+ * protocol-3 bridge got. A protocol-3 bridge sends no heartbeat and keeps
+ * today's behaviour exactly: `patience_ms` alone bounds the whole running
+ * job, silence included.
+ *
  * **3 (2026-09-22):** the ping carries `latency_ms` and `lag_ms`, the bridge
  * sends `link_mode`, `bridge_state` gains `low_bandwidth`, and the
  * `bridge_pressure` datapoint is gone. A protocol-2 bridge is served until
@@ -29,22 +42,25 @@ import { rosTypeName } from './common.js';
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`.
  */
-export const PROTOCOL_VERSION = 3;
+export const PROTOCOL_VERSION = 4;
 /** Days between a version's deprecation and its sunset. */
 export const PROTOCOL_SUNSET_DAYS = 90;
 /**
  * Every protocol version the cloud has served, oldest first. A test keeps
  * exactly one entry current and equal to `PROTOCOL_VERSION`; `test/changelog.test.ts`
- * requires the CHANGELOG's current section to name the newest `bridge_from`
- * and the previous entry's `sunsetOf(...)` date, and `scripts/verify-version-tag.mjs`
- * requires a dated heading for the tag being released.
+ * requires some CHANGELOG section — `[Unreleased]` or a dated one — to name
+ * the newest `bridge_from` together with the previous entry's `sunsetOf(...)`
+ * date, so the pull request that moves this window is the one that fails
+ * without saying so; and `scripts/verify-version-tag.mjs` requires a dated
+ * heading for the tag being released.
  */
 export const PROTOCOL_VERSIONS = [
     { version: 2, bridge_from: '3.0.0', deprecated_at: '2026-09-22' },
-    { version: 3, bridge_from: '4.0.0', deprecated_at: null },
+    { version: 3, bridge_from: '4.0.0', deprecated_at: '2026-09-29' },
+    { version: 4, bridge_from: '5.0.0', deprecated_at: null },
 ];
 /** The newest bridge package. The cloud mails organisations still below it. */
-export const LATEST_BRIDGE_VERSION = '4.0.0';
+export const LATEST_BRIDGE_VERSION = '5.0.0';
 const DAY_MS = 24 * 60 * 60 * 1000;
 function isoDate(date) {
     return date.toISOString().slice(0, 10);
@@ -146,6 +162,40 @@ export const MAX_PATIENCE_MS = 120_000;
  * this end bounds what the caller can do to the robot.
  */
 export const MIN_PATIENCE_MS = 1_000;
+/**
+ * How often a protocol-4 bridge sends a `job_update` heartbeat for every
+ * running job — the last known state, whether or not the action itself said
+ * anything new. One second: often enough that `JOB_HEARTBEAT_TIMEOUT_MS`
+ * can be a small multiple of it and still absorb a missed beat or two, rare
+ * enough that it costs nothing next to the datapoint traffic a busy robot
+ * already sends.
+ */
+export const JOB_HEARTBEAT_INTERVAL_MS = 1_000;
+/**
+ * How long a protocol-4 job may go without a `job_update` — heartbeat or
+ * real progress, either counts — before the cloud settles it `lost` with
+ * `bridge_timeout`, once the bridge is connected. Five heartbeats: enough
+ * slack for an ordinary scheduling jitter, small next to `patience_ms`
+ * because it no longer has to cover the acceptance gap too. `patience_ms`
+ * bounds only the time from `invoke` to the *first* update on a protocol-4
+ * job; every rearm after that uses this constant instead. A protocol-3
+ * bridge sends no heartbeat, so this constant does not apply to it —
+ * `patience_ms` keeps bounding the whole running job there, exactly as
+ * before.
+ */
+export const JOB_HEARTBEAT_TIMEOUT_MS = 5_000;
+/**
+ * How long a running job survives its robot going offline before the cloud
+ * gives up and settles it `lost` with `bridge_disconnected`. Five minutes:
+ * long enough that an ordinary Wi-Fi dead zone — the case this constant
+ * exists for — never costs a job, since a robot with no safety layer of its
+ * own (§ Fleetless is not a safety layer) keeps driving through one and the
+ * result the cloud is waiting for is often still coming. A robot connected
+ * the whole time never reaches this bound at all: while online, silence is
+ * `JOB_HEARTBEAT_TIMEOUT_MS`'s question (protocol 4) or `patience_ms`'s
+ * (protocol 3), never this one's.
+ */
+export const JOB_OFFLINE_GRACE_MS = 300_000;
 /** Re-exported so consumers keep importing wire names from one place. */
 export { slug } from './common.js';
 /**
@@ -440,10 +490,20 @@ export const bridgeJobUpdate = z.object({
  * left to enumerate, so it is `hello.active_job_ids` that closes that gap.
  * Both paths end in the same place — the cloud publishes `lost` rather than
  * leaving a job reading "running" because nobody contradicted it.
+ *
+ * **`error` (since protocol 4) is optional and, when present, applies to
+ * every job named in `job_ids`.** A vanished action server is discovered
+ * once, by the bridge's own liveness check on that one goal, so a frame
+ * naming several jobs at once — plausible if several goals shared the same
+ * server — always shares the same cause. Absent means today's behaviour:
+ * the cloud settles the job `lost` with no specific code, the same as a
+ * protocol-3 bridge's frame, which carries no `error` at all and still
+ * parses under this schema unchanged.
  */
 export const bridgeJobLost = z.object({
     type: z.literal('job_lost'),
     job_ids: z.array(z.uuid()),
+    error: z.object({ code: z.string().min(1), message: z.string().min(1) }).optional(),
 });
 /** Cloud asks for a fresh ROS graph; `request_id` correlates the answer. */
 export const cloudIntrospectRequest = z.object({

package/dist/realtime.d.ts

@@ -256,8 +256,8 @@ export declare const liveSessionEndReason: z.ZodEnum<{
     unknown: "unknown";
     publish_failed: "publish_failed";
     robot_offline: "robot_offline";
-    released_by_peer: "released_by_peer";
     config_changed: "config_changed";
+    released_by_peer: "released_by_peer";
     revoked: "revoked";
     expired: "expired";
     robot_deleted: "robot_deleted";
@@ -287,8 +287,8 @@ export declare const liveSessionEvent: z.ZodObject<{
         unknown: "unknown";
         publish_failed: "publish_failed";
         robot_offline: "robot_offline";
-        released_by_peer: "released_by_peer";
         config_changed: "config_changed";
+        released_by_peer: "released_by_peer";
         revoked: "revoked";
         expired: "expired";
         robot_deleted: "robot_deleted";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",