Add honest accounting and automatic refund mechanism for completed jobs

Implement honest accounting post-job completion, calculating actual costs, adding margin, and enabling automatic refunds for overpayments via a new endpoint.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 418bf6f8-212b-4bb0-a7a5-8231a061da4e
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: c6386de2-d5f4-47cc-a557-73416f09e118
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/418bf6f8-212b-4bb0-a7a5-8231a061da4e/sPDHkg8
Replit-Helium-Checkpoint-Created: true

lib/api-spec/openapi.yaml

@@ -90,6 +90,59 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+  /jobs/{id}/refund:
+    post:
+      operationId: claimRefund
+      tags: [jobs]
+      summary: Claim a refund for overpayment
+      description: |
+        After a job completes, if the actual cost (tokens used + infra + margin) was
+        less than the work invoice amount, the difference is owed back to the user.
+        Submit a BOLT11 invoice for exactly `refundAmountSats` to receive the payment.
+        Idempotent: returns 409 if already paid or if no refund is owed.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClaimRefundRequest"
+      responses:
+        "200":
+          description: Refund sent
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClaimRefundResponse"
+        "400":
+          description: Missing invoice, wrong amount, or invalid BOLT11
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "404":
+          description: Job not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: Job not complete, refund already paid, or no refund owed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "500":
+          description: Server error (e.g. Lightning payment failure)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
   /demo:
     get:
       operationId: runDemo
@@ -196,7 +249,7 @@ components:
           description: BTC/USD spot price used to convert the invoice to sats
     CostLedger:
       type: object
-      description: Actual cost record stored after the job completes
+      description: Honest post-work accounting stored after the job completes
       properties:
         actualInputTokens:
           type: integer
@@ -208,12 +261,30 @@ components:
         actualCostUsd:
           type: number
           description: Raw Anthropic token cost (no infra, no margin)
+        actualChargeUsd:
+          type: number
+          description: What we honestly charged in USD (actual token cost + DO infra + margin)
         estimatedCostUsd:
           type: number
+          description: Original estimate used to create the work invoice
+        actualAmountSats:
+          type: integer
+          description: Honest sats charge (actual cost converted at the locked BTC price)
+        workAmountSats:
+          type: integer
+          description: Amount the user originally paid in sats
+        refundAmountSats:
+          type: integer
+          description: Sats owed back to the user (workAmountSats - actualAmountSats, >= 0)
+        refundState:
+          type: string
+          enum: [not_applicable, pending, paid]
+          description: Lifecycle of the refund for this job
         marginPct:
           type: number
         btcPriceUsd:
           type: number
+          description: BTC/USD price locked at invoice creation time
     JobStatusResponse:
       type: object
       required:
@@ -238,6 +309,30 @@ components:
           $ref: "#/components/schemas/CostLedger"
         errorMessage:
           type: string
+    ClaimRefundRequest:
+      type: object
+      required:
+        - invoice
+      properties:
+        invoice:
+          type: string
+          description: BOLT11 invoice for exactly refundAmountSats
+    ClaimRefundResponse:
+      type: object
+      required:
+        - ok
+        - refundAmountSats
+        - paymentHash
+        - message
+      properties:
+        ok:
+          type: boolean
+        refundAmountSats:
+          type: integer
+        paymentHash:
+          type: string
+        message:
+          type: string
     DemoResponse:
       type: object
       required: