-
-
Validate Before Recover
-
Return / CP-01
-
Recover / Decision Gate
-
Resume / CP-02
-
Still Aligned / Feature C + Collaboration Rule
-
STATEWAKE Re-entry Model
-
Technical Architecture
Inspiration
The hardest part of returning to a long-running project is often not remembering what happened. It is knowing whether the plan you trusted when you left is still safe to continue from.
A memory system can faithfully restore an outdated plan. An activity feed can show what changed. Neither answers the question that matters most at re-entry:
Can I safely continue from where I left off?
That became the idea behind STATEWAKE.
Most agents remember the past. STATEWAKE checks whether the past is still safe to continue from.
Its core principle is simple:
Validate before Recover.
What it does
STATEWAKE is an interrupted-work recovery agent for long-running technical projects.
It maintains a committed Trusted Project State containing the user's confirmed direction, priority, next action, checkpoint, state version, and evidence cursor.
When the user returns, STATEWAKE compares that trusted continuation point against current project evidence.
It produces one of three outcomes:
VALID — the trusted continuation point still holds. STATEWAKE preserves it without unnecessary recovery or a new checkpoint.
INVALID — material project changes have made the previous continuation point unsafe.
AMBIGUOUS — evidence shows meaningful drift, but replacing protected user intent requires human authority.
In the primary demo, the user leaves with:
- Direction: Feature A
- Priority: Technical depth
- Next action: Finish Feature A integration
While they are away, Feature A leaves the active demo flow, Feature B becomes the current implementation path, and a Cloud Run deployment blocker appears.
STATEWAKE correctly determines that the old next action is no longer valid.
But it does not silently promote Feature B into the user's confirmed direction.
Instead, it presents a Decision Gate and asks one consequential authorization question.
After the user explicitly approves Feature B, STATEWAKE commits checkpoint CP-02:
- Direction: Feature B
- Priority: Demo clarity
- Do First: Resolve Cloud Run deployment failure
- Ignore for Now: Feature A integration
The result is a Resume State: a verified working state the user can actually continue from.
Collaboration Memory
STATEWAKE can also save explicit guidance about how the user wants future project changes interpreted.
In the demo, the user saves this rule:
Experimental implementation alone does not establish approved scope without explicit confirmation.
Later, an experimental Feature C prototype appears in the live GitHub repository.
On the second Re-entry, STATEWAKE applies the saved collaboration rule, recognizes Feature C as experimental, preserves Feature B as the approved direction, and keeps the existing Cloud Run blocker as the next action.
No clarification is needed.
No new checkpoint is created.
No false recovery occurs.
This demonstrates both sides of collaborative agent behavior:
knowing when to stop and ask, and knowing when not to interrupt.
How we built it
STATEWAKE runs as a production web application on Google Cloud Run.
The frontend is built with HTML, CSS, and Vanilla JavaScript, served from the same FastAPI application as the backend.
The production Re-entry workflow uses Google ADK to coordinate the agent and expose read tools for:
- Trusted Project State
- Collaboration Memory
- current project evidence
Gemini 3.5 Flash on Vertex AI performs semantic interpretation of project drift.
Cloud Firestore stores:
- Trusted Project State
- immutable checkpoints
- state versions
- evidence cursors
- Re-entry sessions
- explicit Collaboration Memory
A public GitHub repository acts as the live project-reality source. STATEWAKE reads recent commits, implementation state, documentation changes, deployment issues, and other evidence without writing back to GitHub.
The system deliberately separates three layers:
Evidence is observed.
Findings are inferred.
Trusted State is committed.
The model determines what evidence means.
Deterministic code determines what is allowed to become project truth.
Human authority and state integrity
Trusted State has a single writer:
prepare_resume_state
The agent cannot directly rewrite project truth.
A consequential direction change must pass through the Decision Gate and receive explicit authorization before a new checkpoint can be committed.
The state layer also enforces:
- optimistic state-version checks
- immutable production checkpoints
- atomic state transitions
- no partial Trusted State on failed sessions
- no direct evidence-to-state promotion
- no checkpoint creation on a VALID / no-mutation Re-entry
- no direct state mutation from Collaboration Memory
This makes the agent autonomous where it is safe and human-authorized where it is consequential.
Architecture
The production path is:
Browser → Google Cloud Run → FastAPI → Re-entry Workflow → Google ADK → Gemini 3.5 Flash on Vertex AI
The agent reads:
Cloud Firestore Trusted State + Collaboration Memory + read-only GitHub evidence
Its interpretation flows through a deterministic Decision Boundary.
For consequential ambiguity:
Human Decision Gate → explicit authorization → prepare_resume_state → Firestore checkpoint commit → Resume State
For a VALID state:
Preserve Trusted State → no new checkpoint
Challenges we ran into
The hardest challenge was defining the boundary between observed reality, agent interpretation, and authorized project truth.
A naive agent could see Feature B in the repository and automatically replace the user's confirmed Feature A direction. That would look autonomous, but it would actually be unsafe.
We therefore designed STATEWAKE so that project evidence can invalidate an old continuation point without automatically gaining authority to replace protected user intent.
Another challenge was avoiding unnecessary recovery.
An agent that constantly regenerates plans is disruptive. The second Re-entry was therefore just as important as the first: STATEWAKE had to recognize that experimental Feature C evidence did not invalidate the approved Feature B direction.
Production reliability also required work across Vertex AI authentication, Firestore access, Cloud Run service identity, evidence cursors, deterministic demo reset, and API response contracts.
Accomplishments that we're proud of
STATEWAKE demonstrates two opposite forms of agent maturity in one workflow.
First Re-entry: it knows when it must stop and ask for authority.
Second Re-entry: it knows when it should not ask again.
Both behaviors run through the real production stack using Google ADK, Gemini on Vertex AI, Cloud Run, Firestore, and live GitHub evidence.
We also implemented a deterministic Trusted State model, versioned checkpoints, a single-writer state boundary, Collaboration Memory, evidence cursors, responsive production UI, and a repeatable real-world demo flow.
What we learned
Building STATEWAKE changed how we think about memory in agents.
Persistent memory is not automatically beneficial.
If remembered state is stale, better memory can make an agent more confidently wrong.
Long-running agents need more than memory. They need validity checks, authority boundaries, selective human escalation, and the ability to preserve state when nothing important has changed.
Sometimes the correct agent action is not to act.
What's next
The current MVP deliberately focuses on one user, one technical project, and one public GitHub evidence source.
Future versions could support:
- private GitHub repositories through OAuth
- multiple projects and workspaces
- CI/CD and issue tracker evidence
- richer user-defined Collaboration Memory
- configurable authority policies
- team-level Trusted State
- additional project evidence sources
- deeper IDE and project-management integrations
The core principle would remain the same:
Do not recover from memory until you have verified that memory is still safe to continue from.
STATEWAKE — Come back without starting over.
Log in or sign up for Devpost to join the conversation.