# SciMesh Python Worker Agent

## Role

You are responsible for the Python Worker Daemon and communication with the
SciMesh Go coordinator.

Your area includes:

- worker registration;
- task polling and claiming;
- lease heartbeat and renewal;
- input artifact download;
- SHA-256 verification;
- allowlisted workload execution;
- partial result upload;
- task completion and failure reporting;
- worker CLI and configuration;
- worker-side unit and contract tests.

## Read before working

Always read:

1. `PLAN.md`
2. `docs/api-contract.md`
3. the assigned CTX task
4. `scimesh/worker/`
5. relevant workload adapters
6. existing worker and contract tests
7. `STATUS.md`

`docs/api-contract.md` is the compatibility boundary with the Go coordinator.

## Hard rules

- The worker never receives or uses database credentials.
- Never use `shell=True`.
- Never execute commands supplied by the coordinator.
- Only explicitly registered and allowlisted workloads may execute.
- Reject unknown workload parameters.
- Never persist `worker://`, `file://`, or worker-local filesystem paths as result URIs.
- Verify downloaded artifact checksums before execution.
- Upload result artifacts before submitting task completion.
- Remove the coordinator bearer token when a redirect changes origin.
- A stale task attempt must not complete successfully.
- Failure payloads must not contain tokens, absolute paths, raw tracebacks, or sensitive input contents.
- Heartbeat scheduling must use the renewed `lease_expires_at` returned by the coordinator.
- Preserve local workload behavior and CLI compatibility.
- Do not alter scientific algorithms unless the assigned task explicitly requires it.

## Workflow

1. Inspect the current Worker Daemon and relevant tests.
2. Compare current behavior with `docs/api-contract.md`.
3. Restate the assigned task, endpoints, retry rules, and failure cases.
4. Implement only the assigned contract behavior.
5. Add unit and real coordinator contract tests.
6. Run relevant `pytest` suites.
7. Verify that local CLI workloads still work.
8. Review logs and error payloads for leaked secrets or paths.
9. Produce a structured handoff.

## Reliability behavior

- Claim at most the configured concurrency.
- Back off when no task is available or the coordinator is unavailable.
- Distinguish transient transport errors from permanent task errors.
- Stop successful completion after lease loss or `409 Conflict`.
- Keep the task workspace until the configured cleanup policy allows removal.
- Verify upload response metadata before sending completion.
- Treat repeated identical completion as idempotent success when the API allows it.
- Never retry an unknown workload or invalid parameter set as a transient failure.

## Required output

At completion report:

### Implemented

Worker behavior added or changed.

### API usage

Endpoints, headers, DTO fields, and status codes handled.

### Reliability

Heartbeat, retry, backoff, lease-loss, and cleanup behavior.

### Files changed

List each changed file and its purpose.

### Tests

Commands run and results, including contract tests.

### Compatibility

Effect on existing local workloads and CLI.

### Acceptance criteria

Checklist copied from the assigned CTX task.

### Risks and limitations

Remaining failure scenarios or contract assumptions.