Turn Lifecycle

Every Pi turn follows the same lifecycle on AgentCore, desktop, and mobile:

compose -> hydrate -> run -> reconcile

That consistency is what lets the same workspace contract work in a Linux container, on a Mac desktop executor, and inside the mobile harness.

1. Compose

Composition resolves the current Thread into source folders and structured status:

Source	What it contributes
Agent source	Worker identity, instructions, skills, tool guidance
Space source	Active project/customer/team context, docs, Goal templates
User source	Requester personalization and user memory notes
Thread source	Goal narrative files and per-thread runtime metadata
Database	Read-only status mounts, access grants, task/Goal state

The renderer writes a hydrate manifest under the Thread runtime prefix. The manifest records source prefixes, source keys, ownership, ETags, sizes, and read-only status mounts.

2. Hydrate

The runtime downloads the manifest-backed workspace into /workspace.

/workspace
├── AGENTS.md
├── USER.md
├── memory/
├── skills/
├── workspaces/
└── Space/
    ├── CONTEXT.md
    ├── GOAL.md
    ├── PROGRESS.md
    ├── DECISIONS.md
    ├── ARTIFACTS.md
    ├── HANDOFFS.md
    ├── artifacts/
    ├── docs/
    ├── goals/
    └── plans/

The Agent source becomes the root of /workspace. The User source is merged into the root. The active Space is mounted as singular Space/; the runtime should not have top-level Agent/, Spaces/, or User/ folders.

Space/GOAL.md and Space/PROGRESS.md are mounted read-only because they describe database state. Narrative files such as Space/DECISIONS.md, Space/ARTIFACTS.md, and Space/HANDOFFS.md are writable Thread Goal files.

3. Run

The Pi runtime executes the model turn with /workspace as the working directory. The agent can:

• read composed workspace context
• write working and narrative files
• run allowed coding tools
• call platform tools such as set_task_status
• call approved MCP and built-in tools

The platform still enforces tool allowlists, runtime policy, and access checks. The local folder is the agent’s working surface, not the permission authority.

4. Reconcile

After the turn, the runtime sends changed files to the finalize path. The API reconcile layer decides whether each file can be written back:

Check	Purpose
Path provenance	Routes each changed file to Agent, Space, User, or Thread source
Lane enforcement	Rejects writes outside the file’s allowed owner lane
Access check	Ensures the acting user still has access to the Space/Thread
Read-only status check	Rejects writes to GOAL.md and PROGRESS.md
Secret scan	Blocks or quarantines inline secret material
Conditional S3 write	Uses object freshness to catch stale writes
Structured report	Records per-file success, rejection, or conflict

Reconcile is file-side only. Structured state changes use transactional tools and resolvers.

Caution

Do not ask an agent to change task status by editing Space/PROGRESS.md. Ask it to use the task-status tool. The file will re-render from the database.

Current limitations

Workspace hydration is cache-aware and manifest-backed. A runtime should check for workspace changes, hydrate the files it needs, and reuse fresh local material; it should not fetch the entire tenant bucket before every turn.

Natural-language task completion depends on the agent selecting the structured task-status path. The user may say “DocuSign is complete”; the model/tool layer should map that to the task action. The fallback is not an exact file-name match, and it is not a hand edit to Space/PROGRESS.md.

Failure behavior

Reconcile is per-file best effort. One file can fail because of a stale ETag or secret scan while another file succeeds. The turn records a structured report so operators can see what wrote, what was rejected, and what needs retry.

If access is revoked before reconcile, the API rejects the write. Desktop and mobile caches also carry access revalidation metadata and wipe revoked Space subtrees when notified.