docs: define scoped session continuity and bounded recovery guidance

docs/plans/scoped-session-open-20261023.md

@@ -1,5 +1,7 @@
 # Scoped host opening and shell readiness
 
+The broader objective and staged acceptance criteria are maintained in [workspace-session-continuity.md](workspace-session-continuity.md): sustained, authorized agent work across sessions within a workspace. This PR is its first implementation increment.
+
 ## Goal and baseline
 
 Initial base: upstream main 695fd2768, fetched 2026-10-23. Final integration base: e9818a619 (latest upstream at the pre-submission synchronization). Future PRs must fetch upstream first and use its latest main as the base. The old experimental branch and patch are retained outside the maintained repository. Existing changes in the maintained repository remain untouched.

docs/plans/workspace-session-continuity.md

@@ -0,0 +1,57 @@
+# Agent session continuity within a workspace
+
+## Objective
+
+Let an agent continue an authorized task across multiple sessions in its workspace, including recovery from transient disconnects, sleep/wake connection loss, slow shell startup, and an unresponsive terminal. A recoverable session problem should not automatically end the whole task or require the user to repeat its instructions.
+
+The workspace is the collaboration and permission boundary. The host grants access to particular sessions and management operations; the main process enforces those grants across RPC, IPC, and CLI paths. Being displayed in a workspace does not itself grant access, transfer ownership, or authorize closing another chat's session. Existing task authorization should be reusable for permitted recovery without repeated permission questions.
+
+## Current delivery: PR 3885
+
+- Open a new host session in an explicitly selected workspace and bind it to the requesting chat scope, or return an explicit binding failure.
+- Preserve upstream reuse-first behavior and original ownership, including visibility of sessions already auto-reconnecting.
+- Wait for a live shell prompt before delivering commands to tracked shell-backed PTYs, with bounded waits and cancellation.
+- Document bounded recovery decisions using capabilities available in the running build.
+
+Explicit reconnect, moving an existing session, and restarting a connection are not implemented by this PR. The larger objective explains this first increment; it is not a claim that the recovery lifecycle is already complete.
+
+## Next increments
+
+1. **Reconnect within the same tab.** Expose an authorized reconnect operation for disconnected sessions, preserving session identity, workspace placement, useful history, and scope. Reuse an in-flight reconnect instead of starting another connection. Return connected/ready only after those states are observed; surface authentication requirements separately.
+2. **Open or attach a recovery session.** Allow a permitted existing session to join the selected workspace, or open an independent session to the same verified host when the old transport is unusable. Preserve its management permissions and scope throughout placement. Coalesce duplicate recovery requests and return whether a session was reused or created.
+3. **Recover an unresponsive connection.** Expose explicit replacement/restart where permitted, fence old-generation writes and late callbacks, and preserve diagnostics. Reopening a connection does not prove the old remote process was terminated. Process termination requires a separately verified target and existing authorization.
+4. **Coordinate ongoing work.** Keep per-session execution reservations and cancellation; track whether a command was not sent, acknowledged, completed, or has an unknown outcome. Multiple sessions can support independent jobs while tool calls remain serialized wherever the host requires it. Do not replay a possibly executed command to simulate progress.
+
+Each increment starts with lifecycle and scope regressions, reuses existing session actions and permission checks, and is delivered as a small change against freshly fetched upstream main. Preserve observer/confirm/auto behavior and distinguish session visibility from management permission.
+
+## Recovery policy
+
+Use existing session recovery before creating a new tab. Defaults per target session/host in one incident: at most three recovery attempts including the first, wait 2 seconds and then 5 seconds before another attempt, and stop starting attempts after a 120-second elapsed budget including connection and waiting time. A smaller user/host limit takes precedence. A new chat turn or tab does not reset an ongoing incident's budget. Create at most one new recovery session for that incident; reuse it on subsequent checks.
+
+Apply retry only to transient transport/startup conditions when it is known that no task command was delivered, or to an inspection/reconnect operation whose semantics permit retry. Authentication rejection, missing permission, revoked scope, invalid targets, and user cancellation need a different action; they are not transient retry signals. A program returning a nonzero exit code is not evidence that its terminal connection is broken.
+
+After an ambiguous timeout or disconnect during execution, inspect the existing job, marker, process, output, or durable result before considering another execution. Exhausting recovery pauses only the blocked dependency; continue independent authorized work and report the session, observed state, attempted actions, and what remains unknown. Do not skip required work or report it as complete.
+
+The Skill is operator guidance, not a backend retry controller or a grant of permissions. New lifecycle tools must enforce their own deadlines, generation checks, idempotency, and workspace permissions.
+
+## Acceptance scenarios
+
+| Scenario | Required result | Delivery |
+| --- | --- | --- |
+| Open a new connection for parallel work | Requested workspace, usable chat scope, explicit reuse/create result, no duplicate retry tabs | Placement/scope delivered; existing reuse preserved |
+| Slow local shell or SSH shell startup | No command bytes before readiness; bounded cancellation and explicit not-sent failure | Delivered for tracked shell PTYs |
+| Brief network loss or sleep/wake disconnect | Reconnect original tab within its grant, preserve scope, resume after observed readiness | Planned explicit reconnect |
+| Old terminal is unresponsive | Inspect/cancel appropriately, then use one permitted independent connection in the same workspace | Creation is available where exposed; automated recovery orchestration planned |
+| A command may have executed before disconnect | Diagnose outcome; no automatic replay of a possibly mutating command | Skill guidance; richer delivery state planned |
+| Permission revoked or user stops the task | No reconnect/reopen/resume that bypasses that decision | Existing enforcement retained; lifecycle regressions required for new tools |
+| Same failure persists | Bounded retries/backoff, no tab storm, clear blocked-dependency report | Skill guidance; controller enforcement required with lifecycle tools |
+
+## Status
+
+Planning and Skill guidance for the continuity objective. PR 3885 remains the first implementation increment. No disconnected-session reconnect/restart/move tool is claimed by this document. Apply Skill updates through the application's normal distribution/synchronization path; do not rely on overwriting a user's separately maintained interruption skill.
+
+## Guidance validation
+
+- The bundled skill passes skill-creator quick_validate.py; Markdown references and the existing control/error routes were inspected.
+- Scenario walkthroughs: transient disconnect uses the bounded incident budget; a known busy job is polled rather than receiving new input; authentication/scope denial stops retry; uncertain command completion requires inspection before replay; a missing reconnect capability is reported rather than invented; explicit user cancellation is respected.
+- This documentation/Skill increment adds no executable lifecycle behavior or installed-user-skill replacement. No runtime test or new production build is claimed for these text-only edits.

skills/netcatty-tool-cli/SKILL.md

@@ -22,6 +22,7 @@ For routine tasks, the host prompt is usually enough. Read only the reference th
    - Treat `exec` as the short-command path only. If the command may exceed about 60 seconds, or streams output for an extended period, use the long-running job commands instead of plain `exec`.
 5. If the host prompt already names a connected default target session, use that session directly for routine requests that do not mention another session or host, but still start with `session --session <id> --json` instead of jumping straight to `exec` or `sftp`.
 6. Only fall back to `env` lookup when the task is ambiguous, the user points to another session, or that direct `session` lookup fails.
+7. For disconnects, stalled sessions, or recovery across multiple sessions, read `references/control-commands.md`. Prefer bounded recovery within the granted workspace scope; a new connection must not silently lose that scope.
 
 ## Core Rules
 
@@ -45,5 +46,5 @@ Examples:
 - SFTP file workflow: `references/sftp.md`
 - Vault notes workflow: `references/notes.md`
 - Session and device-type handling: `references/session-types.md`
-- Cancel, resume, and runtime diagnostics: `references/control-commands.md`
+- Cancel, resume, runtime diagnostics, and bounded session recovery: `references/control-commands.md`
 - Error handling and authoritative failures: `references/errors.md`

skills/netcatty-tool-cli/references/control-commands.md

@@ -1,11 +1,11 @@
 # Control Commands
 
-Read this when you need diagnostics, cancellation, or to re-enable a cancelled chat scope.
+Read this for diagnostics, cancellation, or bounded recovery after a session cannot continue.
 
 ## Useful Commands
 
-  - Existing connected/connecting sessions are reused by default and keep their original placement and owner. Use `--new-tab` only when a separate connection is needed; workspace placement applies to the newly opened session.
-  - Open a fresh saved-host session and bind it to the authenticated chat scope:
+- Existing connected/connecting sessions are reused by default and keep their original placement and owner. Use `--new-tab` only when a separate connection is needed; workspace placement applies to the newly opened session.
+- Open a fresh saved-host session and bind it to the authenticated chat scope:
   - `<netcatty-cli-prefix> vault host open --host-id <id> --new-tab --json`
 - Open a fresh pane inside the main window's active workspace:
   - `<netcatty-cli-prefix> vault host open --host-id <id> --new-tab --workspace-id current --json`
@@ -27,3 +27,18 @@ Read this when you need diagnostics, cancellation, or to re-enable a cancelled c
 
 - `cancel` affects the current chat scope; it requests cancellation for in-flight `exec`, session-backed SFTP transfers, and running `job-start` work in that scope. Later `exec` calls in that scope stay blocked until `resume`.
 - Do not issue control commands concurrently with other Netcatty CLI commands for the same chat session.
+
+## Bounded Recovery
+
+1. Keep the task context: target host/session/workspace, active job, and last command outcome. Inspect `session --session <id> --json`; use scoped `env` when discovery is needed. Distinguish a transport failure from a program returning a nonzero exit code, a busy job, or a program waiting for input.
+2. Prefer a usable existing session or an already in-flight auto-reconnect. For a known job, inspect it with `job-poll` at the host's normal polling cadence instead of injecting another command. Do not send a shell probe into a password/input prompt or an unknown foreground application.
+3. For a transient connection/startup failure, allow at most three recovery attempts including the first, with waits of 2 seconds and then 5 seconds before retrying, and a 120-second elapsed budget including connection/wait time. Do not start another call if its budget would exceed the remaining time. User/host limits can shorten this policy. Do not reset an incident's budget by changing tabs or chat turns.
+4. Use explicit reconnect/restart/move tools only if the running build exposes them and the current grant permits them. This PR adds no such tools; `resume` only removes a chat cancellation block, and `host open` does not reconnect an inactive disconnected tab. Do not invent a command or switch identities to obtain a missing capability.
+5. When an independent connection is needed and host opening is available, verify the saved host identity and request the intended workspace explicitly (prefer its concrete ID when known). Create at most one new recovery session per incident; inspect/reuse that result instead of repeatedly opening tabs. Require successful scope binding and confirm session metadata before using it. Visible workspace membership alone does not grant access or ownership. Close only sessions the current scope is permitted to manage.
+6. `SHELL_NOT_READY` from the tracked PTY readiness gate means the command was not delivered. Diagnose startup/busy/input/custom-prompt state before a bounded retry. An execution timeout, dropped response, or disconnect after delivery can mean the command ran: inspect its job/marker/process or durable result before considering replay, especially for writes or deployments.
+7. Stop automatic recovery on authentication rejection, missing permission, revoked scope, an invalid target, or an explicit user stop. Do not call `resume` or open another connection to undo the user's cancellation. Preserve existing authorization for recovery actions already granted; do not ask for the same permission repeatedly.
+8. When the budget is exhausted, stop that recovery branch, continue independent authorized work, and report the affected session, observed state, attempt count, and whether command completion is unknown. Do not silently omit blocked work or claim success.
+
+Opening or closing a terminal connection does not confirm that an old remote process stopped. If process termination is necessary, first verify the same host and a unique process target (marker/PID/PGID and command/start-time evidence). A forced cancellation result releases tooling locks; it is not process-exit evidence.
+
+Independent jobs may run on separate permitted sessions through `job-start`; issue CLI calls serially as required by the host. Avoid concurrent input to the same shell. These limits guide the agent's decisions; future lifecycle tools still need backend deadlines, permission checks, and duplicate-request protection.

skills/netcatty-tool-cli/references/errors.md

@@ -5,6 +5,8 @@ Read this when a Netcatty CLI call fails or returns a blocked state.
 ## Rules
 
 - Treat Netcatty CLI errors as authoritative. Do not argue with them or try alternate launch methods.
-- If Netcatty returns `COMMAND_ALREADY_RUNNING`, wait for the in-flight command to finish instead of retrying in parallel.
+- If Netcatty returns `COMMAND_ALREADY_RUNNING`, inspect/wait for the existing operation with a bounded recovery budget instead of retrying in parallel. See `control-commands.md`; do not wait indefinitely or assume the shell is stuck.
+- For transient disconnect/startup failures, follow the bounded retry/backoff policy in `control-commands.md`. Authentication, permission, scope, and explicit user-cancellation failures are not signals for repeated reconnects or alternate entrypoints.
+- After an execution timeout or lost response, command completion may be unknown. Do not replay a potentially mutating command without inspecting its outcome.
 - Netcatty enforces scope, approvals, blocklists, and timeouts. Do not try to bypass those checks with wrappers or alternate shells.
 - If a direct command fails and the failure suggests the task genuinely needs branching or parsing logic, then consider a small script. Otherwise keep commands simple.