Polymath Zero

Developers

Session model

A session is a single AI-assisted run on a Work item. Sessions log hypothesis, plan, diffs, test results, and output. Every action taken during a session is recorded in the session memory file.

Session lifecycle

Each session has two distinct operator-gated phases:

  1. Context load — Zero loads the Work item, memory files, and repository state.
  2. Hypothesis — Agent writes a plain-text hypothesis about the problem or approach. (Plan mode begins)
  3. Plan — Agent writes a step-by-step plan as a bounded preparation artifact. Shown to operator before any execution.
  4. Approval — Operator reviews and approves the plan. No code executes without this decision. (Plan mode ends)
  5. Execution — Agent executes the approved plan: reads files, makes changes, runs tests. (Work mode)
  6. Output — Session output written: diff summary, test results, observations. (Work mode ends)
  7. Proof decision — Operator reviews output and attaches proof or abandons the session.
Plan mode → Work mode. Every session transitions from bounded planning to bounded execution. The operator approves the plan before Work mode starts — execution never begins automatically.
Sessions are append-only. A session that ends (proof attached or abandoned) cannot be modified. Start a new session to continue work on the same Work item.

Session states

StateMeaning
createdSession created, context loading.
planningAgent is writing hypothesis and plan.
plan_readyPlan written, awaiting operator approval.
approvedPlan approved, execution about to begin.
executingAgent is running tools and making changes.
completeExecution finished, output available.
failedSession ended with an error or unrecoverable state.
abandonedOperator ended the session without proof.

Object shape

{
  "id": "uuid-v4",
  "case_id": "uuid-v4",
  "number": 4,
  "state": "verifying",
  "type": "implementing",
  "hypothesis": "JWT expiry check uses < instead of <=",
  "plan": "1. Reproduce under load test\n2. Locate expiry check in auth/jwt.rs\n3. Change < to <=\n4. Run auth test suite",
  "output": "All 47 auth tests pass. Diff: auth/jwt.rs +3 -1.",
  "diff": {
    "file": "auth/jwt.rs",
    "additions": 3,
    "deletions": 1
  },
  "tests": {
    "run": 47,
    "passed": 47,
    "failed": 0
  },
  "proof_attached": true,
  "created_at": "2026-04-23T14:00:00Z",
  "updated_at": "2026-04-23T14:32:00Z"
}

Fields

FieldDescription
idUUID v4 for the session.
case_idParent Work item identifier.
numberSequential session number within the Work item.
stateCurrent session state. See above.
typeSession type: planning, implementing, investigating, verifying.
hypothesisPlain-text hypothesis written during planning.
planStep-by-step plan text approved by operator.
outputSession output summary written after execution.
diffFiles modified, additions, deletions.
testsTest counts: run, passed, failed.
proof_attachedWhether a proof artifact is linked to this session.

API endpoints

MethodPathDescription
POST/cases/:id/sessionsCreate a new session on a Work item.
GET/cases/:id/sessionsList all sessions for a Work item.
GET/cases/:id/sessions/:sidGet a single session by ID.
POST/cases/:id/sessions/:sid/approveApprove the session plan. Transitions state to approved.
GET/cases/:id/sessions/:sid/streamSSE stream of session execution events.
# Create a session
curl -s -X POST http://localhost:7878/cases/:id/sessions \
  -H "Content-Type: application/json" \
  -d '{"type": "implementing"}'

# Approve a plan
curl -s -X POST http://localhost:7878/cases/:id/sessions/:sid/approve

Memory file

Every session writes a memory file at zero-memory/cases/{case-id}/sessions/{n}.md. The file is plain markdown — human-readable and scriptable without any Zero tooling.

# Session S002 — implementing

case_id: 31255233-0c7f-4164-8feb-0dc1b8af28ef
case_title: auth timeout on /api/login
session_type: implementing
state: complete
started_at: 2026-04-21T14:22:00Z
completed_at: 2026-04-21T14:38:00Z

## Hypothesis
JWT expiry check uses `<` instead of `<=` — off-by-one causing
timeouts at exact expiry boundary.

## Plan
- Patch `auth/jwt.rs:142`: change `<` to `<=`
- Run `cargo test auth`

## Execution output
Patched jwt.rs:142.
cargo test auth: 47/47 passed (2.3s)

## Proof candidates
- cargo-test-auth-47.txt (47 passed)
- diff-jwt-142.patch

The file contains the full audit trail for the session. It persists in your workspace after the session ends and is never deleted by Zero.

latest.md in the sessions directory is a symlink to the most recent session file. Scripts that only need current state can read sessions/latest.md without scanning all session files.

Related: Case model, Proof and evidence, API reference.