docs: refresh jobs and output guidance

README.md

@@ -91,8 +91,18 @@ Deployment profiles and hardening references:
 
 <details>
 
-<summary><strong>Host compatibility, output previews, media safety, and graph guards refreshed</strong></summary>
+<summary><strong>Secure jobs visibility, host compatibility, output previews, and graph guards refreshed</strong></summary>
 
+- `GET /openclaw/jobs` now provides an Admin-only, versioned jobs view with bounded
+  status/workflow filtering, sorting, pagination, and privacy-minimized summaries across
+  pending, in-progress, completed, failed, and cancelled work.
+- Jobs listing distinguishes an authoritative empty snapshot from unsupported or
+  unavailable host contracts and never returns raw prompts, workflows, execution errors,
+  tracebacks, current inputs/outputs, tenant/client/trace identifiers, or reasoning text.
+- Authorized connector operators can use `/jobs` (plus `jobs` or `queue`) for a bounded
+  authoritative summary. The connector validates the response contract, displays only
+  aggregate counts and short job IDs, and uses a coarse queue-count fallback only for
+  explicit host-contract/backend unavailability.
 - Published host compatibility notes now pin the current ComfyUI, standalone frontend, and Desktop reference anchors while keeping Desktop embedded-frontend lag explicit.
 - Output previews keep filename-backed refs first-class, accept optional `asset_hash` / `hash` metadata when present, and leave asset-service-only identifiers as explicit fallback states.
 - LINE and WhatsApp connector media URLs now force dangerous active content such as SVG/HTML/JS/CSS/XML to download with no-sniff response headers while preserving safe image delivery.
@@ -516,6 +526,8 @@ Base path notes:
 Main API families:
 
 - Observability: health, capabilities, logs, traces, event feeds
+- Jobs visibility: Admin-only, bounded and privacy-minimized list/filter/sort/pagination
+  over the in-process ComfyUI queue and history snapshot
 - Admin diagnostics: preflight inventory snapshot/status, doctor-facing readiness views
 - Config + LLM: effective config, provider tests, model lists, assist planner/refiner
 - Connector diagnostics: installation state, resolution, callback/tenant binding evidence, audit views, extraction seam metadata, and static service-env SecretRef propagation policy
@@ -536,6 +548,10 @@ Primary references:
 Key operational notes:
 
 - Observability remains token-gated for remote access and redacts provider reasoning-like content plus marked internal maintenance/helper content by default.
+- `GET /openclaw/jobs` is Admin-only and returns contract version 1 with bounded job
+  summaries and pagination. Treat HTTP 200 with `jobs: []` as an authoritative empty
+  snapshot, HTTP 501 as an unsupported host contract, and HTTP 503 as backend
+  unavailability; neither failure is an empty success.
 - Event/model-download polling and preflight inventory are snapshot/cursor-driven contracts; clients should consume `snapshot_ts`, `scan_state`, `stale`, and cursor metadata instead of assuming full-refresh polling.
 - Model Manager and preflight consumers should use current ComfyUI folder keys for model types where possible, including `text_encoders`, `diffusion_models`, `gligen`, `latent_upscale_models`, `hypernetworks`, `photomaker`, `model_patches`, `geometry_estimation`, and `detection`; compatibility aliases such as `clip`, `unet`, `ckpt`, and plural legacy names are normalized before lookup/import.
 - Output/history-facing consumers should keep using the bounded `/history` + `/view` contract; current previewable output groups include `images`, `video`, `audio`, `3d`, and bounded `text`, while optional hash-backed refs are used only when host metadata is present and refs that only upstream asset services can resolve remain explicit `asset_api_required` compatibility states.
@@ -745,7 +761,9 @@ OpenClaw includes a standalone **Connector** process that allows you to control
 
 The connector currently remains an **optional attached subsystem inside this repo/package boundary**. Current builds expose extraction diagnostics for maintainers, but do **not** treat a standalone connector package or separate-repo distribution as a supported release shape.
 
-- **Status & Queue**: Check job progress remotely.
+- **Status & Queue**: Authorized operators can use `/jobs` for a bounded authoritative
+  jobs summary; public `/status` remains a coarse health/queue view and does not receive
+  the Admin-only jobs payload.
 - **Run Jobs**: Submit templates via chat commands.
 - **Targeted cancellation**: `/stop`, `/cancel`, and `/interrupt` without job IDs send an explicit global interrupt; supplying one or more job IDs requests targeted ComfyUI job cancellation.
 - **Approvals**: Approve/Reject paused workflows from your phone.

docs/connector.md

@@ -289,6 +289,28 @@ OPENCLAW_COMMAND_ALLOW_FROM_RUN=alice_id,ops_bot_id
 
 If a class-level `OPENCLAW_COMMAND_ALLOW_FROM_*` list is set and non-empty, only listed IDs can run that class.
 
+### Authoritative jobs summary
+
+`/jobs` and its `jobs` / `queue` aliases are Admin-class commands. They require both an
+authorized connector admin user and a configured `OPENCLAW_CONNECTOR_ADMIN_TOKEN` before
+the connector calls `GET /openclaw/jobs`.
+
+The connector validates jobs contract version 1 before rendering any reply:
+
+- output contains aggregate snapshot/page counts plus at most five job IDs and statuses;
+- displayed job IDs are capped at 24 characters and the complete reply is capped at 1,000
+  characters;
+- raw job records, prompts, workflows, outputs, errors, tracebacks, tenant identifiers,
+  and the upstream payload are never sent to the chat LLM or copied into error messages;
+- HTTP 401/403 returns a fixed authorization message without fallback;
+- only explicit HTTP 501 `jobs_host_contract_unsupported` or HTTP 503
+  `jobs_backend_unavailable` responses may fall back to a bounded coarse queue count;
+- malformed, unknown-version, oversized, or inconsistent success payloads fail to a fixed
+  content-free message.
+
+Public `/status` remains separate: it can summarize health and the coarse ComfyUI queue,
+but it does not fetch or forward the Admin-only jobs snapshot.
+
 ### 3. Usage
 
 #### Running the Connector

docs/release/recent_updates.md

@@ -7,6 +7,25 @@ Newest entries appear first.
 
 <details>
 
+<summary><strong>Secure jobs visibility and connector summaries completed</strong></summary>
+
+- Replaced the placeholder jobs listing with an Admin-only, versioned in-process read
+  model over current ComfyUI queue/history state, including five lifecycle states and
+  bounded status/workflow filters, sorting, pagination, and source/scan diagnostics.
+- Reduced every listed job to an allowlisted summary and excluded raw prompts, workflows,
+  execution errors, tracebacks, current inputs/outputs, tenant/client/trace identifiers,
+  reasoning, and internal content from successful responses and audit details.
+- Preserved authoritative empty snapshots while distinguishing unsupported host contracts
+  (HTTP 501) from unavailable or malformed snapshots (HTTP 503), so failures cannot look
+  like an empty queue.
+- Added an Admin-class connector `/jobs` summary that validates contract version 1,
+  renders bounded aggregate counts and short IDs, keeps the raw payload out of the chat
+  LLM, and permits only a coarse queue-count fallback for explicit 501/503 conditions.
+
+</details>
+
+<details>
+
 <summary><strong>Host compatibility reference anchors refreshed</strong></summary>
 
 - Refreshed the active compatibility baseline to ComfyUI `1377a2f7` (`v0.27.0-47-g1377a2f7`, pyproject `0.27.0`) and standalone frontend `1.48.1` (`ceb5ae1eba`, `v1.48.1-1-gceb5ae1eba`).

docs/release/threat_model.md

@@ -25,9 +25,13 @@ Operators should use this to understand the risks of deployment.
 * **Who**: Chat users (Telegram/Discord/LINE).
 * **Access**:
   * **User**: `submit_job` (via Allowlisted templates), `query_status`.
-  * **Admin (Chat)**: `approve_request`, `cancel_job`, `trace`.
+  * **Admin (Chat)**: `approve_request`, `cancel_job`, `trace`, and privacy-minimized
+    `list_jobs` summaries.
 * **Mechanism**: Chat platform auth + OpenClaw User Allowlist (or `require_approval` policy).
-* **Risk**: Spam/DoS (mitigated by Budgets + Rate Limits), or Prompt Injection (mitigated by Template Constraints).
+* **Risk**: Spam/DoS (mitigated by Budgets + Rate Limits), Prompt Injection (mitigated by
+  Template Constraints), or job metadata disclosure (mitigated by Admin-only authorization,
+  allowlisted bounded fields, content-free errors, and keeping raw jobs payloads out of the
+  chat LLM).
 
 ---
 

docs/troubleshooting.md

@@ -63,6 +63,28 @@ Explorer / inventory note:
 - A response showing `scan_state=refreshing` or `stale=true` does not necessarily mean the inventory path is broken; it can mean the cached snapshot was returned quickly while a deeper model scan continues in the background.
 - Treat `last_error` as the primary signal that the background scan actually failed.
 
+## Jobs list or connector `/jobs` reports authorization or backend errors
+
+`GET /openclaw/jobs` is an Admin-only bounded read model. For direct API/browser calls,
+send the configured Admin token and use only the documented `status`, `workflow_id`,
+`sort_by`, `sort_order`, `limit`, and `offset` query fields.
+
+Interpret results as follows:
+
+- HTTP 200 with `jobs: []` is an authoritative empty snapshot.
+- HTTP 401/403 means Admin authentication or tenant authorization failed; verify
+  `OPENCLAW_ADMIN_TOKEN`, and for connector commands also verify
+  `OPENCLAW_CONNECTOR_ADMIN_TOKEN` plus the sender's Admin allowlist/class policy.
+- HTTP 501 `jobs_host_contract_unsupported` means the active ComfyUI host does not expose
+  the required queue/history helper contract.
+- HTTP 503 `jobs_backend_unavailable` means the host snapshot was unavailable or malformed;
+  it must not be treated as an empty queue.
+
+The connector `/jobs` command returns fixed, content-free failures. It can show a bounded
+coarse queue-count fallback only for the explicit 501/503 conditions above; authorization,
+unknown-version, malformed, or oversized responses do not fall back and never echo the raw
+upstream payload.
+
 ## External tool execution is disabled or fails with sandbox diagnostics
 
 External tools are disabled by default and require an admin boundary plus an explicit feature flag.