# Portal Guide Lifecycle And Recording

> Nested lingtai-portal-guide reference for portal lifecycle-state interpretation, heartbeat staleness, recording, and tape reconstruction behavior.

- Skill: `lingtai-ai/portal-guide-lifecycle-and-recording` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lingtai-ai/portal-guide-lifecycle-and-recording`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lingtai-ai/portal-guide-lifecycle-and-recording/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lingtai-ai (https://skillmd.com/u/lingtai-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lingtai-ai/portal-guide-lifecycle-and-recording

---


# Lifecycle and recording

This is a nested `lingtai-portal-guide` reference. It covers how the portal interprets agent lifecycle states and how it records/rebuilds topology history.

## 5-state lifecycle

| State | Meaning |
|-------|---------|
| `ACTIVE` | Agent is running and processing |
| `IDLE` | Agent is running but waiting for input |
| `STUCK` | Agent encountered an error or is unresponsive |
| `ASLEEP` | Agent is in sleep mode (`.sleep` signal or explicit lifecycle transition) |
| `SUSPENDED` | Agent process is not running (kernel/manifest reports it as such) |

Heartbeat is the portal's liveness ground truth, but it is observed independently from the manifest lifecycle state. `BuildNetwork()` calls `IsAlive(..., AgentAliveThresholdSec())`, which resolves the shared TUI/Portal/kernel liveness window from the `LINGTAI_AGENT_ALIVE_THRESHOLD_SEC` env var (default 10 seconds; missing, blank, malformed, non-finite, zero, or negative values fall back to the default). A stale or missing heartbeat only clears `AgentNode.Alive` — it does not rewrite `.agent.json`'s stored `state`, so a genuinely `SUSPENDED` manifest stays `SUSPENDED` while an `ACTIVE`/`IDLE`/etc. agent with a stale heartbeat keeps its real state and is simply reported not alive.

## Recording

The portal starts recording immediately on launch: a background goroutine calls `BuildNetwork()` every 3 seconds and appends the result as a JSONL line to `topology.jsonl`. This tape grows indefinitely.

## Reconstruction

On startup, if the tape needs reconstruction (missing, empty, or old format), the portal rebuilds it from replay chunks. While that runs, `.lingtai/.portal/reconstruct.progress` may contain a transient `current/total` progress string, which the `/api/topology/progress` endpoint parses and exposes to the browser UI.

A manual `POST /api/topology/rebuild` instead reconstructs from source data and rewrites the replay chunks. The `topology-and-api` reference documents both endpoints' exact response shapes.