Turn Lifecycle

Every Pi turn follows the same lifecycle inside the AWS-managed AgentCore runtime:

compose -> hydrate -> run -> reconcile

That consistency is what lets desktop, mobile, web, and automation clients share one workspace contract while agent execution remains in AgentCore.

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
├── CONTEXT.md
├── skills/
├── workspaces/
├── Spaces/
│   └── board-pack/
│       ├── SPACE.md
│       ├── CONTEXT.md
│       ├── artifacts/
│       ├── docs/
│       ├── goals/
│       ├── plans/
│       └── workflows/
├── User/
│   ├── USER.md
│   └── memory/
└── Thread/
    ├── THREAD.md
    ├── GOAL.md
    ├── PROGRESS.md
    ├── TASKS.md
    └── notes/

The Agent source becomes the root of /workspace. The User source remains under User/. The active Space is mounted under Spaces/<active-space>/. Other authorized Spaces are not hydrated; the compose step lists them in the generated Workspace Routing section of AGENTS.md (built from authorization state: active Space, other authorized Spaces, acting user, participants, and Agent Profiles — replacing the former Spaces/INDEX.md), and the agent reads them read-only with the fetch_workspace_source tool. The runtime should not have a top-level Agent/, singular Space/, root USER.md, workspace/, source/, or workspace-archives/.

Thread/GOAL.md, Thread/PROGRESS.md, and Thread/TASKS.md are mounted read-only because they describe database state. Narrative files under Thread/notes/ are writable Thread-scoped working 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 Thread/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 Thread/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. Client caches only carry rendered UI state; source-of-truth workspace access is revalidated by the managed API/runtime path.