sshscript 5.0.0__tar.gz → 6.1.0__tar.gz

{sshscript-5.0.0 → sshscript-6.1.0}/.github/workflows/ci.yml

@@ -4,7 +4,7 @@ permissions:
   contents: read
 jobs:
   verify:
-    timeout-minutes: 20
+    timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:
@@ -48,7 +48,7 @@ jobs:
   openssh-integration:
     name: OpenSSH integration (Python ${{ matrix.python-version }}, ${{ matrix.dependency-label }})
     runs-on: ubuntu-latest
-    timeout-minutes: 25
+    timeout-minutes: 35
     strategy:
       fail-fast: false
       matrix:

{sshscript-5.0.0 → sshscript-6.1.0}/.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
   build:
     name: Verify and attest release artifacts
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     permissions:
       contents: read
       id-token: write

{sshscript-5.0.0 → sshscript-6.1.0}/.gitignore

@@ -119,3 +119,7 @@ htmlcov/
 !/unittest/test_stdin_contract.py
 !/unittest/test_syntax_error.spy
 !/unittest/test_update_check.py
+
+!/unittest/test_interactive_console.py
+
+!/unittest/test_embedded_console.py

sshscript-6.1.0/AI_GUIDE.md

@@ -0,0 +1,119 @@
+# SSHScript for AI agents
+
+**Documentation contract: SSHScript 6.1.0; Python 3.11+.**
+
+This guide targets SSHScript 6.1.0 and its public Console integration API.
+Install `sshscript==6.1.0` and verify the imported package version.
+For nested SSH, provision known_hosts on each calling host: `"parent"` is the
+default. Read the 4.0.2-to-5.0 migration before reusing older automation.
+
+Start with the [agent guide](skills/sshscript/references/agent-guide.md).
+It explains version checks, API selection, command results, input, deadlines,
+authentication and cleanup. Read only the task-relevant sections of the
+[canonical API guide](API_GUIDE.md) and [version policy](VERSIONING.md).
+
+The [SSHScript skill](skills/sshscript/SKILL.md) supplies a compact operating
+workflow. Its folder contains the supporting guide; copy the entire
+`skills/sshscript/` folder when installing it in an agent's skill directory.
+It teaches SSHScript usage, not development of SSHScript itself or a particular
+recipe library. Agents without skill support can read these Markdown files.
+
+## Borrowed Session integration (unified Console API)
+
+Use `from sshscript import Console` and `with Console(existing_session)` for an
+existing authorized connection. Read [the full host contract](EMBEDDED_CONSOLE.md)
+before driving it. Require structured completion/exit status and confirmed reuse;
+keep host account policy and credentials in the resolver. A prompt/silence is not
+a success signal. See the bundled skill for the matching agent guidance.
+
+## Interactive console (6.1)
+
+For step-by-step use from a human or UI agent's retained terminal, see the
+[console guide](CONSOLE.md) and the agent guide's
+[console instructions](skills/sshscript/references/agent-guide.md#interactive-console-61).
+Run `python3 -B sshscript.py console` from the matching development checkout;
+an installed 6.1.0 wheel provides `sshscript console`. Use public
+Console(session) for host integration; older 6.0 console internals are removed.
+
+Input remains Python with dollar commands: `$hostname` executes a command,
+`print($.stdout)` reads its result, and variables persist between inputs.
+`exit`/`exit()` leave one layer; `quit`/`quit()` close all layers. Script
+completion uses `$.stop()`; `$.exit()`, `Session.exit()` and wrapper `.exit()`
+are removed. These incompatible 6.0 rules do not describe stable 5.0.0.
+
+## Share one URL
+
+The website entry is [SSHScript for AI Agents](https://iapyeh.github.io/sshscript/v3a/ai-agents/).
+Users can give that URL and a task to an agent:
+
+> Read the SSHScript AI agent entry at
+> https://iapyeh.github.io/sshscript/v3a/ai-agents/ and follow its reading order.
+> Check the SSHScript version in my environment before selecting APIs. Help me
+> complete this task: [describe the task, target hosts and expected output].
+> If you cannot read a required document, report that limitation rather than
+> guessing its contents. Explain the proposed commands before execution and
+> stay within the operations I authorize.
+
+A URL supplies reference material for the current task. It does not install
+SSHScript, install a skill, grant execution permission, or guarantee persistent
+memory. An agent needs URL-reading tools, or the user must provide the files.
+
+## Set up before you have a task
+
+Users can also give an agent this prompt before requesting any automation.
+It requests a complete skill installation and a reusable preference where the
+agent supports them; downloading only `SKILL.md` omits the reference files.
+
+```text
+Read https://iapyeh.github.io/sshscript/v3a/ai-agents/ and the Agent Guide to
+understand SSHScript's purpose, APIs and execution limits.
+
+If you support installing skills, download the complete skill bundle linked
+on that page, install it using your environment's skill mechanism, and confirm
+that it can be loaded. If skills are unsupported, use that page as a reference
+entry for future SSHScript tasks.
+
+If you support persistent preferences or memory, save this preference:
+For future local or remote command execution, automation and interactive shell
+tasks, first assess whether SSHScript is suitable. Use it according to the
+documentation when appropriate; if another tool is more suitable, explain why.
+
+For now, only read the documentation and configure the skill and preference.
+Do not connect to remote hosts or run demonstration commands. Report whether
+the skill was installed and loaded and whether the preference was saved.
+Explain any limitations or steps that could not be completed.
+```
+
+Use the agent's own installation and preference mechanisms. Installation paths
+and invocation syntax vary by agent. If it needs user approval for a setup step,
+it should request that approval before proceeding. Reading a URL alone does
+not create persistent memory or authorize later command execution.
+
+## Maintain the source and website
+
+Maintain this entry, `skills/sshscript/SKILL.md`, and its reference guide in
+the designated `working_branch` checkout on branch `working_branch`.
+The landing page is maintained in `gh-pages/v3a/ai-agents/index.md` on branch
+`gh-pages`. The API guide remains authoritative for public behavior.
+
+From `working_branch`, synchronize the generated website guide, plain-text
+files and portable skill ZIP with:
+
+```sh
+python3 tools/sync_ai_docs.py ../gh-pages/v3a
+python3 tools/sync_ai_docs.py ../gh-pages/v3a --check
+```
+
+The ZIP includes the skill and its reference guide, plus snapshots of
+`API_GUIDE.md` and `VERSIONING.md` for offline use. These snapshots are generated
+from the source documents; do not edit the ZIP or generated website copies.
+The sync command checks the destination branch before writing. Website pages
+keep their Last Updated timestamp aligned with their mtime.
+
+When the execution contract changes, review the skill and guide, update their
+contract labels and the landing page, then regenerate the website assets.
+Validate links, skill structure, example behavior, source/ZIP equality and
+the rendered website. Source and website publishing are separate operations;
+copying files does not publish either of them.
+
+*Last modified: 2026-10-23 18:39:31*

{sshscript-5.0.0 → sshscript-6.1.0}/API_GUIDE.md

@@ -1,7 +1,7 @@
 # Recommended SSHScript API
 
 This is the canonical entry point for new code and AI-generated examples.
-**Current contract: 5.0.0**, Python 3.11+. Sections marked **4.0** require
+**Current release contract: 6.1.0**, Python 3.11+. Sections marked **4.0** require
 SSHScript 4.0.2 or newer; installing `sshscript==3.1.5` does not provide them.
 Examples labelled 3.1.5 remain verified compatibility examples for that baseline.
 Pin the exact artifact version and record it with execution diagnostics when
@@ -31,7 +31,8 @@ identifiers and handoff reports are future work, not a current API guarantee.
 
 ## One command, one retained result (4.0; compatible with 3.1.5)
 
-Install the current release with `python -m pip install "sshscript==5.0.0"`.
+Install `sshscript==6.1.0` for this contract. Verify the installed version and
+artifact before operational use; source publication alone does not install it.
 For reproducing only the historical compatibility baseline, explicitly install
 `sshscript==3.1.5`; the 4.0 sections require the current release.
 An argv list is one command, not a batch. Shell-looking argument text stays data.
@@ -234,7 +235,7 @@ print(result.stdout)
 
 ## 4.0: settings and managed jobs
 
-Use SSHScript 5.0.0 for the following examples. CLI `-v`, `--stderr`, and
+Use SSHScript 6.1.0 for the following examples. CLI `-v`, `--stderr`, and
 `--debug` override root defaults only for that execution. Child Sessions copy
 their parent's settings. `set()` validates before changing anything; `get()`
 returns a copy. Explicit command options override Session policy.
@@ -253,7 +254,7 @@ the settings dictionary at creation; the policy object itself is shared, so
 custom policies with mutable state must account for reuse. Changing the setting
 does not reconfigure existing connections.
 
-<!-- example: {"id":"settings", "profile":"5.0.0", "stdout":"True\n1\n"} -->
+<!-- example: {"id":"settings", "profile":"6.1.0", "stdout":"True\n1\n"} -->
 ```python
 from contextlib import closing
 import paramiko
@@ -275,7 +276,7 @@ semantics; do not combine it with `command_timeout`.
 For an indefinite command such as tcpdump, use `start(timeout=None)`. This safe
 local example uses a small Python process instead of capturing network traffic:
 
-<!-- example: {"id":"stop", "profile":"5.0.0", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stop", "profile":"6.1.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -314,7 +315,7 @@ legacy SSH behavior which appended a newline to strings: if a consumer
 needs a line, migrate `input=password` to `input=password + "\n"` explicitly.
 Published 3.1.5 still has the legacy SSH behavior.
 
-<!-- example: {"id":"exact-stdin", "profile":"5.0.0", "stdout":"'abc'\n'abc\\n'\n"} -->
+<!-- example: {"id":"exact-stdin", "profile":"6.1.0", "stdout":"'abc'\n'abc\\n'\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -383,7 +384,7 @@ or unpack exactly `stdout, stderr, exitcode`. This changes the released 3.1.5
 console contract: old `stdout, stderr = shell(command)` must be migrated.
 Shell calls accept command strings; argv execution belongs to Session.
 
-<!-- example: {"id":"shell-result", "profile":"5.0.0", "stdout":"first 0\n"} -->
+<!-- example: {"id":"shell-result", "profile":"6.1.0", "stdout":"first 0\n"} -->
 ```python
 from contextlib import closing
 from sshscript import Session
@@ -439,7 +440,7 @@ matching: `iter_stdout()` yields chunks, not packets or lines. Put `stop()` in
 `finally`, so condition matches, exceptions, and KeyboardInterrupt all trigger
 cleanup. This credential-free example uses a continuous Python process:
 
-<!-- example: {"id":"stream-condition", "profile":"5.0.0", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stream-condition", "profile":"6.1.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -504,7 +505,7 @@ the current Bash console's channel, cwd, environment and identity. It does not
 launch through the underlying Session. Ordinary `console(command)` / `$command`
 still waits and returns `CommandResult`; no migration is needed for finite commands.
 
-<!-- example: {"id":"console-stream", "profile":"5.0.0", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
+<!-- example: {"id":"console-stream", "profile":"6.1.0", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
 ```python
 from contextlib import closing
 import shlex
@@ -762,3 +763,31 @@ host prerequisites and are not credential-free examples.
 The same source is mirrored into the website; edit this file, then use
 `tools/sync_api_guide.py` to refresh the website copy. Additional protocol and
 production details remain in the full documentation.
+
+
+## Embed an existing Session (unified Console API)
+
+`from sshscript import Console` provides a supported integration surface without
+editing reserved variables. `Console(session)` borrows the connection, while
+`ownership="owned"` explicitly transfers ownership. Read the complete
+[API and lifecycle contract](EMBEDDED_CONSOLE.md) for structured updates,
+credentials, identity, PTY limits, exceptions and runnable examples.
+
+## Interactive console and script completion (6.0)
+
+See [the console guide](CONSOLE.md) for the 6.0 Python-first dollar REPL, retained
+variables, connect/sudo/su layers, text programs and migration from 5.0.0.
+Ordinary input is Python; `$hostname` runs a shell command and `print($.stdout)`
+reads its result. No language-mode switching is needed.
+Bare `exit` and `exit()` leave one managed layer, or close the console at the
+local root. Bare `quit` and `quit()` close the whole console.
+Use `help` or `help()` for console instructions and `help(object)` for Python
+object documentation.
+`$.stop(code=0, message="")` normally completes the nearest script runner;
+`$.exit()`, `Session.exit()` and wrapper `.exit()` are removed in both modes,
+as is the old `$.break()` name. Session.run()/run_script() return a dictionary-like
+ScriptResult with exitcode, stopped and message attributes; run_file() returns
+the integer status. Cleanup failures still propagate. Python SystemExit remains
+separate from normal script completion.
+
+*Last modified: 2026-10-23 18:39:31*

{sshscript-5.0.0 → sshscript-6.1.0}/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 6.1.0 — 2026-10-23
+
+- Add public `Console(existing_session)` for terminal and host/AI-agent interaction
+  over an existing Session, including target Sessions reached through jumps,
+  without reconnecting or changing authentication/host-key sources.
+- Retain Python variables, shell cwd/environment and interactive program state.
+  Expose structured submit/poll/input/interrupt/EOF and completion results.
+- Add account credential/policy and switch-result hooks, separate connection login
+  identity from effective shell identity, and expose the environment stack.
+- Borrow Sessions by default. Unwind console-owned layers and confirm Session
+  reuse; initialization/restoration/cleanup failures report unknown explicitly.
+- Fix lost prompt readiness after program Ctrl-C. Keep waiting_input after a
+  protocol match, running for ignored/unfinished interrupts, and real exit status
+  for exiting programs; support delayed prompt recovery through poll.
+- Use one Console implementation for CLI and embedding. Remove old internal
+  InteractiveConsole/open()/execute() entry points and :help/:quit aliases; use
+  Console(session), submit(), help/quit and structured status instead.
+- Add complete terminal/agent examples and the matching AI skill. OpsFeast reports
+  local/simulated and browser UI revalidation passed. This is distinct from real
+  SSH/jump/PAM/su/sudo validation; release CI records its own disposable native tests.
+- Development-stage releases do not guarantee backward compatibility unless
+  explicitly requested. Minor releases may include the differences listed above.
+
+## 6.0.0 — 2026-10-22 (incompatible source contract)
+
+- Add console helpers: help/help(), help(object), exit/exit() to leave one
+  managed layer, and quit/quit() for complete cleanup and termination.
+- Ctrl-C discards input or interrupts execution while preserving console state;
+  Ctrl-D at the Python prompt quits. Inside enter(), both keys are sent as raw
+  program control characters, with parent-shell return detected before unwinding.
+
+- Add `sshscript console`: a Python REPL with dollar syntax, persistent Bash
+  shells, retained variables and command-result snapshots,
+  automatic shell entry after connect, sudo/su layers, explicit text-program
+  entry, streaming command output and managed Ctrl-C recovery.
+- Replace `$.break()` with `$.stop()`. Normal completion is handled by the
+  nearest script/import boundary and preserves cleanup and partial names.
+- Remove `$.exit()`, Session.exit() and wrapper .exit() in both console and
+  script mode. Existing script-ending calls must become stop() or Python
+  sys.exit(). Remove the old SSHScriptBreak/SSHScriptExit control exceptions
+  and partial wrapper exit.
+- Return dictionary-like ScriptResult completion metadata from source runners;
+  preserve integer completion status from run_file().
+- Enable terminal line editing, including both Backspace control codes, when
+  Python readline support is available.
+- See [console usage](CONSOLE.md) and [6.0 migration](VERSIONING.md#60-console-and-script-completion-migration).
+  Source and local artifacts use 6.0.0. PyPI publication and release tags are
+  separate operations.
+
+
 This project records user-visible changes here. Release artifacts and their
 provenance are available from the linked GitHub Release and PyPI pages.
 
@@ -286,3 +336,5 @@ verified artifacts in the
 
 [Unreleased]: https://github.com/iapyeh/sshscript/compare/v3.1.4...release
 [3.1.4]: https://github.com/iapyeh/sshscript/releases/tag/v3.1.4
+
+*Last modified: 2026-10-23 18:39:31*

sshscript-6.1.0/CONSOLE.md

@@ -0,0 +1,217 @@
+# Interactive console (6.1)
+
+The SSHScript 6.1 console runs from the flat development checkout:
+
+```sh
+python3 -B sshscript.py console
+```
+
+Use Python 3.11 or newer with the project's dependencies. Install
+`sshscript==6.1.0` for `sshscript console`. No installation into the flat
+development checkout is required.
+
+## Embed an existing Session (new API)
+
+Use the public `sshscript.Console` API for borrowed Sessions, host-driven updates,
+credential hooks and explicit cleanup/reuse reporting. Read
+[the embedded console contract](EMBEDDED_CONSOLE.md) and its executable examples.
+The CLI uses the same Console core and ownership contract. Earlier 6.0 CLI
+compatibility is not maintained; see the linked contract for removed entry points
+and aliases. This guide describes the 6.1.0 release contract.
+
+## A Python console with dollar syntax
+
+Input is Python by default, with SSHScript dollar syntax available in the same
+namespace. No Python/shell language-mode switching is required:
+
+```text
+local [user]> hostname
+NameError: operation failed; inspect error for details.
+local [user]> hostname = "a Python variable"
+local [user]> hostname
+'a Python variable'
+local [user]> $hostname
+my-host
+local [user]> print($.stdout)
+my-host
+local [user]> actual_hostname = $.stdout.strip()
+local [user]> options = {"port": 2222, "username": "ops", "timeout": 15}
+local [user]> $.connect("my-ssh-alias", **options)
+```
+
+`hostname` reads a Python variable; `$hostname` executes a command. A shell
+command always needs its dollar prefix. `$cd /tmp` and `$export NAME=value`
+retain the shell's directory and environment for later dollar commands. Output
+streams while a command runs; a nonzero exit status is displayed and the console
+remains usable. Shell commands do not display an extra JobResult representation.
+
+`$.stdout`, `$.stderr` and `$.exitcode` read the most recent dollar-command result
+in the current managed layer. These are result snapshots, not drained live
+buffers. The `result` Python name retains the latest dollar-command JobResult.
+You can mix dollar properties with Python expressions and f-strings, or unpack
+command results using the normal `.spy` syntax:
+
+```text
+local [user]> out, err, status = $printf ready
+local [user]> summary = f"host={$.stdout.strip()}, status={$.exitcode}"
+local [user]> for index in range(2):
+...     $f"echo item-{index}"
+...
+```
+
+On a terminal, the console enables Python's optional `readline` module for line
+editing, including Backspace. Python builds without that module retain the
+terminal's basic input editing; piped input does not require it. No history file
+is written.
+
+As in Python's REPL, a blank line completes an indented block. Parenthesized
+expressions and parameter dictionaries can span multiple input lines. Functions
+and variables remain available for later inputs. Ordinary Python strings that
+contain dollar characters remain literal strings. `with` blocks use the normal
+`.spy` compiler's lexical context management, rather than leaving a managed
+interactive layer open after the block. Inside lexical contexts, inspect or
+print returned command output explicitly, just as in a script.
+
+Reserved names are `control`, `session` (current connection Session), `console`
+(current shell/identity/program), `result` and `error` (latest operation error).
+`session` and `console` are refreshed when environments change. User variables
+survive environment changes; references to exited environments are not reusable.
+`getpass` is provided for reading secrets without terminal echo. No input history
+is saved by SSHScript; host terminal/session recording remains external.
+
+## Connections and identities
+
+A connection automatically enters its own persistent Bash shell. One `exit()`
+closes that shell and connection together and restores the parent environment.
+Nested connections are created by the current connection Session. They retain
+the existing SSH config, key ownership and known-host verification contracts.
+
+```sh
+python3 -B sshscript.py console ops@host1 --port 2222 --timeout 15
+python3 -B sshscript.py console my-ssh-alias --ask-pass
+```
+
+CLI options include `--username`, `--port`, `--pkey-path`, `--timeout`,
+`--ssh-config`, `--known-hosts`, `--known-hosts-path` and `--ask-pass`.
+For interactive parameter dictionaries, use the normal Session.connect keyword
+names. Configure a custom trust path with `$.set(known_hosts_path="...")` on the
+calling Session before connecting. Never disable host-key verification merely
+to make a connection succeed.
+
+```text
+host1 [ops]> $.sudo(password=None)
+host1 [root]> $.su("postgres", password=None)
+host1 [postgres]> exit()
+host1 [root]> exit()
+host1 [ops]> exit()
+local [user]>
+```
+
+Omitting an authentication password asks through getpass in a terminal. Use
+`password=None` explicitly for passwordless authentication; nonterminal input
+requires an explicit password argument rather than an invisible password read.
+You can also set a variable with `password = getpass("Password: ")` in Python and reference it in an expression. Do not place real secrets in literal
+commands or shared transcripts.
+
+The displayed account is queried after entering the environment, not assumed
+from the requested account. `:status` shows all environment layers. File
+transfers retain the SSH connection account's permissions even inside sudo/su.
+The console rejects connect() from explicit sudo/su/shell/program layers: leave
+that layer first. Elevating a console does not change the Session's SSH
+credentials or the account owning its SFTP/key-file reads.
+
+## Text programs and interruption
+
+Use explicit enter() for a program that asks questions or provides a REPL:
+
+```text
+local [user]> $.enter("python3 -q -u", prompt=">>>", exit="quit()")
+local [?] program> print(6 * 7)
+42
+local [?] program> exit()
+local [user]>
+```
+
+Configure the program's actual readiness prompt and exit sequence. Plain input
+in this layer goes to the program; `exit`, `exit()`, `quit`, `quit()`, lines
+beginning with `$.` and the colon management commands remain reserved. Use
+`$.input(...)` or `$.send(...)` to send text that would otherwise be interpreted as a management expression.
+Ctrl-C/Ctrl-D go to the entered program. In particular, Ctrl-D in an entered
+Python REPL exits that REPL and restores the SSHScript prompt, rather than
+closing the entire SSHScript console. Outside enter(), Ctrl-C requests managed
+shell cancellation or interrupts Python code. An interrupted Python multiline
+input is discarded. A failed/unusable channel
+is removed from the environment stack; the console never silently reconnects
+and claims that the previous state survived. At the Python prompt, use
+`exit` or `exit()` to leave a layer. If a text program returns to its parent
+shell and that return is detected, its program layer is closed automatically.
+
+This console supports text commands and explicitly configured text programs,
+not full-screen applications or transparent terminal passthrough. Dollar shell
+commands do not automatically detect interactive programs; use enter() for them.
+Command results retain up to 8 MiB per stream; reaching that capture limit is
+reported and the displayed stream may omit output. PTY stdout/stderr can merge.
+Readiness or silence is not interpreted as a successful process exit.
+
+## Stop a script, leave a layer, or quit
+
+- `$.stop(code=0, message="")` normally completes the nearest script execution.
+  It is unavailable at the console prompt itself.
+- Bare `exit` and `exit()` leave one managed interactive layer. At the local
+  root they close the console. These are console helpers, not script APIs.
+- Bare `help` or `help()` displays console instructions; `help(object)` retains
+  Python's object documentation behavior.
+- Bare `quit` and `quit()` close every managed layer. Calling `exit()` or
+  `quit()` unwinds the current Python cell, including `finally`/lexical contexts,
+  before performing the requested cleanup.
+- Ctrl-C at a Python prompt discards the pending input. During Python execution
+  it interrupts that code; during a shell command it requests managed cancellation.
+  Variables and usable environments remain available afterward.
+- Ctrl-D/EOF at the Python prompt closes all layers, like quit(). In a terminal,
+  EOF is produced by Ctrl-D on an empty input line; partial-line behavior follows
+  the terminal's normal line editing.
+- In an enter() program, Ctrl-C/Ctrl-D are forwarded as raw terminal control
+  characters, without an added newline. Only a detected return to the parent
+  shell closes that program layer; the Python console stays available.
+- Use `help`/`help()` and `quit`/`quit()`. The former `:help` and `:quit` aliases
+  are removed; `:status` shows the environment stack.
+  The Python helper names can be shadowed by assignment, just like Python names;
+  the colon aliases and `control.quit()` remain available.
+- Python `sys.exit()` retains SystemExit semantics. The interactive boundary
+  catches it, reports its status and keeps the console open.
+
+The console intentionally gives `exit` and `exit()` the same one-layer behavior.
+Use `quit` or `quit()` for all layers, and `$.stop()` for normal script
+completion. `$.exit()` is removed in both console and script mode.
+
+`script_result = $.run(source)` executes in the current connection Session; it
+does not inherit an elevated console as its command target. `$.run_file(path)` uses the public
+file runner, which creates a fresh local Session. A stopped script returns to
+the console. Assign its returned ScriptResult to inspect completion and names;
+script results do not automatically replace the console's Python namespace.
+`with` and `finally` still perform cleanup on early completion.
+
+`Session.run()` and `run_script()` return ScriptResult, a dictionary of executed
+names with `.exitcode`, `.stopped` and `.message` attributes. `run_file()` returns
+the integer completion status. A stopped imported `.spy` module keeps the names
+initialized before stop(), and its importer continues normally. Cleanup failures
+remain errors even if the script requested normal completion.
+
+## Incompatible changes from 5.0.0
+
+Replace `$.break(...)` with `$.stop(...)`. Replace script-ending `$.exit(...)`
+with `$.stop(...)` for normal completion, or Python `sys.exit(...)` when the
+caller should receive SystemExit. The old Break/Exit exception classes and the
+old direct wrapper exit behavior are removed. `$.exit()`, `Session.exit()`
+and wrapper `.exit()` are no longer available. In the console, use `exit` or
+`exit()` to leave one managed layer. In scripts, let Python manage lexical
+`with` blocks. The earlier preview's bare-exit reminder and whole-console
+`exit()` behavior are replaced by this one-layer rule.
+
+The initial shell-first preview's `:python` and `:shell` commands are removed.
+Input now follows Python/dollar syntax throughout; prefix shell commands with `$`.
+
+Type `help` for a reminder. Operation failures display their type without
+reprinting credential-bearing input; inspect `error` at the prompt for details.
+
+*Last modified: 2026-10-23 18:39:31*