qubasic 0.5.1__tar.gz → 0.6.1__tar.gz

{qubasic-0.5.1 → qubasic-0.6.1}/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.6.1 (2026-06-18)
+
+### Fixed
+- Changing noise strength between runs (for example `NOISE amplitude_damping 0.1` then `0.9`) now rebuilds the circuit instead of reusing the first noise level, so sequential noise comparisons are correct.
+
+### Changed
+- The CLI now lives in `qubasic_core/cli.py`; the `qubasic` console script and `python -m qubasic_core` are unchanged, but the former top-level `qubasic` module is removed. Test suites moved under `tests/`.
+
+## 0.6.0 (2026-06-18)
+
+Correctness, scalability, and usability improvements.
+
+### Fixed
+- **Time-travel debugging now works**: STEP records statevector checkpoints, so REWIND/FORWARD/HISTORY operate (previously `_checkpoint_sv` was never called).
+- **TRON, breakpoints, ON TIMER, ON MEASURE now fire**: the debug hooks are wired into the execution loop instead of being dead code.
+- **PLOT and ANIMATE sweep correctly**: the transpiled-circuit cache key now includes variable bindings, so parameter sweeps no longer reuse the first circuit.
+- **`$XXXX` memory addresses parse**: PEEK/POKE/DUMP/SYS/WAIT accept the canonical hex-address notation, not only `0x`/decimal/`&H`.
+- **Multi-line IF/ELSE/END IF**: the untaken branch is properly skipped (previously both branches ran).
+- **ON ERROR** reports the real ERR/ERL for build-path errors and runs handler lines through the program executor (no spurious state dumps).
+- **OPTION BASE 1** is honored in array indexing; FOR with STEP 0 is rejected; bare `NEXT` and `NEXT i, j` are supported.
+- **CSV/EXPORT** report correctly when only a statevector (no counts) is present.
+
+### Performance / scalability
+- Stabilizer is chosen before MPS for large Clifford circuits, and the full 2^n statevector is no longer rebuilt after every measured run (a 30-qubit GHZ went from ~16s to <1s).
+- STEP evolves the statevector incrementally; DENSITY and EXPECT avoid building large matrices; HEATMAP and STATS reuse work.
+
+### Quantum / LOCC
+- LOCC depolarizing noise matches the Qiskit Aer convention; amplitude- and phase-damping channels are now simulated in the LOCC engine.
+- EXPECT/ENTROPY/DENSITY/BLOCH accept a register argument in SPLIT mode; `LOCC SHOTCAP` replaces the magic shot-cap variable; SEND prefix/suffix optimization detects all control transfers.
+- Per-qubit memory-mapped noise applies to multi-qubit gates; complex single-qubit amplitudes are exposed in the qubit-state block; POKE-driven state preparation is applied at build.
+
+### Language / interface
+- User-defined TYPE record fields can be read and assigned (`p.x`); ELSEIF chains and re-parsed clauses are memoized.
+- SAVE/LOAD round-trip noise, seed, screen mode, DEF FN, and TYPE definitions; CHAIN/MERGE/INCLUDE/IMPORT honor a `QUBASIC_PATH` search path; IMPORT no longer pollutes SAVE output.
+- CLI gains `--version` and `--agent`; `--json` output is enriched (statevector, variables, manifest) and emits structured errors; the agent write-sandbox engages under `--json`/`--agent`.
+- `SET_STATE` persists into the next RUN and warns when a named state cannot fit; per-command `HELP <name>`; dependency-version warnings are suppressed before the banner.
+
 ## 0.5.0 (2026-03-30)
 
 - **Colorized histograms**: bars colored green/yellow/dim by probability in terminal

{qubasic-0.5.1/qubasic.egg-info → qubasic-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.5.1
+Version: 0.6.1
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -73,11 +73,12 @@ Requires Python >= 3.10, Qiskit >= 1.0, qiskit-aer >= 0.13.
 ## Usage
 
 ```
-python qubasic.py                  Interactive REPL
-python qubasic.py script.qb        Run a script file
-python qubasic.py --quiet script    Suppress banner, output results only
-python qubasic.py --json script     Machine-readable JSON output
-python qubasic.py --help            Show CLI help
+qubasic                       Interactive REPL (installed console script)
+python -m qubasic_core         Same, without installing
+qubasic script.qb             Run a script file
+qubasic --quiet script         Suppress banner, output results only
+qubasic --json script          Machine-readable JSON output
+qubasic --help                Show CLI help
 ```
 
 Headless (no REPL):
@@ -468,15 +469,9 @@ BLOCH A 0                Bloch sphere for register A, qubit 0
 LOCCINFO                 Protocol metrics
 ```
 
-SPLIT: max capacity (31+31+...), no cross-register entanglement. Use SEND/IF for classical coordination.
+SPLIT: max capacity (up to 33 qubits per register), no cross-register entanglement. Use SEND/IF for classical coordination.
 
-JOINT: shared entanglement via SHARE. Limited to ~32 total qubits.
-
-### Network LOCC
-```
-CONNECT "host:port" AS C   Attach remote register (local simulation stand-in)
-DISCONNECT C               Detach
-```
+JOINT: shared entanglement via SHARE. Limited to 33 total qubits.
 
 ### LOCC optimization
 Programs with SEND execute the deterministic prefix (before first SEND) once, snapshot the statevector, then re-execute only the suffix per shot. Complexity: O(prefix + shots * suffix) instead of O(shots * total).
@@ -691,7 +686,7 @@ Programs with SEND use prefix/suffix splitting: the deterministic prefix (before
 ## JSON output
 
 ```
-python qubasic.py --json examples/bell.qb
+qubasic --json examples/bell.qb
 ```
 
 ```json
@@ -705,8 +700,9 @@ python qubasic.py --json examples/bell.qb
 ## Architecture
 
 ```
-qubasic.py              CLI entry point
 qubasic_core/
+  cli.py                 CLI entry point (qubasic / python -m qubasic_core)
+  __main__.py            Module entry point
   engine_state.py        Engine: standalone state container
   terminal.py            QBasicTerminal: REPL + command dispatch
   engine.py              Constants, gate tables, numpy simulation, LOCCEngine
@@ -735,9 +731,11 @@ qubasic_core/
   demos.py               Built-in demo circuits
   protocol.py            TerminalProtocol (mixin contract)
   mock_backend.py        MockAerSimulator for fast testing
+tests/                   Test suites (test_qubasic.py, test_features.py)
+examples/                Sample .qb programs
 ```
 
-`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 16 mixins. `Engine` can be used independently for headless/agent execution.
+`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 20 mixins. Execution methods live on `QBasicTerminal`, so headless/agent use should instantiate `QBasicTerminal` (the `Engine` base is a state container only).
 
 ## License
 

{qubasic-0.5.1 → qubasic-0.6.1}/README.md

@@ -40,11 +40,12 @@ Requires Python >= 3.10, Qiskit >= 1.0, qiskit-aer >= 0.13.
 ## Usage
 
 ```
-python qubasic.py                  Interactive REPL
-python qubasic.py script.qb        Run a script file
-python qubasic.py --quiet script    Suppress banner, output results only
-python qubasic.py --json script     Machine-readable JSON output
-python qubasic.py --help            Show CLI help
+qubasic                       Interactive REPL (installed console script)
+python -m qubasic_core         Same, without installing
+qubasic script.qb             Run a script file
+qubasic --quiet script         Suppress banner, output results only
+qubasic --json script          Machine-readable JSON output
+qubasic --help                Show CLI help
 ```
 
 Headless (no REPL):
@@ -435,15 +436,9 @@ BLOCH A 0                Bloch sphere for register A, qubit 0
 LOCCINFO                 Protocol metrics
 ```
 
-SPLIT: max capacity (31+31+...), no cross-register entanglement. Use SEND/IF for classical coordination.
+SPLIT: max capacity (up to 33 qubits per register), no cross-register entanglement. Use SEND/IF for classical coordination.
 
-JOINT: shared entanglement via SHARE. Limited to ~32 total qubits.
-
-### Network LOCC
-```
-CONNECT "host:port" AS C   Attach remote register (local simulation stand-in)
-DISCONNECT C               Detach
-```
+JOINT: shared entanglement via SHARE. Limited to 33 total qubits.
 
 ### LOCC optimization
 Programs with SEND execute the deterministic prefix (before first SEND) once, snapshot the statevector, then re-execute only the suffix per shot. Complexity: O(prefix + shots * suffix) instead of O(shots * total).
@@ -658,7 +653,7 @@ Programs with SEND use prefix/suffix splitting: the deterministic prefix (before
 ## JSON output
 
 ```
-python qubasic.py --json examples/bell.qb
+qubasic --json examples/bell.qb
 ```
 
 ```json
@@ -672,8 +667,9 @@ python qubasic.py --json examples/bell.qb
 ## Architecture
 
 ```
-qubasic.py              CLI entry point
 qubasic_core/
+  cli.py                 CLI entry point (qubasic / python -m qubasic_core)
+  __main__.py            Module entry point
   engine_state.py        Engine: standalone state container
   terminal.py            QBasicTerminal: REPL + command dispatch
   engine.py              Constants, gate tables, numpy simulation, LOCCEngine
@@ -702,9 +698,11 @@ qubasic_core/
   demos.py               Built-in demo circuits
   protocol.py            TerminalProtocol (mixin contract)
   mock_backend.py        MockAerSimulator for fast testing
+tests/                   Test suites (test_qubasic.py, test_features.py)
+examples/                Sample .qb programs
 ```
 
-`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 16 mixins. `Engine` can be used independently for headless/agent execution.
+`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 20 mixins. Execution methods live on `QBasicTerminal`, so headless/agent use should instantiate `QBasicTerminal` (the `Engine` base is a state container only).
 
 ## License
 

{qubasic-0.5.1 → qubasic-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qubasic"
-version = "0.5.1"
+version = "0.6.1"
 description = "Quantum BASIC Interactive Terminal"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -42,10 +42,9 @@ charts = ["plotille>=5.0"]
 readline = ["pyreadline3>=3.4; sys_platform == 'win32'"]
 
 [project.scripts]
-qubasic = "qubasic:main"
+qubasic = "qubasic_core.cli:main"
 
 [tool.setuptools]
-py-modules = ["qubasic"]
 packages = ["qubasic_core"]
 
 [tool.setuptools.package-data]
@@ -66,9 +65,19 @@ skip_empty = true
 
 [tool.mypy]
 python_version = "3.10"
-warn_return_any = true
+ignore_missing_imports = true
 warn_unused_configs = true
-disallow_untyped_defs = true
-check_untyped_defs = true
 warn_redundant_casts = true
-warn_unused_ignores = true
+# QBasicTerminal composes 20 mixins; each mixin accesses attributes the host
+# class provides, which mypy cannot resolve in isolation. The codebase is
+# intentionally gradually typed, so the strict per-method settings and the
+# cross-mixin attribute check are disabled while keeping mypy useful for real
+# type mismatches, undefined names, and signature checks.
+disallow_untyped_defs = false
+check_untyped_defs = false
+warn_return_any = false
+warn_unused_ignores = false
+# attr-defined: cross-mixin attributes the host class provides.
+# has-type: types behind the lazy __getattr__ re-exports cannot be inferred.
+# misc/union-attr: mixin base-class attribute overlap and optional access.
+disable_error_code = ["attr-defined", "has-type", "misc", "union-attr"]

{qubasic-0.5.1 → qubasic-0.6.1/qubasic.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.5.1
+Version: 0.6.1
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -73,11 +73,12 @@ Requires Python >= 3.10, Qiskit >= 1.0, qiskit-aer >= 0.13.
 ## Usage
 
 ```
-python qubasic.py                  Interactive REPL
-python qubasic.py script.qb        Run a script file
-python qubasic.py --quiet script    Suppress banner, output results only
-python qubasic.py --json script     Machine-readable JSON output
-python qubasic.py --help            Show CLI help
+qubasic                       Interactive REPL (installed console script)
+python -m qubasic_core         Same, without installing
+qubasic script.qb             Run a script file
+qubasic --quiet script         Suppress banner, output results only
+qubasic --json script          Machine-readable JSON output
+qubasic --help                Show CLI help
 ```
 
 Headless (no REPL):
@@ -468,15 +469,9 @@ BLOCH A 0                Bloch sphere for register A, qubit 0
 LOCCINFO                 Protocol metrics
 ```
 
-SPLIT: max capacity (31+31+...), no cross-register entanglement. Use SEND/IF for classical coordination.
+SPLIT: max capacity (up to 33 qubits per register), no cross-register entanglement. Use SEND/IF for classical coordination.
 
-JOINT: shared entanglement via SHARE. Limited to ~32 total qubits.
-
-### Network LOCC
-```
-CONNECT "host:port" AS C   Attach remote register (local simulation stand-in)
-DISCONNECT C               Detach
-```
+JOINT: shared entanglement via SHARE. Limited to 33 total qubits.
 
 ### LOCC optimization
 Programs with SEND execute the deterministic prefix (before first SEND) once, snapshot the statevector, then re-execute only the suffix per shot. Complexity: O(prefix + shots * suffix) instead of O(shots * total).
@@ -691,7 +686,7 @@ Programs with SEND use prefix/suffix splitting: the deterministic prefix (before
 ## JSON output
 
 ```
-python qubasic.py --json examples/bell.qb
+qubasic --json examples/bell.qb
 ```
 
 ```json
@@ -705,8 +700,9 @@ python qubasic.py --json examples/bell.qb
 ## Architecture
 
 ```
-qubasic.py              CLI entry point
 qubasic_core/
+  cli.py                 CLI entry point (qubasic / python -m qubasic_core)
+  __main__.py            Module entry point
   engine_state.py        Engine: standalone state container
   terminal.py            QBasicTerminal: REPL + command dispatch
   engine.py              Constants, gate tables, numpy simulation, LOCCEngine
@@ -735,9 +731,11 @@ qubasic_core/
   demos.py               Built-in demo circuits
   protocol.py            TerminalProtocol (mixin contract)
   mock_backend.py        MockAerSimulator for fast testing
+tests/                   Test suites (test_qubasic.py, test_features.py)
+examples/                Sample .qb programs
 ```
 
-`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 16 mixins. `Engine` can be used independently for headless/agent execution.
+`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 20 mixins. Execution methods live on `QBasicTerminal`, so headless/agent use should instantiate `QBasicTerminal` (the `Engine` base is a state container only).
 
 ## License
 

{qubasic-0.5.1 → qubasic-0.6.1}/qubasic.egg-info/SOURCES.txt

@@ -3,7 +3,6 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
-qubasic.py
 examples/bell.qb
 examples/grover3.qb
 examples/locc_teleport.qb
@@ -19,6 +18,7 @@ qubasic_core/__main__.py
 qubasic_core/analysis.py
 qubasic_core/backend.py
 qubasic_core/classic.py
+qubasic_core/cli.py
 qubasic_core/control_flow.py
 qubasic_core/debug.py
 qubasic_core/demos.py
@@ -54,4 +54,6 @@ qubasic_core/statements.py
 qubasic_core/strings.py
 qubasic_core/subs.py
 qubasic_core/sweep.py
-qubasic_core/terminal.py
+qubasic_core/terminal.py
+tests/test_features.py
+tests/test_qubasic.py

qubasic-0.6.1/qubasic.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qubasic = qubasic_core.cli:main

{qubasic-0.5.1 → qubasic-0.6.1}/qubasic.egg-info/top_level.txt

@@ -1,2 +1 @@
-qubasic
 qubasic_core

{qubasic-0.5.1 → qubasic-0.6.1}/qubasic_core/__init__.py

@@ -28,7 +28,7 @@ __all__ = [
     'GATE_TABLE', 'GATE_ALIASES',
 ]
 
-__version__ = '0.5.1'
+__version__ = '0.6.1'
 
 def __getattr__(name):
     """Lazy import heavy modules on first access."""

qubasic-0.6.1/qubasic_core/__main__.py

@@ -0,0 +1,6 @@
+"""Run the CLI as a module: python -m qubasic_core [args]."""
+
+from qubasic_core.cli import main
+
+if __name__ == '__main__':
+    main()

{qubasic-0.5.1 → qubasic-0.6.1}/qubasic_core/analysis.py

@@ -22,24 +22,48 @@ class AnalysisMixin:
     self.locc, self.locc_mode.
     """
 
+    def _resolve_analysis_target(self, rest: str):
+        """Return (sv, n_qubits, remaining_rest) for a state-analysis command.
+
+        In LOCC SPLIT mode a leading register letter selects that register
+        (e.g. ``EXPECT A Z 0``); otherwise the active statevector is used.
+        """
+        parts = rest.split()
+        if self.locc_mode and self.locc and not self.locc.joint and parts:
+            cand = parts[0].upper()
+            if cand in self.locc.names:
+                sv, n = self._active_sv_for_reg(cand)
+                return sv, n, ' '.join(parts[1:])
+        return self._active_sv, self._active_nqubits, rest
+
     def cmd_expect(self, rest: str) -> None:
-        """EXPECT <pauli> [qubits] — compute expectation value.
-        Examples: EXPECT Z 0, EXPECT ZZ 0 1, EXPECT X 0"""
-        sv = self._active_sv
+        """EXPECT [reg] <pauli> [qubits] — compute expectation value.
+        Examples: EXPECT Z 0, EXPECT ZZ 0 1, EXPECT A Z 0 (SPLIT register A)"""
+        sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
             if self.locc_mode and self.locc and not self.locc.joint:
-                self.io.writeln("?SPLIT mode: use STATE A / STATE B for per-register inspection")
+                self.io.writeln("?SPLIT mode: prefix a register, e.g. EXPECT A Z 0")
             else:
                 self.io.writeln("?NO STATE — RUN first")
             return
         parts = rest.split()
         if not parts:
-            self.io.writeln("?USAGE: EXPECT <Z|X|Y|ZZ|...> [qubits]")
+            self.io.writeln("?USAGE: EXPECT [reg] <Z|X|Y|ZZ|...> [qubits]")
             return
         pauli_str = parts[0].upper()
         qubits = [int(q) for q in parts[1:]] if len(parts) > 1 else list(range(len(pauli_str)))
-
-        n = self._active_nqubits
+        # Fast numpy path for diagonal (Z/I-only) observables — no qiskit copy.
+        if set(pauli_str) <= {'Z', 'I'}:
+            svf = np.ascontiguousarray(sv).ravel()
+            probs = np.abs(svf) ** 2
+            idx = np.arange(svf.size)
+            sign = np.ones(svf.size)
+            for i, p in enumerate(pauli_str):
+                if p == 'Z' and i < len(qubits):
+                    sign = sign * np.where(((idx >> qubits[i]) & 1) == 1, -1.0, 1.0)
+            val = float(np.sum(probs * sign))
+            self.io.writeln(f"  <{pauli_str}> on qubits {qubits} = {val:.6f}")
+            return
         try:
             from qiskit.quantum_info import Statevector, SparsePauliOp
             sv_q = Statevector(np.ascontiguousarray(sv).ravel())
@@ -54,17 +78,19 @@ class AnalysisMixin:
             self.io.writeln(f"?EXPECT ERROR: {e}")
 
     def cmd_entropy(self, rest: str = '') -> None:
-        """ENTROPY [qubits] — entanglement entropy of specified qubits vs rest.
-        Examples: ENTROPY 0  |  ENTROPY 0 1  |  ENTROPY (defaults to qubit 0)"""
-        sv = self._active_sv
+        """ENTROPY [reg] [qubits] — entanglement entropy of qubits vs rest.
+        Examples: ENTROPY 0 | ENTROPY 0 1 | ENTROPY A 0 (SPLIT register A)"""
+        sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
-            self.io.writeln("?NO STATE — RUN first")
+            if self.locc_mode and self.locc and not self.locc.joint:
+                self.io.writeln("?SPLIT mode: prefix a register, e.g. ENTROPY A 0")
+            else:
+                self.io.writeln("?NO STATE — RUN first")
             return
         if rest.strip():
             partition_a = [int(q) for q in rest.replace(',', ' ').split() if q.strip()]
         else:
             partition_a = [0]
-        n = self._active_nqubits
         try:
             from qiskit.quantum_info import Statevector, entropy, partial_trace
             sv_obj = Statevector(np.ascontiguousarray(sv).ravel())
@@ -81,25 +107,27 @@ class AnalysisMixin:
         except Exception as e:
             self.io.writeln(f"?ENTROPY ERROR: {e}")
 
-    def cmd_density(self) -> None:
-        """Show density matrix (or partial trace for small systems)."""
-        sv = self._active_sv
+    def cmd_density(self, rest: str = '') -> None:
+        """Show density matrix (DENSITY [reg]); summarizes for large systems."""
+        sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
-            self.io.writeln("?NO STATE — RUN first")
+            if self.locc_mode and self.locc and not self.locc.joint:
+                self.io.writeln("?SPLIT mode: prefix a register, e.g. DENSITY A")
+            else:
+                self.io.writeln("?NO STATE — RUN first")
             return
         sv = np.ascontiguousarray(sv).ravel()
-        rho = np.outer(sv, sv.conj())
-        n = self._active_nqubits
         dim = 2**n
         if dim > 16:
+            # |psi><psi| is rank-1, so purity is ||psi||^4 and the von Neumann
+            # entropy is 0; report directly instead of building a 2^n x 2^n matrix.
+            norm2 = float(np.vdot(sv, sv).real)
             self.io.writeln(f"  Density matrix: {dim}x{dim} (too large to display)")
-            self.io.writeln(f"  Purity: {np.real(np.trace(rho @ rho)):.6f}")
-            self.io.write(f"  Von Neumann entropy: ")
-            eigvals = np.linalg.eigvalsh(rho)
-            eigvals = eigvals[eigvals > 1e-15]
-            ent = -np.sum(eigvals * np.log2(eigvals))
-            self.io.writeln(f"{ent:.6f} bits")
+            self.io.writeln(f"  Pure state |psi><psi|: purity {norm2 ** 2:.6f}")
+            self.io.writeln(f"  Von Neumann entropy: 0.000000 bits")
+            self.io.writeln(f"  (use ENTROPY <qubits> for reduced-state entanglement)")
             return
+        rho = np.outer(sv, sv.conj())
         self.io.writeln(f"\n  Density matrix ({dim}x{dim}):\n")
         for i in range(dim):
             row = []
@@ -154,7 +182,7 @@ class AnalysisMixin:
             return
         n = self._active_nqubits
         sv = np.ascontiguousarray(sv).ravel()
-        checks = []
+        checks: list = []
 
         # 1. SV normalization
         norm = float(np.sum(np.abs(sv)**2))

qubasic-0.5.1/qubasic.py → qubasic-0.6.1/qubasic_core/cli.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 """
-QUBASIC — Quantum BASIC Interactive Terminal
+QUBASIC — command-line entry point.
 
 Usage:
-    python qubasic.py             Interactive REPL
-    python qubasic.py script.qb   Run a script file
+    qubasic                       Interactive REPL (installed console script)
+    python -m qubasic_core        Same, run as a module
+    qubasic script.qb             Run a script file
 """
 
 import sys
@@ -50,14 +51,15 @@ def main():
     import json as _json
     os.environ.setdefault('PYTHONIOENCODING', 'utf-8')
 
+    from qubasic_core import __version__
+
     args = sys.argv[1:]
     quiet = '--quiet' in args or '-q' in args
     json_mode = '--json' in args
+    agent_mode = '--agent' in args
     seed_val = None
-    if quiet:
-        args = [a for a in args if a not in ('--quiet', '-q')]
-    if json_mode:
-        args = [a for a in args if a != '--json']
+    for flag in ('--quiet', '-q', '--json', '--agent'):
+        args = [a for a in args if a != flag]
     # Parse --seed N
     filtered = []
     i = 0
@@ -70,8 +72,11 @@ def main():
             i += 1
     args = filtered
 
+    if any(a in ('-v', '--version') for a in args):
+        print(f"QUBASIC {__version__}")
+        sys.exit(0)
+
     if any(a in ('-h', '--help') for a in args):
-        from qubasic_core import __version__
         print(f"QUBASIC {__version__} — Quantum BASIC Interactive Terminal")
         print()
         print("Usage:")
@@ -79,13 +84,17 @@ def main():
         print("  qubasic script.qb        Run a script file")
         print("  qubasic --quiet script    Suppress banner and progress")
         print("  qubasic --json script     Output results as JSON")
+        print("  qubasic --agent script    Confine file writes to the working dir")
         print("  qubasic --seed N script   Set random seed for reproducibility")
+        print("  qubasic --version         Show version")
         print("  qubasic --help            Show this help")
         print()
         print("Type HELP inside the REPL for full command reference.")
         sys.exit(0)
 
     term = QBasicTerminal()
+    # JSON mode implies agent use, so confine file writes to the working dir.
+    term.agent_mode = agent_mode or json_mode
     if seed_val is not None:
         import numpy as _np
         term._seed = seed_val
@@ -93,35 +102,41 @@ def main():
 
     if args:
         path = args[0]
-        if os.path.isfile(path):
-            if quiet or json_mode:
-                import io
-                buf = io.StringIO()
-                old = sys.stdout
-                sys.stdout = buf
-                try:
-                    run_script(path, term)
-                finally:
-                    sys.stdout = old
-                if json_mode:
-                    result = {
-                        'counts': term.last_counts or {},
-                        'num_qubits': term.num_qubits,
-                        'shots': term.shots,
-                    }
-                    print(_json.dumps(result, indent=2))
-                elif not quiet:
-                    print(buf.getvalue())
+        if not os.path.isfile(path):
+            if json_mode:
+                print(_json.dumps({'error': f'FILE NOT FOUND: {path}'}, indent=2))
             else:
-                term.print_banner()
+                print(f"?FILE NOT FOUND: {path}")
+            sys.exit(1)
+        if quiet or json_mode:
+            import io
+            buf = io.StringIO()
+            old = sys.stdout
+            sys.stdout = buf
+            err = None
+            try:
                 run_script(path, term)
-            # Exit code: 0 if results exist, 1 if error
-            sys.exit(0 if term.last_counts is not None or not any(
-                term.program.get(ln, '').strip().upper() == 'MEASURE'
-                for ln in term.program) else 1)
+            except Exception as e:  # surface as structured error in JSON mode
+                err = str(e)
+            finally:
+                sys.stdout = old
+            if json_mode:
+                if err is not None:
+                    print(_json.dumps({'error': err}, indent=2))
+                    sys.exit(1)
+                print(_json.dumps(term.result(), indent=2))
+            elif not quiet:
+                print(buf.getvalue())
+                if err is not None:
+                    print(f"?ERROR: {err}")
+                    sys.exit(1)
         else:
-            print(f"?FILE NOT FOUND: {path}")
-            sys.exit(1)
+            term.print_banner()
+            run_script(path, term)
+        # Exit 0 on success; 1 if a measured program produced no counts.
+        sys.exit(0 if term.last_counts is not None or not any(
+            term.program.get(ln, '').strip().upper() == 'MEASURE'
+            for ln in term.program) else 1)
     else:
         term.repl()