browser/run/protocol/job.md

Run Job Contract

Jobs execute bounded server management work.

Implemented Routes

• POST /api/v1/run/jobs/claim: claims one queued job for the registered run endpoint.
• POST /api/v1/run/jobs/ack: acknowledges an active leased job before execution.
• POST /api/v1/run/jobs/progress: reports bounded progress for an active leased job.
• POST /api/v1/run/jobs/result: submits a bounded terminal result for an active leased job.
• POST /api/v1/run/jobs/cancel: polls platform cancellation requests for active leased jobs.
• POST /api/v1/run/jobs/reconcile: reconciles platform-known active jobs after run restart or reconnect.

Payloads

• RunJobClaimRequest: session token, run ID, capacity, and supported capabilities.
• RunJobClaimResponse: optional job assignment with identity, capability, server instance, logical target key, scoped input ref, idempotency key, lease token, attempt, and polling hint.
• RunJobAckRequest: job ID, run ID, session token, lease token, attempt, and bounded message.
• RunJobProgressRequest: job ID, run ID, session token, lease token, attempt, percent, sequence, and bounded message.
• RunJobResultRequest: job ID, run ID, session token, lease token, attempt, terminal state, progress, bounded message, error code, and result reference.
• RunJobCancelPollRequest: run ID, session token, and optional job lease identity.
• RunJobReconcileRequest: run ID, session token, and active local job IDs.

Local Journal

Run must keep a local short-term journal for accepted jobs so duplicate delivery, reconnect, and restart can be reconciled.

Lifecycle Executor

The runtime worker executes these bounded lifecycle job capabilities:

• process.install
• process.start
• process.stop

Platform-dispatched config/file jobs are now represented in the run job payload and validated before execution by later worker implementations:

• config.write: writes approved config content addressed by a logical config key plus scoped input://... ref.
• files.read: reads a declared logical file key and returns results through bounded metadata or artifact refs.
• files.write: writes content addressed by a logical file key plus scoped input://... or artifact://... ref.

The executor resolves lifecycle action templates under the scoped server workspace and runs direct command/argument vectors through the process supervisor. It does not run unrestricted shell strings, execute arbitrary plugin code, expose host paths, return raw credentials, open direct sockets, or embed logs/artifacts in job result payloads.

Rules

• Job ack must be sent before execution.
• Terminal result must be replayable while the journal retains the job.
• Large files must be passed as artifact references, not embedded in job payloads.
• Config/file job payloads must use logical target keys and scoped input/artifact refs.
• Job payloads must not include logs, artifact chunks, raw host paths, raw credentials, direct sockets, or large inline result bodies.
• Process stdout/stderr must be redacted and written to the log spool rather than embedded in progress/result bodies.
• Job ack/progress/result/cancel/reconcile calls are lightweight lifecycle metadata and must be able to complete while artifact/file transfer work is active or retrying.
• Terminal results must remain idempotent under log and artifact retry pressure and must reference artifacts by safe artifact://... refs rather than embedding transfer payloads.

Deferred Channels

Durable log ingest, artifact chunk transfer, and optional game client bridge traffic remain separate channels and must not be multiplexed through job result payloads. Artifact transfer carries chunk payloads only through /api/v1/run/artifacts/* routes.