Harness Work Queue

The harness work queue is the bridge between Sigroom project tasks and executable GeneSYS loop workitems. It gives operators and harnesses one queue to inspect, select into runnable work, verify with command profiles, and open bounded sandbox sessions.

referenceHarness operators and GeneSYS integratorsVerified 2026-07-09

Task Model

Concept	Meaning
Project task	A planning or project task with task_ref project:<project_task_id>; it is visible in the queue but not runnable until selected.
Loop workitem	A runnable HACP/GeneSYS workitem with task_ref loop:<loop_workitem_id>; it carries objective, room, harness instance, outcome contract, attempts, command profiles, run IDs, test IDs, artifacts, and blocked state.
Task link	When a project task is selected, Sigroom creates a loop workitem, moves the project task to in_progress, and stores a link between both records.
Sandbox session	A bounded hsbx-prefixed session record for human or agent testing/debug/preview work, with mode, purpose, TTL, command profiles, test IDs, log artifact IDs, status, and optional preview URL.
Audit trail	Selection, update, completion, test, test-all, sandbox open, and sandbox stop all write audit records.

API Flow

Step	Route
List the queue	GET /workspaces/:workspaceId/harness-tasks?project_id=&room_id=&harness_instance_id=&kind=&status=
Select project or loop work	POST /workspaces/:workspaceId/harness-tasks/select
Edit task state	PATCH /workspaces/:workspaceId/harness-tasks/:kind/:id
Complete task	POST /workspaces/:workspaceId/harness-tasks/:kind/:id/complete
Request tests for one runnable task	POST /workspaces/:workspaceId/harness-tasks/:kind/:id/test
Request tests for matching runnable tasks	POST /workspaces/:workspaceId/harness-tasks/test-all
Open sandbox session	POST /workspaces/:workspaceId/harness-tasks/:kind/:id/sandbox-sessions
Read sandbox session	GET /workspaces/:workspaceId/harness-sandbox-sessions/:sessionId
Stop sandbox session	POST /workspaces/:workspaceId/harness-sandbox-sessions/:sessionId/stop

Launcher Commands

bash

hacp work list \
  --workspace-id w_acme \
  --project-id prj_gateway \
  --room-id r_room01 \
  --harness-instance-id h_genesys \
  --kind all \
  --status queued,running \
  --json

hacp work select project:ptask_plan \
  --workspace-id w_acme \
  --room-id r_room01 \
  --harness-instance-id h_genesys \
  --command-profile-id pcmd_web \
  --objective "Build the task board" \
  --json

hacp work test loop:lwi_impl --workspace-id w_acme --environment sandbox --json
hacp work sandbox-open loop:lwi_impl --workspace-id w_acme --mode agent --purpose test_feature --ttl-minutes 45 --json
hacp work sandbox-status hsbx_session01 --workspace-id w_acme --json
hacp work complete loop:lwi_impl --workspace-id w_acme --summary "Verified in sandbox" --json

Request Preview And API Mode

Without --api-url, hacp work emits a JSON request_preview that shows method, path, query, and body without calling Sigroom. With --api-url and an API cookie, the launcher sends GET, PATCH, or POST requests to the Sigroom API and wraps the response in a status ok envelope.

Permission Rules

workspace.read can list queue items and read sandbox session status.
review.decide can select existing loop workitems, update loop workitems, complete loop workitems, request tests, request test-all, open loop sandboxes, and stop sandbox sessions when the user is an active room participant.
Selecting a project task into runnable loop work requires review.decide plus workspace.admin, a room ID, harness instance ID, outcome contract, and command profile IDs.
Project-task edits and project-task completion require workspace.admin.
Test requests are denied if requested command profile IDs are not already allowed by the loop workitem.

Source Material

apps/api/src/modules/harness-tasks/routes.ts
apps/api/src/modules/harness-tasks/store.ts
packages/contracts/src/index.ts
rust/crates/hacp-launcher/src/lib.rs
rust/crates/hacp-launcher/tests/cli_contract.rs