superqode 2.5.4__tar.gz → 2.5.5__tar.gz

{superqode-2.5.4 → superqode-2.5.5}/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.5] - 2026-10-04
+
+### Added
+
+- Open `:work view ID` for live task dependencies, assigned predecessor evidence,
+  recovery outcomes, acceptance output and candidate review in the TUI.
+- Run existing WorkOrder actions without leaving the inspector. An explicit
+  Interrupt control stops its own worker process; stale leases and unknown
+  outcomes still require recovery and, when necessary, reconciliation.
+- Open `:context evidence` to inspect native Core/hosted PiPy decisions,
+  proposed excerpts, bounded originals and persisted cache reuse after a new step.
+- Add a small real coding WorkOrder demo with an investigator dependency and
+  deterministic acceptance test. Setup is offline; Execute uses the chosen
+  provider. Recovery requires the explicit `--recovery` flag.
+
+### Hardened
+
+- Record reuse admissions only after invocation identity, current ownership,
+  configuration and workspace checks. Recovery views exclude private outcomes.
+- Require a complete, integrity-checked candidate preview and a human reason
+  for TUI approval. Atomically check both candidate identity and digest to reject
+  approval races, including replacement candidates with identical patch bytes.
+- Recheck current permissions on each evidence page. Bound previews, preserve
+  keyboard focus and draft text, and support 80-column terminal layouts.
+- Gate releases on mounted TUI workflows and real PiPy process interruption,
+  restart and committed-call reuse tests with deterministic model responses.
+
+### Notes
+
+- Recovery, evidence reuse and context/Jev selection remain opt-in. Context
+  selection defaults to `off`; shadow mode preserves baseline output. No model
+  routing, price optimization or external harness context-parity claim is added.
+- Live Pi/Jev coding-quality comparisons and net-benefit measurements remain
+  outstanding. These changes expose and harden the existing execution contracts.
+
 ## [2.5.4] - 2026-10-03
 
 ### Fixed

{superqode-2.5.4 → superqode-2.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.5.4
+Version: 2.5.5
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

superqode-2.5.5/examples/workorders/tui_demo.py

@@ -0,0 +1,154 @@
+"""Prepare a real, small coding WorkOrder for the TUI; make no model calls."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+from superqode.harness.loader import load_harness_spec
+from superqode.workorders import (
+    WorkOrder,
+    WorkOrderBudget,
+    WorkOrderStore,
+    WorkOrderTask,
+    WorkTaskRole,
+)
+
+
+def prepare(directory: Path, *, provider: str, model: str, recovery=False):
+    directory = directory.expanduser().resolve()
+    directory.mkdir(parents=True, exist_ok=False)
+    (directory / "answer.py").write_text("def answer():\n    return 41\n")
+    (directory / "test_answer.py").write_text(
+        "import unittest\nfrom answer import answer\n\n"
+        "class AnswerTest(unittest.TestCase):\n"
+        "    def test_answer(self):\n        self.assertEqual(answer(), 42)\n"
+    )
+    (directory / "AGENTS.md").write_text(
+        "Keep the change minimal. Never modify test_answer.py. Run the acceptance test.\n"
+    )
+    (directory / ".gitignore").write_text(".superqode/\n__pycache__/\n")
+    subprocess.run(["git", "init", "-q", str(directory)], check=True)
+    subprocess.run(["git", "-C", str(directory), "add", "."], check=True)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(directory),
+            "-c",
+            "user.name=SuperQode Demo",
+            "-c",
+            "user.email=demo@example.invalid",
+            "commit",
+            "-qm",
+            "Failing answer acceptance test",
+        ],
+        check=True,
+    )
+    control = directory / ".superqode"
+    control.mkdir()
+    harness = {
+        "version": 1,
+        "name": "tui-demo-pipy",
+        "flavor": "coding",
+        "runtime": {
+            "backend": "pipy",
+            "config": {"recovery": {"enabled": recovery}, "mcp_config": False},
+        },
+        "model_policy": {"primary": model, "config": {"provider": provider}},
+        "execution_policy": {
+            "sandbox": "none",
+            "allow_read": True,
+            "allow_write": True,
+            "allow_shell": True,
+            "allow_network": False,
+        },
+        "agents": [
+            {
+                "id": "coder",
+                "role": "implementation",
+                "system_prompt": "Inspect the assigned task, make only requested changes, and finish with concise evidence.",
+            }
+        ],
+    }
+    harness_path = control / "demo-pipy.yaml"
+    harness_path.write_text(yaml.safe_dump(harness, sort_keys=False))
+    load_harness_spec(harness_path)
+    investigate = control / "demo-investigate.yaml"
+    harness["name"] = "tui-demo-investigate"
+    harness["execution_policy"]["allow_write"] = False
+    investigate.write_text(yaml.safe_dump(harness, sort_keys=False))
+    load_harness_spec(investigate)
+    store = WorkOrderStore(control / "workorders" / "store.sqlite3")
+    acceptance = f"{shlex.quote(sys.executable)} -m unittest -v"
+    store.create(
+        WorkOrder(
+            "tui-demo",
+            "Fix answer() to satisfy the unchanged acceptance test",
+            str(directory),
+            acceptance_tests=(acceptance,),
+            harness=str(harness_path),
+            budget=WorkOrderBudget(max_seconds=900, max_workers=1, max_tool_calls=20),
+            metadata={"evidence_reuse": True},
+            tasks=(
+                WorkOrderTask(
+                    "investigate",
+                    "Investigate the failing answer",
+                    "Read answer.py and test_answer.py, run the acceptance test, report the cause and smallest fix. Do not edit files.",
+                    role=WorkTaskRole.INVESTIGATOR,
+                    harness=str(investigate),
+                    provider=provider,
+                    model=model,
+                    max_attempts=4,
+                ),
+                WorkOrderTask(
+                    "implement",
+                    "Implement and verify the fix",
+                    "Retrieve assigned investigator evidence. Fix answer.py only, keep test_answer.py unchanged, run the acceptance test and report its outcome.",
+                    dependencies=("investigate",),
+                    harness=str(harness_path),
+                    provider=provider,
+                    model=model,
+                    max_attempts=4,
+                ),
+            ),
+        )
+    )
+    store.queue("tui-demo")
+    return directory
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "directory", type=Path, help="New directory; existing directories are refused"
+    )
+    parser.add_argument("--provider", required=True)
+    parser.add_argument("--model", required=True)
+    parser.add_argument(
+        "--recovery",
+        action="store_true",
+        help="Explicitly enable experimental PiPy process recovery",
+    )
+    args = parser.parse_args()
+    root = prepare(args.directory, provider=args.provider, model=args.model, recovery=args.recovery)
+    print(
+        f"Prepared {root}; no model calls made. Recovery: {'enabled' if args.recovery else 'off'}."
+    )
+    print(f"cd {shlex.quote(str(root))}\nsq\n:work view tui-demo --lease 10")
+    print("Select Run ready tasks, then Execute. Inspect Evidence and Recovery while it runs.")
+    print(
+        "After completion: Acceptance checks, Prepare candidate, Review / Open, then Approve with your reason."
+    )
+    print(
+        "Workers use the selected provider and may incur cost. This demo uses process permissions; it does not configure an OS sandbox."
+    )
+
+
+if __name__ == "__main__":
+    main()

{superqode-2.5.4 → superqode-2.5.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.5.4"
+version = "2.5.5"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.5.4"
+__version__ = "2.5.5"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/app/constants.py

@@ -521,6 +521,8 @@ COMMANDS = [
     ":connect protocols",
     ":context",
     ":context next",
+    ":context evidence",
+    ":work view",
     ":chat",
     ":chat off",
     ":chat clear",

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/app/mixins/commands_impl.py

@@ -1466,6 +1466,153 @@ class CommandImplMixin:
             return
         self.run_worker(self._superqode_cli_cmd(["skillopt", *tokens], log, "SkillOpt command"))
 
+    def _open_work_inspector(self, args, log):
+        from superqode.commands.work import DEFAULT_WORK_STORE
+        from superqode.widgets.workorder_inspector import WorkOrderInspector, parse_inspector_args
+
+        try:
+            parsed = parse_inspector_args(args, DEFAULT_WORK_STORE)
+        except ValueError as exc:
+            log.add_error(str(exc))
+            return True
+        if parsed is None:
+            return False
+        path, reference, lease = parsed
+        if not path.is_file():
+            log.add_error("WorkOrder store does not exist. Create a WorkOrder first.")
+            return True
+
+        def running():
+            process = getattr(self, "_work_inspector_processes", {}).get((str(path), reference))
+            return process is not None and process.returncode is None
+
+        def dispatch(parts):
+            self.run_worker(self._work_inspector_action(parts, path, reference, log))
+
+        self.push_screen(
+            WorkOrderInspector(
+                path, reference, on_action=dispatch, worker_running=running, lease_seconds=lease
+            ),
+            callback=lambda _: self._ensure_input_focus(),
+        )
+        return True
+
+    async def _work_inspector_action(self, parts, path, reference, log):
+        import os
+        import signal
+        import sys
+        import tempfile
+
+        processes = getattr(self, "_work_inspector_processes", None)
+        if processes is None:
+            processes = self._work_inspector_processes = {}
+        key = (str(path), reference)
+        process = processes.get(key)
+        if parts == ["interrupt"]:
+            if process is not None and process.returncode is None:
+                try:
+                    if os.name == "posix":
+                        os.killpg(process.pid, signal.SIGKILL)
+                    else:
+                        process.kill()
+                    log.add_info(
+                        "WorkOrder worker interrupted. Recover only after its lease becomes stale; reconcile unknown outcomes explicitly."
+                    )
+                except ProcessLookupError:
+                    pass
+            return
+        if process is not None and process.returncode is None:
+            log.add_info(
+                "A WorkOrder action is already running. Inspect progress or interrupt it first."
+            )
+            return
+        # Reserve before awaiting spawn so repeated clicks cannot start two actions.
+        processes[key] = None
+        pending = getattr(self, "_work_inspector_pending", set())
+        self._work_inspector_pending = pending
+        if key in pending:
+            return
+        pending.add(key)
+        try:
+            log.add_info("Starting WorkOrder action: " + " ".join(shlex.quote(p) for p in parts))
+            with tempfile.TemporaryFile() as output_file:
+                process = await asyncio.create_subprocess_exec(
+                    sys.executable,
+                    "-m",
+                    "superqode.main",
+                    *parts,
+                    cwd=Path.cwd(),
+                    stdout=output_file,
+                    stderr=asyncio.subprocess.STDOUT,
+                    start_new_session=os.name == "posix",
+                )
+                processes[key] = process
+                await process.wait()
+                output_file.seek(0, os.SEEK_END)
+                output_file.seek(max(0, output_file.tell() - 16000))
+                output = output_file.read(16000)
+            if process.returncode == 0:
+                log.add_success("WorkOrder action completed.")
+            else:
+                log.add_error(f"WorkOrder action stopped with exit code {process.returncode}.")
+            if output:
+                log.write(Text(output.decode(errors="replace")[-16000:], overflow="fold"))
+        except asyncio.CancelledError:
+            if process is not None and process.returncode is None:
+                try:
+                    if os.name == "posix":
+                        os.killpg(process.pid, signal.SIGKILL)
+                    else:
+                        process.kill()
+                except ProcessLookupError:
+                    pass
+                await process.wait()
+            raise
+        except Exception as exc:
+            log.add_error(f"WorkOrder action failed: {exc}")
+        finally:
+            pending.discard(key)
+            processes.pop(key, None)
+            from superqode.widgets.workorder_inspector import WorkOrderInspector
+
+            screen = self.screen if self.screen_stack else None
+            if (
+                self.is_running
+                and isinstance(screen, WorkOrderInspector)
+                and screen.path == path
+                and screen.reference == reference
+            ):
+                await screen.reload()
+                screen._notice(
+                    "Action completed. Inspect state and acceptance results before the next action."
+                    if process is not None and process.returncode == 0
+                    else "Action stopped or failed. Inspect task errors; Back opens the transcript with command output."
+                )
+
+    def _open_context_evidence(self, log):
+        from superqode.widgets.context_evidence import ContextEvidenceScreen
+
+        pure = getattr(self, "_pure_mode", None)
+        agent = self._active_agent_loop()
+        spec = getattr(pure, "_harness_spec", None)
+        native_pipy = spec is not None and spec.runtime.backend == "pipy"
+        trace = getattr(pure if native_pipy else agent, "last_context_selection", None)
+        if not trace or not trace.get("artifact_store_path"):
+            log.add_info(
+                "No native context decisions yet. Enable context selection explicitly, run a step, then use :context evidence."
+            )
+            return
+        root = getattr(getattr(pure, "session", None), "working_directory", Path.cwd())
+        manager = (
+            pure._permission_manager_for_runtime()
+            if native_pipy
+            else getattr(agent, "permission_manager", None)
+        )
+        self.push_screen(
+            ContextEvidenceScreen(trace, Path(root), permission_manager=manager),
+            callback=lambda _: self._ensure_input_focus(),
+        )
+
     async def _superqode_cli_cmd(
         self,
         command_parts: list[str],

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/app/mixins/slash_commands.py

@@ -526,7 +526,9 @@ class SlashCommandMixin:
         elif c == "optimize":
             self._jev_optimize_cmd(args, log)
         elif c == "context":
-            if args.strip().lower() == "next":
+            if args.strip().lower() == "evidence":
+                self._open_context_evidence(log)
+            elif args.strip().lower() == "next":
                 self._preview_next_context(log)
             else:
                 self._show_context(log)
@@ -543,7 +545,8 @@ class SlashCommandMixin:
         elif c in ("session", "sessions-current"):
             self._session_cmd(args, log)
         elif c == "work" and args.strip():
-            self._run_cli_group("work", args, log, "WorkOrder")
+            if not self._open_work_inspector(args, log):
+                self._run_cli_group("work", args, log, "WorkOrder")
         elif c in ("work", "summary"):
             self._work_cmd(args, log)
         elif c == "files":

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/commands/work.py

@@ -1204,6 +1204,8 @@ def work_diff(ctx: click.Context, work_order_id: str, json_output: bool) -> None
 @click.argument("work_order_id")
 @click.option("--actor", default="human", show_default=True)
 @click.option("--reason", default="")
+@click.option("--candidate-digest", default="", help="Require the exact inspected candidate digest")
+@click.option("--candidate-id", default="", help="Require the exact inspected candidate artifact")
 @click.option("--json", "json_output", is_flag=True, help="Emit JSON")
 @click.pass_context
 def work_approve(
@@ -1211,11 +1213,19 @@ def work_approve(
     work_order_id: str,
     actor: str,
     reason: str,
+    candidate_digest: str,
+    candidate_id: str,
     json_output: bool,
 ) -> None:
     """Approve completed work or the exact prepared merge candidate."""
     try:
-        order = _store(ctx).accept(work_order_id, actor=actor, reason=reason)
+        order = _store(ctx).accept(
+            work_order_id,
+            actor=actor,
+            reason=reason,
+            expected_candidate_digest=candidate_digest,
+            expected_candidate_id=candidate_id,
+        )
     except Exception as exc:
         raise click.ClickException(str(exc)) from exc
     _emit_order(order, json_output=json_output)

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/harness/context_policy.py

@@ -156,6 +156,8 @@ class ContextPolicyEngine:
             "spend_usd": 0 if p.selector == "rules" else None,
             "size_provenance": "character count",
             "decisions": [],
+            "artifact_scope": self.scope,
+            "artifact_store_path": str(self.store.path.resolve()),
         }
         candidates = []
         tail = max(0, len(items) - p.recent_messages)
@@ -344,7 +346,19 @@ class ContextPolicyEngine:
         trace.update(
             proposed_chars_after=after,
             chars_after=after if p.mode == "enforce" else before,
-            decisions=[asdict(d) for d in decisions],
+            decisions=[
+                {
+                    **asdict(d),
+                    **(
+                        {"excerpt": reference_excerpt(c)}
+                        if d.action == "excerpt_with_reference"
+                        else {}
+                    ),
+                }
+                for d in decisions
+                for c in candidates
+                if d.reference == c.reference
+            ],
         )
         return self._finish(decisions, proposed if p.mode == "enforce" else {}, trace)
 

{superqode-2.5.4 → superqode-2.5.5}/src/superqode/pure_mode.py

@@ -104,6 +104,7 @@ class PureMode:
         self._runtime_tool_delta_buffers: dict[str, dict[str, Any]] = {}
         self._runtime_seen_tool_calls: set = set()
         self._last_stats: dict[str, int | float] = {}
+        self.last_context_selection = None
         self._last_resume_descriptor = None
         self._cancel_requested = False
 
@@ -143,6 +144,7 @@ class PureMode:
         self._harness_kernel = None
         self._harness_session = None
         self._harness_session_id = ""
+        self.last_context_selection = None
         self._dispose_runtime()
         self._sync_harness_session_fields()
         return definition
@@ -172,6 +174,7 @@ class PureMode:
         self._harness_kernel = None
         self._harness_session = None
         self._harness_session_id = ""
+        self.last_context_selection = None
         self._sync_harness_session_fields()
 
     def connect_decision(self, pack: str = "factory_route", *, spec=None) -> None:
@@ -523,6 +526,7 @@ class PureMode:
         self._harness_kernel = None
         self._harness_session = None
         self._harness_session_id = ""
+        self.last_context_selection = None
         self._sync_harness_session_fields()
 
     def _permission_manager_for_runtime(self):
@@ -722,7 +726,7 @@ class PureMode:
                 ):
                     if self._cancel_requested:
                         break
-                    if rich_events or event.type == "systemone.decision":
+                    if rich_events or event.type in {"systemone.decision", "context.selection"}:
                         chunk = self._handle_runtime_harness_event(event)
                     elif event.type in {"delta", "model_delta"}:
                         chunk = str(event.data.get("text", ""))
@@ -791,6 +795,10 @@ class PureMode:
 
     def _handle_runtime_harness_event(self, event) -> str:
         """Forward runtime harness events into PureMode callbacks."""
+        if event.type == "context.selection":
+            if self._harness_spec is not None and self._harness_spec.runtime.backend == "pipy":
+                self.last_context_selection = dict(event.data)
+            return ""
         if event.type == "systemone.decision":
             if self.on_systemone:
                 self.on_systemone(event.data)