- How does an agent enter the system? — POC intake with a 60-day clock.
- How does an agent earn production status? — Promotion criteria enforced at transition time.
- How does an agent leave? — Automated sunset when the POC expires or when an operator retires an agent.
Lifecycle Phases
Every agent definition carries a lifecyclePhase field that determines what the agent is allowed to do. The four phases form a linear progression:
AGENT LIFECYCLE PHASES
60-day trial period. Agent is active but time-bounded.
Auto-sunsets at expiry
Pre-production validation. Promotion criteria checked.
Optional intermediate phase
Fully governed. All promotion criteria satisfied.
No expiration clock
Deprecated. No dispatch allowed. Registry entry preserved.
Terminal state
| Phase | Status | Dispatch Allowed | Expiration | Transition Out |
|---|---|---|---|---|
poc | Active | Yes (time-bounded) | 60 days from intake | Promote, extend, or auto-sunset |
staging | Active | Yes | None | Promote to production or sunset |
production | Active | Yes (fully governed) | None | Sunset only |
sunset | Deprecated | No | N/A | Terminal — preserved for audit |
lifecyclePhase field is checked by Gate 2 (Agent Status) in the safety gates pipeline. Agents in the sunset phase have their status set to deprecated, which causes the gate to block all dispatch attempts.Phase Transitions
POC Intake
When a new agent definition is created, it starts without a lifecycle phase. An operator initializes the POC lifecycle explicitly, which sets the 60-day clock:lifecyclePhaseis set topocpocCreatedAtrecords the intake timestamppocExpiresAtis set to 60 days from nowpocExtensionCountis initialized to 0
Promotion Criteria
Promoting an agent frompoc or staging to production requires that four fields are populated on the agent definition. The promotion mutation validates all four and rejects the transition if any are missing:
| Required Field | Purpose |
|---|---|
riskTier | The agent’s assessed risk level (determines governance scrutiny) |
owner | The owning team responsible for the agent’s behavior |
autonomyRung | The agent’s position on the autonomy ladder (assistive, retrieval, supervised, or bounded) |
fiduciaryFlag | Whether the agent handles financial transactions or commitments |
pocExpiresAt) is cleared. The agent is now a fully governed production participant with no time limit.
POC Extension
If a team needs more time to evaluate a POC agent, they can extend the expiration by 30 days. Extensions are subject to constraints:- One free extension is allowed without security review (tracked via
pocExtensionCount) - A written justification is required and stored on the agent definition (
pocExtensionJustification) - Additional extensions beyond the first require contacting the security team directly
- The extension adds 30 days to the current expiration date, not the current time
Sunset Triggers
An agent enters thesunset phase through two paths:
A cron job runs every 6 hours and transitions POC agents whose pocExpiresAt has passed. Sets phase to sunset and status to deprecated. Sends a notification to operators.
An operator explicitly sunsets an agent at any phase (POC, staging, or production). The mutation is idempotent — sunsetting an already-sunset agent is a no-op.
Two-Agent Rule
The Two-Agent Rule is a financial safeguard for high-autonomy agents. It applies specifically to Rung 4 (bounded) agents — those that execute within limits without per-action human confirmation.Financial Threshold
When a Rung 4 agent’s estimated action cost exceeds the financial threshold, the action requires dual approval before proceeding:TWO-AGENT RULE THRESHOLD
FINANCIAL_THRESHOLD_CENTS = 10,000
Actions with an estimated cost above $100 (10,000 cents) at Rung 4 trigger the Two-Agent Rule. The governance pipeline returns a hold disposition, requiring human approval before the action can proceed.
How It Works
| Condition | Result |
|---|---|
| Agent is not Rung 4 (bounded) | Rule does not apply. No additional approval required. |
| Agent is Rung 4, estimated cost at or below $100 | Rule does not apply. Agent executes within its normal autonomy limits. |
| Agent is Rung 4, estimated cost above $100 | Rule triggers. Governance returns hold. Human approval required. |
Autonomy Rungs Reference
The Two-Agent Rule only applies at Rung 4. Here is the full autonomy ladder for context:| Rung | Name | Behavior | Two-Agent Rule |
|---|---|---|---|
| 1 | Assistive | Human reviews before any action | N/A |
| 2 | Retrieval | Read-only from trusted sources | N/A |
| 3 | Supervised | Agent proposes, human confirms | N/A |
| 4 | Bounded | Agent executes within limits | Applies above $100 |
Registry Reconciliation
Registry reconciliation is Forge’s mechanism for detecting shadow agents — agents that exist as definitions but have no corresponding registry entry, or agents whose registry state has drifted from their approved configuration.Reconciliation Process
Every 6 hours, an automated reconciliation job compares all active agent definitions against theagentRegistry table and classifies each agent:
Registry entry exists and was checked within the last 6 hours. Normal operating state.
Registry entry exists but has not been reconciled in over 6 hours. Warning notification sent.
No registry entry found. P0 alert — this agent is unregistered and should not be dispatching.
| Status | Registry Entry | Last Reconciled | Notification |
|---|---|---|---|
current | Exists | Within 6 hours | None |
stale | Exists | Over 6 hours ago | Warning |
missing | Does not exist | N/A | P0 Error alert |
missing status is the most serious finding — it indicates an agent definition exists without a corresponding registry entry. This is the “shadow IT” scenario: an agent that was somehow created or activated outside the normal registration flow. Missing agents generate a P0 operator notification requiring immediate investigation.
Automated Crons
Lifecycle management relies on four automated cron jobs that run on fixed schedules:| Cron Job | Schedule | Purpose |
|---|---|---|
| Auto-Sunset Expired POCs | Every 6 hours | Finds POC agents past their pocExpiresAt and transitions them to sunset with status deprecated. Sends operator notification. |
| POC Day-30 Reminder | Daily at 08:00 UTC | Finds POC agents that have reached day 30 and sends a reminder to the owning team: promote, extend, or let it sunset at day 60. |
| Registry Reconciliation | Every 6 hours | Compares active agent definitions against agentRegistry. Flags missing and stale entries with operator notifications. |
| Convex-Native Agent Sync | Every 24 hours | Ensures all known Convex-native agents have corresponding agentRegistry entries. Prevents registry drift for built-in agents. |
POC LIFECYCLE TIMELINE
POC intake
Reminder sent
Auto-sunset (or day 90 if extended)
Production (no expiry)
Next Steps
Agent Trust
Autonomy rungs, trust levels, and the graduated autonomy model that governs what agents can do.
Approvals
Human-in-the-loop approval lifecycle — creation, escalation, and multi-surface resolution.
Safety Gates
The fail-fast pipeline that checks agent status, identity, and lifecycle phase at dispatch time.
Budget Controls
Budget hierarchy and the financial controls that complement the Two-Agent Rule.