Sessions

A session is an agent conversation connected to workspace repositories, with messaging, Git, workflow, review, and verification controls.

Session modes

Mode determines working-copy lifetime and intended completion behavior.

Mode	Working copy	Use
Chat	Persistent and shared by matching repository branch selections.	Repository questions and ongoing conversations.
Develop	Isolated per session.	Changes intended for review, commit, push, or pull request.

Bot conversations use the bot's configured Chat or Develop mode rather than a separate session mode.

Lifecycle

Lifecycle status shows whether the agent can accept work.

Status	Meaning
Waiting	Ready for user input.
In Progress	Agent work is active.
Done	Work completed.
Canceled	Work explicitly abandoned.
Error	Work failed.

Resetting context clears conversation context without ending the session. Eligible transient response interruptions, temporary host disconnects during working-copy setup, and in-flight sessions after service recovery resume automatically; review the latest message and Git state before continuing only when the session reports a final failure.

Creating a session

Session creation fixes the workspace, mode, model, and starting branches.

1. Select New Session.
2. Choose Chat or Develop and a model.
3. Select one starting branch per repository.
4. Enter the initial message and optional attachments.
5. Review session options, then start.

Use Develop for edits. Chat sessions with the same branch selections share a persistent working copy, so coordinate Git operations with other users of that Chat context.

Development control

Development controls determine how independently the agent proceeds.

• Manual pauses for operator direction between actions.
• Auto allows the agent to continue until it finishes or requires input.
• Session options can enable configured edge-case analysis, code review, verification, test updates, and documentation updates.

Start unfamiliar or production-sensitive work in Manual mode. Switch to Auto only after scope, branch, and safety constraints are confirmed.

Messages and actions

Messages are the session audit trail for user input, agent output, tool activity, failures, and system notices.

Use attachments and file mentions to provide precise context. Cancel an active message to stop current work; cancellation does not revert file or Git changes already made. Available message actions can include copy, edit-and-resend, retry, and feedback depending on message state.

Slash items and skills shown in the composer are limited by workspace, bot, ticket template, and permission configuration. Type / to discover enabled skills available to the session; mid-message autocomplete shows skills only.

Files and Git

The Files and Git areas expose the session working copy for review and source-control operations.

• Review changed files and diffs before committing.
• Commit related changes with a clear message.
• Pull before push when the remote branch may have changed.
• Resolve conflicts before retrying push or pull-request creation.
• In multi-repository sessions, verify the selected repository before each operation.
• Reset and discard actions are destructive and require confirmation.

Completing or canceling a Develop session can release its working copy. Push or otherwise preserve required work first.

Restoring an Error session

Restore retries a failed Develop session only after confirming that every required repository checkout is usable.

1. Open the session and review the final error and Git state.
2. Select Restore.
3. If the retained checkout is invalid or unreadable, Polygent moves its files to a separate recovery folder on the assigned host, clears stale checkout state, and creates a clean checkout.
4. Review the recovery notification or System message for the retained folder locations.
5. Copy any required files into the restored checkout, verify the changes, and remove the recovery folders when they are no longer needed.

Recovery-folder locations are recorded as soon as files move. If a later repository or checkout recreation fails, the notification and System message still list every retained location created so far. A later Restore also surfaces any pending locations before continuing, including when the clean checkout is already valid.

The session returns to Waiting only after all repository checkouts validate successfully and a retained location has been surfaced to the owner. If recovery fails, the session remains in Error and reports whether the host could not preserve the folder, clear stale Git state, recreate the checkout, validate the result, or record the retained locations. Correct that host filesystem or Git condition, then select Restore again. Normal cleanup still preserves working copies whose uncommitted or unpushed state cannot be evaluated safely.

Workflow and task execution

A session can run a selected workflow and workspace tasks.

Workflow progress shows the current step, required parameters, and pause state. Workspace tasks run configured commands in the selected repository context. Review task output before retrying; repeated retries without correcting environment, credentials, or working directory can reproduce the same failure.

See Workflows and Session Hooks.

Ralph Loop

Ralph Loop repeats a bounded instruction for iterative work such as fixing tests or addressing review findings.

Configure the prompt, maximum iterations, context reset behavior, and supported stop conditions. The session displays active iteration progress and updates automatically. Stop the loop when its premise becomes invalid, output repeats without progress, cost is excessive, or human judgment is required.

Only one loop can run in a session. A workflow Ralph Loop pauses workflow progression until the loop reaches its configured outcome.

IDE integration

IDE integration transfers Develop-session work between the host working copy and an authorized local IDE workflow.

Use the UI-provided instructions to open the session, pull committed IDE changes, or upload local uncommitted changes. Verify the session and branch before transfer. Tokens grant access to session Git operations: do not share them, store them in source control, or paste them into messages.

Chat sessions do not support IDE transfer because their working copies can be shared. If an operation is blocked, wait for active session Git work to finish and retry.

Session Hooks

Session hooks run configured workspace tasks at user-facing lifecycle points such as session creation, agent completion, session completion, or cancellation.

Setting	Purpose
Task	Workspace command to run.
Working Directory	Repository-relative execution context selected in the editor.
Timeout	Maximum runtime, shown in the hook editor.
Failure Behavior	Whether failure blocks lifecycle progression.
Condition	Optional rule controlling when the hook applies.

Hook commands and the processes they create run under host resource limits so builds and test suites do not consume the CPU capacity reserved for Polygent. This policy is the same for local and remote session hosts and does not change command output, input, exit codes, timeouts, or cancellation behavior.

Chat sessions are excluded from hooks intended for completed development work. A blocking completion hook can keep a session from reaching Done. Review its output, correct the task, then retry completion. Agent-assisted retry, where enabled, is bounded and does not replace a deterministic task fix.

Code Review

Code Review inspects session changes and reports categorized findings before completion. In the session sidebar, select a review result to expand or collapse its details.

Enable it in session or ticket settings. Review each finding against the actual diff, resolve valid issues, and rerun review after material changes. Secret findings require credential rotation if a real secret entered Git history or agent output; deleting the visible text alone may be insufficient.

Review can be skipped when there are no applicable changes or configuration disables it. A review failure does not prove the changes are safe; inspect the visible failure and perform manual review.

Verification

Verification evaluates completed changes against available requirements and reports pass, fail, warning, or unavailable outcomes shown in the session.

Verification complements code review: it checks whether requested outcomes are met, while code review checks change quality and risk. Confirm requirements and acceptance criteria are specific before relying on verification. Resolve findings and rerun after changes.

When both are enabled, Code Review and Verification run at the same time rather than one after the other. The session waits for both checks to finish, then sends at most one combined report so the agent fixes all findings in one pass instead of separate follow-up turns.

Presence, context, and cost

Session indicators help operators coordinate active work.

Presence shows other viewers, context usage indicates conversation pressure, and total cost summarizes recorded model usage. Reset context when stale history harms results, but first preserve decisions in the next message or an instruction artifact.

Completion and bulk actions

Completion closes successful work; cancellation stops unwanted work, including sessions in Error that you choose not to restore.

Canceling an Error session changes it to Canceled. Repeating cancellation is safe when the session is already Canceled, while a Done session remains Done. Direct and bulk cancellation show success only after the session is Canceled.

Before either action, review active agent work, uncommitted changes, unpushed commits, ticket linkage, and hook results. Cleanup preserves the working copy when Polygent cannot safely confirm that unreadable, uncommitted, or unpushed work can be removed. Bulk cancellation is destructive and requires confirmation. Deploy actions are available only where deployment is configured; see Deployment Worker.

Troubleshooting

These checks cover common session incidents.

Symptom	Check
Session does not start	Confirm host availability, model availability, repository credentials, branch existence, and workspace permissions.
Session appears stuck	Check the latest message and tool activity, host connectivity, and whether a hook, workflow step, or loop is active.
Agent sees stale files	For Chat, check for another session sharing the same branch selection; then review and pull Git changes safely.
Push fails	Verify remote credentials, branch permissions, upstream changes, and repository selection.
Completion is blocked	Review active messages, workflow state, verification/review requirements, and blocking hook output.
IDE transfer fails	Confirm Develop mode, token validity, branch identity, network access, and absence of another Git operation.
Context is exhausted	Preserve required decisions, then use Reset Context and continue with a focused message.