docs(hub): clarify credential storage and retention

docs(hub): explain execution recovery across restarts
2026-10-25 18:52:39 +00:00 · 2026-09-10 08:21:13 +02:00 · 2026-09-10 00:21:01 +02:00
2 changed files with 14 additions and 2 deletions
@@ -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
@@ -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,8 @@ 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.
+
+These values are stored in the Hub database without application-level encryption. Protect database access, storage, and backups as credentials. Hub deletes the execution authority record when the execution becomes terminal; token lease records remain until revocation succeeds or the token expires, so interrupted cleanup can resume. This cleanup is not a guarantee that every copy is erased: retained agent/session data and database backups may still contain resolved values. Token revocation ends access; it does not erase those copies. Backup retention and deletion remain the operator’s responsibility.
+
+See [Hub security](/docs/hub/security) for provider and host boundaries.
Author	SHA1	Message	Date
Mohamed Boudra	757bf81cb9	docs(hub): clarify credential storage and retention	2026-09-10 08:21:13 +02:00
Mohamed Boudra	c56c4bb390	docs(hub): explain execution recovery across restarts	2026-09-10 00:21:01 +02:00