> ## Documentation Index
> Fetch the complete documentation index at: https://aven-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Work Sessions: Tracked and Verified Delivery Units

> A work session captures active coding time and Git change metadata for Aven to calculate an exact, contract-verified payment amount for that period.

A **work session** is a discrete, measurable unit of delivery on an Aven stream. Each session has a precise start and stop time, a record of active vs idle seconds, and a snapshot of Git activity that occurred during that period. The session data is compiled into a structured work report that the Aven verifier uses to compute the exact payment amount — and that the employer reviews before approving release.

Every work session is linked to a specific stream by its `stream_id`. A worker can run multiple sessions against the same stream over the life of the project.

***

## Session Lifecycle

```mermaid theme={null}
stateDiagram-v2
  [*] --> Recording: aven-stellar start
  Recording --> Stopped: aven-stellar stop
  Stopped --> Submitted: report submitted
  Submitted --> UnderReview: worker requests review
  UnderReview --> Approved: employer approves
  UnderReview --> Disputed: employer disputes
  Approved --> Released: payment released
```

**1. Recording**

The worker runs `aven-stellar start` inside the project Git repository. The CLI launches a lightweight background activity watcher that tracks active seconds and monitors the repository for changes.

**2. Stopped**

The worker runs `aven-stellar stop`. The CLI calculates Git change statistics since the session started, compiles the full report, previews it, and asks for submission confirmation. The original stop time is preserved — if submission fails and the worker re-runs `stop`, no extra time is counted.

**3. Submitted**

The report is sent to the Aven dashboard and appears under **Work Sessions** on the stream page. The verifier processes it and reserves the calculated payment amount in the smart contract escrow.

**4. Under Review**

The worker clicks **Request Review**, which notifies the employer that the session is ready for approval. The session moves into the review queue.

**5. Approved or Disputed**

The employer reviews the work record and either approves or disputes it. Approved sessions proceed to payment release. Disputed sessions freeze the reserved amount pending resolution.

**6. Released**

The worker calls `withdraw_approved` (via the dashboard **Withdraw** button), which transfers the reserved tokens from the contract directly to the recipient's Stellar wallet address.

***

## What the CLI Records

The `aven-stellar` CLI records the following information during a session:

| Data point | Description |
| - | - |
| `startedAt` / `endedAt` | ISO timestamps marking when the session began and ended |
| `activeSeconds` | Seconds where activity was detected (keyboard, file changes) |
| `idleSeconds` | Seconds within the session window with no detected activity |
| `branchAtStart` / `branchAtEnd` | Git branch name at session start and stop |
| `commits` | Commits made during the session: hash, message, timestamp, additions, deletions |
| `changedFiles` | Relative paths of changed files with per-file additions, deletions, and change type |
| `additions` / `deletions` | Aggregate line counts across all changed files |
| `dirtyAtStart` / `dirtyAtEnd` | Whether the working tree had unstaged changes at start and end |

The CLI also categorises each changed file (`source`, `test`, `documentation`, `configuration`, `asset`, `generated`, `dependency`, `unknown`) and marks whether it was included in the verification payload. Files excluded by `.gitignore` or `.avenignore` are noted with an `excludedReason`.

> [!NOTE]
>
> The CLI never uploads complete source files, executes project code, records keystrokes or screenshots, or reads Stellar secret keys. Only metadata about what changed is included in the report.

***

## What a Work Report Contains

The submitted work report (`WorkSessionReport`) is a structured JSON document containing all of the above session data, plus:

* The worker's **delivery statement** (`workerStatement.message`) — a summary the worker provides with `--message`
* **Local verification metadata** — verifier version, work type classification, and a human-readable summary
* **Payment request** — the calculated `requestedAmount`, the asset (XLM or USDC), the `ratePerSecond`, and `billableSeconds` used in the calculation
* **Privacy profile** — counts of excluded files, secret warnings, and confirmation that no full source files were included
* **Delivery data** (final sessions only) — selected branches, their head commits, and remote verification status

The report is reviewable by the employer on the stream page and forms the evidence record that backs the on-chain attestation when payment is released.

***

## Verified vs Unverified Sessions

A submitted session is **unverified** until the Aven server-side verifier processes it. The verifier:

1. Reads the session report from the Aven dashboard
2. Independently calculates the payment as `active_seconds × rate_per_second`, capped by unreserved escrow
3. Calls `verify_work` on the stream contract, passing the calculated amount and an `evidence_hash` (SHA-256 of the report)
4. The contract re-validates the amount — if it does not match the contract's own calculation, the transaction is rejected

Once `verify_work` succeeds, the session is **verified**: the payment amount is reserved in escrow and the `evidence_hash` is stored on-chain. The worker can then request employer review.

***

## Normal Sessions vs Final Sessions

**Normal sessions** (`aven-stellar stop`) record a measured work period against a stream that will continue to accept future sessions.

**Final sessions** (`aven-stellar stop --ended`) mark the end of the project. The worker is prompted to specify the delivery branches. The CLI verifies those branch head commits against the connected GitHub repository and includes delivery metadata in the report.

> [!NOTE]
>
> For a final session, the server uses `ceil(remaining escrow ÷ rate)` as the contract's duration argument so the contract caps the verified amount to the exact remaining escrow. The real npm-tracked active seconds are still preserved in the report and displayed in the dashboard. Any pending or reserved payments must be resolved before a final session can be submitted.

***

## Session ID

Each session is assigned a **UUID** (`sessionId`) at the moment `aven-stellar start` runs. This UUID is the `request_id` used in the contract's `WithdrawalRecord` and propagated through to the on-chain `AttestationRecord`. It provides an unambiguous link between the off-chain report and the on-chain payment record.

***

## The `.aven/` Directory

The CLI stores recoverable local session state in a `.aven/` directory at the root of the project repository. This includes:

* The active session file (`LocalSession`) tracking start time, activity counters, and watcher PID
* The Aven configuration file (`AvenConfig`) with dashboard URL, stream ID, worker address, cached rate, and authorization token

> [!NOTE]
>
> Do not commit `.aven/` to version control. It contains a scoped CLI authorization token and local session state. Add it to your `.gitignore`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.