Snapshot task worktrees to hidden refs as agents work

api/openapi.yaml

@@ -288,6 +288,24 @@ paths:
         "404": { $ref: "#/components/responses/Error" }
         "409": { $ref: "#/components/responses/Error" }
 
+  /api/tasks/{taskId}/snapshots:
+    parameters:
+      - { name: taskId, in: path, required: true, schema: { type: string } }
+    get:
+      operationId: listSnapshots
+      description: >
+        The task's snapshots, oldest first. Each is a commit of the worktree as if everything were staged, kept at
+        refs/byre/tasks/{taskId}/snap/{n} until the task is merged or discarded; the rows remain after that.
+      responses:
+        "200":
+          description: The snapshots.
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/Snapshot" }
+        "404": { $ref: "#/components/responses/Error" }
+
   /api/tasks/{taskId}/sessions:
     parameters:
       - { name: taskId, in: path, required: true, schema: { type: string } }
@@ -645,6 +663,23 @@ components:
         path: { type: string }
         patch: { type: string }
 
+    Snapshot:
+      type: object
+      required: [id, task_id, agent_session_id, n, commit_sha, tree_sha, event_seq, trigger, created_at]
+      properties:
+        id: { type: string }
+        task_id: { type: string }
+        agent_session_id: { type: string }
+        n: { type: integer, description: "Position in the task's snapshots, from 1; the ref is refs/byre/tasks/{task_id}/snap/{n}." }
+        commit_sha: { type: string, description: A commit of tree_sha whose parent is the worktree's HEAD when it was taken. }
+        tree_sha: { type: string }
+        event_seq: { type: integer, format: int64, description: "The task's latest event when the snapshot was started: the tree holds at least the work up to it." }
+        trigger:
+          type: string
+          enum: [tool_call, turn_end, ask_human, timer]
+          x-enum-varnames: [SnapshotTriggerToolCall, SnapshotTriggerTurnEnd, SnapshotTriggerAskHuman, SnapshotTriggerTimer]
+        created_at: { type: string, format: date-time }
+
     AgentSession:
       type: object
       required: [id, task_id, vendor, model, vendor_session_id, state, role, created_by, created_at]