From c56c4bb390f4b7ecf92f06cd9c158acac9c61d0d Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 10 Sep 2026 00:21:01 +0200
Subject: [PATCH] docs(hub): explain execution recovery across restarts

---
 public-docs/hub/daemons.md |  2 ++
 public-docs/hub/github.md  | 10 ++++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/public-docs/hub/daemons.md b/public-docs/hub/daemons.md
index a208838266..11214da231 100644
--- a/public-docs/hub/daemons.md
+++ b/public-docs/hub/daemons.md
@@ -96,6 +96,8 @@ worktree:
 
 For agents it dispatched, Hub owns creation, reconnect recovery, output observation, and completion. Agents you start yourself are untouched.
 
+Restarting Hub lets active agents continue working. Hub reconnects to the same agents and resumes tracking their output and completion. [GitHub credentials retain their original lifetime](/docs/hub/github#restarts-and-credential-lifetime).
+
 If Hub loses the create response, or the daemon restarts mid-execution, Hub resends the same create intent with the same execution id. The daemon returns the existing agent rather than running the prompt again. An agent that closed or errored is recorded as interrupted; Hub never silently starts a second one.
 
 ## Status
diff --git a/public-docs/hub/github.md b/public-docs/hub/github.md
index 51b9a0e28b..b3b77a4e16 100644
--- a/public-docs/hub/github.md
+++ b/public-docs/hub/github.md
@@ -37,7 +37,7 @@ steps:
           ${{ paseo.prompt }}
 ```
 
-The agent can use `git` and `gh` within the declared repositories and permissions. Hub mints the token when the step starts and revokes it when execution ends.
+The agent can use `git` and `gh` within the declared repositories and permissions. Hub mints the token when the step starts and revokes it when execution ends or its configured duration elapses.
 
 ## Fields
 
@@ -50,6 +50,12 @@ The agent can use `git` and `gh` within the declared repositories and permission
 
 Requested authority cannot exceed the GitHub App installation. Activation and dispatch fail clearly when the connection, repository, or permissions cannot be resolved.
 
+## Restarts and credential lifetime
+
+Restarting Hub preserves active executions and their existing credentials. Hub reconnects to the same agent and restores the original credential deadlines. A restart does not mint a replacement token or extend its lifetime.
+
+If Hub is unavailable when a shorter duration elapses, it revokes the overdue token when it returns. GitHub’s own expiry still limits the token lifetime to one hour. Revocation failures are retried after recovery.
+
 ## Agent environment
 
 Hub supplies `GH_TOKEN` and process-scoped git configuration through environment variables:
@@ -73,4 +79,4 @@ env:
   SOME_TOKEN: "${{ paseo.connections.some-connection.token }}"
 ```
 
-Hub resolves the value for the step and does not persist it. See [Hub security](/docs/hub/security) for provider and host boundaries.
+Hub persists resolved values as private execution data so it can recover after a restart. Authored configuration retains the expressions. See [Hub security](/docs/hub/security) for provider and host boundaries.