regent-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{regent_cli-0.4.0 → regent_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regent-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project.
 Author-email: Flavio Alvim <flavioalvim@gmail.com>
 License: MIT
@@ -48,7 +48,12 @@ the JSON subcommands — `regent status` (control + lock + the executable contro
 matrix as `workspace.verdict`), `regent activity
 start|resume|suspend|conclude|heartbeat|takeover`, `regent stop request|check`. Hosts
 seeded by older versions upgrade automatically on `regent init` (known-version manifest;
-unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI.
+unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI. Conduction
+phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
+--prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
+REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
+`regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
+provenance check, process-group-killing timeout, integral output preserved).
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.4.0 → regent_cli-0.5.0}/README.md

@@ -32,7 +32,12 @@ the JSON subcommands — `regent status` (control + lock + the executable contro
 matrix as `workspace.verdict`), `regent activity
 start|resume|suspend|conclude|heartbeat|takeover`, `regent stop request|check`. Hosts
 seeded by older versions upgrade automatically on `regent init` (known-version manifest;
-unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI.
+unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI. Conduction
+phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
+--prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
+REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
+`regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
+provenance check, process-group-killing timeout, integral output preserved).
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.4.0 → regent_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "regent-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project."
 readme = "README.md"
 requires-python = ">=3.10"

{regent_cli-0.4.0 → regent_cli-0.5.0}/src/regent/__init__.py

@@ -1,3 +1,3 @@
 """regent — autonomous conduction and mediated adversarial deliberation between AI agents."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{regent_cli-0.4.0 → regent_cli-0.5.0}/src/regent/activity_cli.py

@@ -24,6 +24,7 @@ _EXIT_BY_CODE = {
     "NOT_SUSPENDED": 2, "ACTIVITY_OPEN": 2,
     "TOKEN_MISMATCH": 3, "LOCK_HELD": 3, "LOCK_SUSPECT": 3, "BUSY": 3,
     "CONFLICT": 3, "UNATTRIBUTABLE": 3, "CORRUPT_CONTROL": 4, "IO": 5,
+    "ADVISOR_FAILED": 3, "ADVISOR_UNAVAILABLE": 2, "GATE_RED": 3, "PROVENANCE": 3,
 }
 
 
@@ -91,6 +92,26 @@ def build_parser(sub) -> None:
     p.add_argument("--reason", default=None)
     stop_sub.add_parser("check")
 
+    p_advisor = sub.add_parser("advisor", help="mechanized advisor consultation")
+    p_advisor.add_argument("--project", default=None)
+    advisor_sub = p_advisor.add_subparsers(dest="advisor_command", required=True)
+    p = advisor_sub.add_parser("consult")
+    p.add_argument("--prompt-file", required=True, dest="prompt_file")
+    p.add_argument("--artifact", required=True)
+    p.add_argument("--linkage", required=True)
+    p.add_argument("--timeout", type=float, default=600.0)
+    p.add_argument("--expect-verdict", default=None, dest="expect_verdict")
+
+    p_gate = sub.add_parser("gate", help="mechanized gate execution")
+    p_gate.add_argument("--project", default=None)
+    gate_sub = p_gate.add_subparsers(dest="gate_command", required=True)
+    p = gate_sub.add_parser("run")
+    p.add_argument("--command", required=True, dest="gate_cmd")
+    p.add_argument("--declared-in", required=True, dest="declared_in")
+    p.add_argument("--artifact", required=True)
+    p.add_argument("--linkage", required=True)
+    p.add_argument("--timeout", type=float, default=1800.0)
+
     p_control = sub.add_parser("control",
                                help="control.json attributability helpers")
     p_control.add_argument("--project", default=None)
@@ -120,6 +141,42 @@ def run(args, out=None) -> int:
         if args.command == "control":
             return _run_control_explain(service, root, out,
                                         since_version=args.since_version)
+        if args.command == "advisor":
+            from .conduction.consult import AdvisorUnavailable, run_consult
+            from .conduction.evidence import EvidenceConflict
+            try:
+                result = run_consult(root, prompt_file=Path(args.prompt_file),
+                                     artifact=Path(args.artifact),
+                                     linkage=args.linkage, timeout=args.timeout,
+                                     expect_verdict=args.expect_verdict)
+            except AdvisorUnavailable as exc:
+                return _fail("ADVISOR_UNAVAILABLE", {"reason": str(exc)}, out)
+            except EvidenceConflict as exc:
+                return _fail("CONFLICT", {"paths": exc.paths}, out)
+            if not result["ok"]:
+                return _fail("ADVISOR_FAILED",
+                             {"outcome": result["outcome"],
+                              "exit_code": result["exit_code"],
+                              "verdict": result["verdict"],
+                              "artifact": result["artifact"]}, out)
+            return _emit(result, 0, out)
+        if args.command == "gate":
+            from .conduction.gate import ProvenanceError, run_gate
+            from .conduction.evidence import EvidenceConflict
+            try:
+                result = run_gate(root, command=args.gate_cmd,
+                                  declared_in=Path(args.declared_in),
+                                  artifact=Path(args.artifact),
+                                  linkage=args.linkage, timeout=args.timeout)
+            except ProvenanceError as exc:
+                return _fail("PROVENANCE", {"reason": str(exc)}, out)
+            except EvidenceConflict as exc:
+                return _fail("CONFLICT", {"paths": exc.paths}, out)
+            if not result["ok"]:
+                return _fail("GATE_RED", {"outcome": result["outcome"],
+                                          "exit_code": result["exit_code"],
+                                          "artifact": result["artifact"]}, out)
+            return _emit(result, 0, out)
         return _fail("USAGE", f"unknown command {args.command!r}", out)
     except ActivityError as exc:
         return _fail(exc.code, exc.detail, out)

regent_cli-0.5.0/src/regent/conduction/__init__.py

@@ -0,0 +1,7 @@
+"""regent.conduction — conduction phase 1 (PLAN-003): mechanized advisor
+consultations and gate runs with automated, fail-closed evidence."""
+
+from .consult import run_consult
+from .gate import run_gate
+
+__all__ = ["run_consult", "run_gate"]

regent_cli-0.5.0/src/regent/conduction/consult.py

@@ -0,0 +1,98 @@
+"""`regent advisor consult` — mechanized advisor consultation (PLAN-003).
+
+Ports the IMP-003-proven CodexConsultAdapter: read-only sandboxed `codex exec`
+with the REQ-003 §5 evidence tuple generated BY THE COMMAND, not by executor
+discipline. Sandbox flags are mandatory and not configurable. Every terminal
+outcome (SUCCESS/TIMEOUT/FAILURE) leaves the evidence pair complete.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from .evidence import EvidenceSet, header
+from .process import SubprocessRunner
+
+DEFAULT_VERDICT_RE = (r"^(CONCORDA|DISCORDA.*|APROVADO( COM RESSALVAS)?|"
+                      r"REPROVADO|QUITADAS|PENDENTES.*)$")
+
+
+class AdvisorUnavailable(Exception):
+    pass
+
+
+def run_consult(root: Path, *, prompt_file: Path, artifact: Path, linkage: str,
+                timeout: float = 600.0, expect_verdict: str | None = None,
+                runner=None, codex_bin: str = "codex") -> dict:
+    root = Path(root)
+    prompt_bytes = Path(prompt_file).read_bytes()  # byte-faithful (no newline
+    # translation — read_text would normalize CRLF)
+    prompt_text = prompt_bytes.decode("utf-8", errors="replace")
+    evidence = EvidenceSet(Path(artifact),
+                           {"prompt": Path(str(artifact) + "-PROMPT.md")})
+    evidence.precheck()
+
+    if runner is None:
+        if shutil.which(codex_bin) is None:
+            raise AdvisorUnavailable(f"'{codex_bin}' not found on PATH")
+        runner = SubprocessRunner()
+
+    # ONE cleanup guard around the WHOLE operation (sibling publish, temp
+    # file, execution and the main publish): any exception — OSError,
+    # EvidenceConflict from a no-clobber race on the main artifact, anything —
+    # removes the already-published siblings. Only a completed write_main
+    # (terminal outcome) leaves the pair behind.
+    try:
+        evidence.write_sibling("prompt", prompt_bytes)  # byte-identical copy
+        fd, msg_file = tempfile.mkstemp(prefix="regent-consult-", suffix=".txt")
+        os.close(fd)
+        try:
+            argv = [codex_bin, "--ask-for-approval", "never",
+                    "--sandbox", "read-only",  # MANDATORY, not configurable
+                    "exec", "--cd", str(root), "-o", msg_file, prompt_text]
+            result = runner.run(argv, cwd=str(root), timeout=timeout)
+            try:
+                last_message = Path(msg_file).read_text(encoding="utf-8",
+                                                        errors="replace")
+            except OSError:
+                last_message = ""
+        finally:
+            try:
+                os.unlink(msg_file)
+            except OSError:
+                pass
+
+        if result.timed_out:
+            outcome = "TIMEOUT"
+        elif result.exit_code != 0:
+            outcome = "FAILURE"
+        else:
+            outcome = "SUCCESS"
+
+        body = last_message if last_message.strip() else result.output
+        pattern = (expect_verdict if expect_verdict is not None
+                   else DEFAULT_VERDICT_RE)
+        verdict = _extract_verdict(body, pattern)
+        evidence.write_main(header(outcome, result.exit_code, linkage,
+                                   verdict=verdict), body)
+    except BaseException:
+        evidence.cleanup_orphans()
+        raise
+
+    verdict_ok = verdict is not None if expect_verdict is not None else True
+    return {"ok": outcome == "SUCCESS" and verdict_ok, "outcome": outcome,
+            "verdict": verdict, "exit_code": result.exit_code,
+            "artifact": str(evidence.main),
+            "prompt_copy": str(evidence.siblings["prompt"])}
+
+
+def _extract_verdict(body: str, pattern: str) -> str | None:
+    import re
+    for line in reversed(body.splitlines()):
+        line = line.strip()
+        if line:
+            return line if re.fullmatch(pattern, line) else None
+    return None

regent_cli-0.5.0/src/regent/conduction/evidence.py

@@ -0,0 +1,101 @@
+"""Atomic evidence sets for conduction artifacts (PLAN-003 contracts).
+
+An evidence SET (main artifact + siblings such as the prompt copy or the
+FULL.log) has ONE atomic contract: every path is pre-checked BEFORE anything
+is written (any pre-existing member = conflict — evidence is never
+overwritten); siblings are committed first (tmp+replace each), the main
+artifact last; every terminal outcome leaves the set complete; a non-terminal
+failure removes the orphan siblings written so far.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from pathlib import Path
+
+from ..protocol.audit import utcnow
+
+
+class EvidenceConflict(Exception):
+    def __init__(self, paths: list[str]) -> None:
+        super().__init__(f"evidence already exists: {paths}")
+        self.paths = paths
+
+
+def atomic_write(path: Path, content: "str | bytes") -> None:
+    """Atomic NO-CLOBBER publish: os.link fails with EEXIST if the target
+    appeared meanwhile (closes the precheck→publish TOCTOU — evidence is never
+    overwritten, not even by a concurrent writer)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.tmp-{uuid.uuid4().hex}")
+    payload = content.encode("utf-8") if isinstance(content, str) else content
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o644)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+        os.link(tmp, path)  # atomic no-clobber (EEXIST if raced)
+    except OSError as exc:
+        import errno as _errno
+        if exc.errno == _errno.EEXIST:
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+            raise EvidenceConflict([str(path)]) from None
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+    tmp.unlink()
+
+
+class EvidenceSet:
+    def __init__(self, main: Path, siblings: dict[str, Path]) -> None:
+        self.main = Path(main)
+        self.siblings = {k: Path(v) for k, v in siblings.items()}
+        self._written: list[Path] = []
+
+    def precheck(self) -> None:
+        existing = [str(p) for p in (self.main, *self.siblings.values())
+                    if p.exists() or p.is_symlink()]
+        if existing:
+            raise EvidenceConflict(existing)
+
+    def write_sibling(self, key: str, content: "str | bytes") -> Path:
+        path = self.siblings[key]
+        try:
+            atomic_write(path, content)
+        except (OSError, EvidenceConflict):
+            self.cleanup_orphans()
+            raise
+        self._written.append(path)
+        return path
+
+    def write_main(self, header: dict, body: str) -> Path:
+        lines = ["---"]
+        for key, value in header.items():
+            lines.append(f"{key}: {value if value is not None else 'null'}")
+        lines.append("---")
+        content = "\n".join(lines) + "\n\n" + body
+        try:
+            atomic_write(self.main, content)
+        except (OSError, EvidenceConflict):
+            self.cleanup_orphans()
+            raise
+        return self.main
+
+    def cleanup_orphans(self) -> None:
+        for path in self._written:
+            try:
+                path.unlink()
+            except OSError:
+                pass
+
+
+def header(outcome: str, exit_code: int | None, linkage: str, **extra) -> dict:
+    base = {"outcome": outcome, "exit_code": exit_code,
+            "timestamp": utcnow(), "linkage": linkage}
+    base.update(extra)
+    return base

regent_cli-0.5.0/src/regent/conduction/gate.py

@@ -0,0 +1,71 @@
+"""`regent gate run` — mechanized gate execution (PLAN-003).
+
+The gate command is NEVER invented by regent: it must appear VERBATIM in the
+plan artifact referenced by --declared-in (provenance is checked, not
+trusted). Full output is always preserved: <=200 KiB inline in the artifact;
+above that, header+tail with DECLARED truncation plus the integral output in
+<artifact>-FULL.log, all under one atomic evidence-set contract.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .evidence import EvidenceSet, header
+from .process import SubprocessRunner
+
+TAIL_LIMIT = 200 * 1024
+
+
+class ProvenanceError(Exception):
+    pass
+
+
+def run_gate(root: Path, *, command: str, declared_in: Path, artifact: Path,
+             linkage: str, timeout: float = 1800.0, runner=None) -> dict:
+    root = Path(root)
+    if not command.strip():
+        raise ProvenanceError("empty gate command is never declared")
+    declared_text = Path(declared_in).read_text(encoding="utf-8",
+                                                errors="replace")
+    if command not in declared_text:
+        raise ProvenanceError(
+            f"gate command not declared verbatim in {declared_in}")
+
+    evidence = EvidenceSet(Path(artifact),
+                           {"full": Path(str(artifact) + "-FULL.log")})
+    evidence.precheck()
+    if runner is None:
+        runner = SubprocessRunner()
+
+    # ONE cleanup guard around execution + both publishes (see consult.py).
+    try:
+        result = runner.run(["bash", "-c", command], cwd=str(root),
+                            timeout=timeout)
+        raw = result.output_bytes
+        output_bytes = len(raw)
+        truncated = output_bytes > TAIL_LIMIT
+
+        if result.timed_out:
+            outcome = "TIMEOUT"
+        elif result.exit_code == 0:
+            outcome = "GREEN"
+        else:
+            outcome = "RED"
+
+        if truncated:
+            evidence.write_sibling("full", raw)  # integral RAW BYTES first
+            tail = raw[-TAIL_LIMIT:].decode("utf-8", errors="replace")
+            body = (f"[truncated: full output is {output_bytes} bytes — see "
+                    f"{evidence.siblings['full'].name}; tail follows]\n" + tail)
+        else:
+            body = raw.decode("utf-8", errors="replace")
+        evidence.write_main(header(outcome, result.exit_code, linkage,
+                                   command=command, output_bytes=output_bytes,
+                                   truncated=truncated), body)
+    except BaseException:
+        evidence.cleanup_orphans()
+        raise
+
+    return {"ok": outcome == "GREEN", "outcome": outcome,
+            "exit_code": result.exit_code, "artifact": str(evidence.main)}

regent_cli-0.5.0/src/regent/conduction/process.py

@@ -0,0 +1,44 @@
+"""Injectable process runner for the conduction commands (PLAN-003).
+
+The real runner launches the child in a NEW SESSION (its own process group);
+on timeout the WHOLE group is SIGKILLed before the TIMEOUT outcome is
+reported — no child (not even ones spawned by bash) survives the result.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass
+class RunResult:
+    exit_code: int | None
+    output_bytes: bytes
+    timed_out: bool
+
+    @property
+    def output(self) -> str:
+        return self.output_bytes.decode("utf-8", errors="replace")
+
+
+class SubprocessRunner:
+    def run(self, argv: list[str], *, cwd: str, timeout: float) -> RunResult:
+        proc = subprocess.Popen(argv, cwd=cwd, stdin=subprocess.DEVNULL,
+                                stdout=subprocess.PIPE,
+                                stderr=subprocess.STDOUT,
+                                start_new_session=True)  # bytes mode + headless: NEVER
+        # inherit the parent's stdin — a child waiting for EOF on an
+        # inherited pipe hangs forever (caught live by the dogfooded review)
+        try:
+            output, _ = proc.communicate(timeout=timeout)
+            return RunResult(proc.returncode, output or b"", False)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+            output, _ = proc.communicate()
+            return RunResult(None, output or b"", True)

{regent_cli-0.4.0 → regent_cli-0.5.0}/src/regent/templates/MANIFEST.json

@@ -12,6 +12,7 @@
     "3121ea845545750928ca81fe656fd6a9941cbdc728e224e3aca476b0faa912cb",
     "e6fe09a2931fc4d468dccd981803be5e07a98e1dce1dca6d868291d61eaf7270",
     "6552c88b1ec1b7a286de73067dd16f7c9f333aaae3486398647d89b28b83fe44",
-    "4f09f84e5de5ab80ca54e36895e08dea9f0a30506b23d237a20d912633706c9d"
+    "4f09f84e5de5ab80ca54e36895e08dea9f0a30506b23d237a20d912633706c9d",
+    "340f8b028fdcac4542c32890a13c24fa006637afdea6c015b090de68b8b3980f"
   ]
 }

{regent_cli-0.4.0 → regent_cli-0.5.0}/src/regent/templates/skills/regent/SKILL.md

@@ -72,17 +72,25 @@ executable gate) → advisor review (+1 rebuttal cycle) → `APPROVAL.md`
 staged into the commit that closes the current boundary; record `control.version` from
 `regent status` at step start, and BEFORE staging them run `regent control explain --since-version <o valor registrado>`:
 exit 0 = explained operational churn, `UNATTRIBUTABLE` = the step commit MUST fail) →
-implement → run the gate for real →
+implement → run the gate MECHANIZED:
+`regent gate run --command "<gate from the plan>" --declared-in <PLAN.md path>
+--artifact build/GATE-NN[-tryM].md --linkage PLAN-NNN/STEP-NN` (the command must appear
+verbatim in the plan — `PROVENANCE` otherwise; `GATE_RED`/`TIMEOUT` never proceed and
+never commit; a retry uses a NEW artifact name) →
 `build/STEP-NN.md` → deliberate commit with trailer `Regent-Step: PLAN-NNN/STEP-NN` →
 final advisor review over `BASE-SHA..HEAD` → `build/CONCLUSION.md` (status + actor) →
 `regent activity conclude --status <conclusion status>`.
 
-## 4. Advisor consultations (shared contract — REQ-003 §5)
+## 4. Advisor consultations (shared contract — REQ-003 §5, mechanized)
 
-`codex --ask-for-approval never --sandbox read-only exec --cd <repo> -o <tmpfile>
-"<prompt>"` — full prompt persisted in `<ARTIFACT>-PROMPT.md`; response artifact opens
-with the structured header (`outcome`, `exit_code`, `timestamp`, `linkage`). Fail-closed:
-non-SUCCESS never advances; retry = a NEW recorded consultation.
+Write the full prompt to a file, then:
+`regent advisor consult --prompt-file <path> --artifact <ARTIFACT>.md --linkage
+<ROUND-NNN|PLAN-NNN[/STEP-NN]> [--expect-verdict "<regex>"]`
+The command persists the whole evidence pair (structured header + byte-identical prompt
+copy) on EVERY outcome, enforces the read-only sandbox, and is fail-closed: exit ≠0
+(`ADVISOR_FAILED`, `ADVISOR_UNAVAILABLE`) never advances the activity; retry = a NEW
+consultation with a NEW artifact name (evidence is never overwritten — `CONFLICT`).
+Never invoke the codex CLI directly.
 
 ## 5. Error codes you will see (exact)
 

{regent_cli-0.4.0 → regent_cli-0.5.0}/src/regent_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regent-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project.
 Author-email: Flavio Alvim <flavioalvim@gmail.com>
 License: MIT
@@ -48,7 +48,12 @@ the JSON subcommands — `regent status` (control + lock + the executable contro
 matrix as `workspace.verdict`), `regent activity
 start|resume|suspend|conclude|heartbeat|takeover`, `regent stop request|check`. Hosts
 seeded by older versions upgrade automatically on `regent init` (known-version manifest;
-unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI.
+unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI. Conduction
+phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
+--prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
+REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
+`regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
+provenance check, process-group-killing timeout, integral output preserved).
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.4.0 → regent_cli-0.5.0}/src/regent_cli.egg-info/SOURCES.txt

@@ -7,6 +7,11 @@ src/regent/activity_cli.py
 src/regent/cli.py
 src/regent/doctor.py
 src/regent/initcmd.py
+src/regent/conduction/__init__.py
+src/regent/conduction/consult.py
+src/regent/conduction/evidence.py
+src/regent/conduction/gate.py
+src/regent/conduction/process.py
 src/regent/protocol/__init__.py
 src/regent/protocol/audit.py
 src/regent/protocol/control.py
@@ -23,8 +28,10 @@ src/regent_cli.egg-info/top_level.txt
 tests/test_activity.py
 tests/test_activity_cli.py
 tests/test_choreography.py
+tests/test_consult.py
 tests/test_control.py
 tests/test_doctor.py
+tests/test_gate.py
 tests/test_init_upgrade.py
 tests/test_initcmd.py
 tests/test_lock.py

{regent_cli-0.4.0 → regent_cli-0.5.0}/tests/test_activity_cli.py

@@ -163,9 +163,9 @@ class ActivityCliTest(unittest.TestCase):
 
 
 class VersionTest(unittest.TestCase):
-    def test_cli_version_reports_040(self):
+    def test_cli_version_reports_050(self):
         import regent
-        self.assertEqual(regent.__version__, "0.4.0")
+        self.assertEqual(regent.__version__, "0.5.0")
 
 
 if __name__ == "__main__":

regent_cli-0.5.0/tests/test_consult.py

@@ -0,0 +1,180 @@
+"""Directed tests for regent advisor consult (PLAN-003 STEP-01)."""
+
+import io
+import json
+import os
+import stat
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from regent.cli import main
+from regent.conduction.consult import AdvisorUnavailable, run_consult
+from regent.conduction.evidence import EvidenceConflict
+from regent.conduction.process import RunResult
+
+
+class FakeRunner:
+    def __init__(self, exit_code=0, timed_out=False, message="opinião...\nCONCORDA\n",
+                 raw_output="raw log"):
+        self.exit_code, self.timed_out = exit_code, timed_out
+        self.message, self.raw_output = message, raw_output
+        self.argv = None
+
+    def run(self, argv, *, cwd, timeout):
+        self.argv = argv
+        msg_file = argv[argv.index("-o") + 1]
+        if not self.timed_out and self.message is not None:
+            Path(msg_file).write_text(self.message, encoding="utf-8")
+        return RunResult(None if self.timed_out else self.exit_code,
+                         self.raw_output.encode("utf-8"), self.timed_out)
+
+
+class ConsultTest(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        self.addCleanup(self._tmp.cleanup)
+        (self.root / ".regent").mkdir()
+        self.prompt = self.root / "PROMPT-src.md"
+        self.prompt.write_text("Avalie o plano.\nTERMINE com CONCORDA ou DISCORDA.",
+                               encoding="utf-8")
+        self.artifact = self.root / ".regent" / "plans" / "P" / "ADVISOR-1.md"
+
+    def _consult(self, runner, **kwargs):
+        return run_consult(self.root, prompt_file=self.prompt,
+                           artifact=self.artifact, linkage="PLAN-003",
+                           runner=runner, **kwargs)
+
+    def test_consult_success_persists_tuple_and_verdict(self):
+        result = self._consult(FakeRunner())
+        self.assertTrue(result["ok"])
+        self.assertEqual(result["verdict"], "CONCORDA")
+        text = self.artifact.read_text(encoding="utf-8")
+        self.assertIn("outcome: SUCCESS", text)
+        self.assertIn("exit_code: 0", text)
+        self.assertIn("linkage: PLAN-003", text)
+        self.assertIn("verdict: CONCORDA", text)
+        self.assertIn("opinião...", text)
+
+    def test_consult_prompt_copy_byte_identical(self):
+        self._consult(FakeRunner())
+        copy = Path(str(self.artifact) + "-PROMPT.md")
+        self.assertEqual(copy.read_bytes(), self.prompt.read_bytes())
+
+    def test_consult_sandbox_flags_forced(self):
+        runner = FakeRunner()
+        self._consult(runner)
+        argv = runner.argv
+        self.assertIn("--sandbox", argv)
+        self.assertEqual(argv[argv.index("--sandbox") + 1], "read-only")
+        self.assertIn("--ask-for-approval", argv)
+        self.assertEqual(argv[argv.index("--ask-for-approval") + 1], "never")
+
+    def test_consult_timeout_records_and_fails_closed(self):
+        result = self._consult(FakeRunner(timed_out=True, message=None))
+        self.assertFalse(result["ok"])
+        self.assertEqual(result["outcome"], "TIMEOUT")
+        text = self.artifact.read_text(encoding="utf-8")
+        self.assertIn("outcome: TIMEOUT", text)
+        self.assertIn("exit_code: null", text)
+
+    def test_consult_failure_records_exit_code(self):
+        result = self._consult(FakeRunner(exit_code=7, message=None,
+                                          raw_output="boom"))
+        self.assertFalse(result["ok"])
+        self.assertEqual(result["outcome"], "FAILURE")
+        self.assertIn("exit_code: 7", self.artifact.read_text(encoding="utf-8"))
+        self.assertIn("boom", self.artifact.read_text(encoding="utf-8"))
+
+    def test_consult_expect_verdict_fail_closed(self):
+        result = self._consult(FakeRunner(message="análise sem veredicto final\n"),
+                               expect_verdict=r"^APROVADO$")
+        self.assertFalse(result["ok"])  # SUCCESS outcome, but demanded verdict absent
+        self.assertEqual(result["outcome"], "SUCCESS")
+        self.assertIsNone(result["verdict"])
+
+    def test_consult_default_regex_null_verdict_is_informational(self):
+        result = self._consult(FakeRunner(message="sem veredicto\n"))
+        self.assertTrue(result["ok"])  # no explicit expectation: null allowed
+        self.assertIsNone(result["verdict"])
+
+    def test_consult_pair_conflict_either_file(self):
+        copy = Path(str(self.artifact) + "-PROMPT.md")
+        copy.parent.mkdir(parents=True)
+        copy.write_text("pre-existing", encoding="utf-8")
+        with self.assertRaises(EvidenceConflict):
+            self._consult(FakeRunner())
+        self.assertFalse(self.artifact.exists())  # nothing else was written
+
+    def test_consult_refuses_existing_artifact(self):
+        self.artifact.parent.mkdir(parents=True)
+        self.artifact.write_text("old evidence", encoding="utf-8")
+        with self.assertRaises(EvidenceConflict):
+            self._consult(FakeRunner())
+        self.assertEqual(self.artifact.read_text(encoding="utf-8"), "old evidence")
+
+    def test_consult_terminal_outcome_always_completes_pair(self):
+        for runner in (FakeRunner(), FakeRunner(timed_out=True, message=None),
+                       FakeRunner(exit_code=3, message=None)):
+            with self.subTest(runner=runner):
+                self._consult(runner)
+                self.assertTrue(self.artifact.exists())
+                self.assertTrue(Path(str(self.artifact) + "-PROMPT.md").exists())
+                self.artifact.unlink()
+                Path(str(self.artifact) + "-PROMPT.md").unlink()
+
+    def test_consult_missing_codex_is_capability_error(self):
+        with self.assertRaises(AdvisorUnavailable):
+            run_consult(self.root, prompt_file=self.prompt,
+                        artifact=self.artifact, linkage="X",
+                        codex_bin="definitely-not-a-real-binary-xyz")
+
+    def test_conflict_race_on_main_cleans_prompt_orphan(self):
+        artifact = self.artifact
+
+        class RacingRunner(FakeRunner):
+            def run(inner, argv, *, cwd, timeout):
+                artifact.parent.mkdir(parents=True, exist_ok=True)
+                artifact.write_text("raced-in evidence", encoding="utf-8")
+                return super().run(argv, cwd=cwd, timeout=timeout)
+
+        with self.assertRaises(EvidenceConflict):
+            self._consult(RacingRunner())
+        self.assertFalse(Path(str(artifact) + "-PROMPT.md").exists())  # cleaned
+        self.assertEqual(artifact.read_text(encoding="utf-8"),
+                         "raced-in evidence")  # the racer's evidence untouched
+
+    def test_runner_never_inherits_stdin(self):
+        from regent.conduction.process import SubprocessRunner
+        result = SubprocessRunner().run(
+            ["bash", "-c", "cat; echo done"], cwd=str(self.root), timeout=5)
+        self.assertFalse(result.timed_out)  # cat gets EOF immediately (DEVNULL)
+        self.assertIn("done", result.output)
+
+    def test_consult_cli_with_fake_codex_on_path(self):
+        bindir = self.root / "bin"
+        bindir.mkdir()
+        fake = bindir / "codex"
+        fake.write_text('#!/usr/bin/env bash\n'
+                        'while [ "$1" != "-o" ]; do shift; done\n'
+                        'printf "parecer\\nCONCORDA\\n" > "$2"\n', encoding="utf-8")
+        fake.chmod(fake.stat().st_mode | stat.S_IEXEC)
+        old_path = os.environ["PATH"]
+        os.environ["PATH"] = f"{bindir}:{old_path}"
+        self.addCleanup(os.environ.__setitem__, "PATH", old_path)
+        out = io.StringIO()
+        with redirect_stdout(out):
+            code = main(["advisor", "--project", str(self.root), "consult",
+                         "--prompt-file", str(self.prompt),
+                         "--artifact", str(self.artifact),
+                         "--linkage", "PLAN-003",
+                         "--expect-verdict", "^CONCORDA$"])
+        payload = json.loads(out.getvalue())
+        self.assertEqual(code, 0, payload)
+        self.assertEqual(payload["verdict"], "CONCORDA")
+
+
+if __name__ == "__main__":
+    unittest.main()

regent_cli-0.5.0/tests/test_gate.py

@@ -0,0 +1,108 @@
+"""Directed tests for regent gate run (PLAN-003 STEP-02)."""
+
+import json
+import subprocess
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from regent.conduction.evidence import EvidenceConflict
+from regent.conduction.gate import ProvenanceError, run_gate
+
+
+class GateTest(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        self.addCleanup(self._tmp.cleanup)
+        self.plan = self.root / "PLAN.md"
+        self.artifact = self.root / "evidence" / "GATE-01.md"
+
+    def _declare(self, command: str):
+        self.plan.write_text(f"## Etapa\n- **Gate:** `{command}`\n", encoding="utf-8")
+        return command
+
+    def _run(self, command, **kwargs):
+        return run_gate(self.root, command=command, declared_in=self.plan,
+                        artifact=self.artifact, linkage="PLAN-003/STEP-02",
+                        **kwargs)
+
+    def test_gate_green_persists_and_exits_zero(self):
+        result = self._run(self._declare("echo gate-ok"))
+        self.assertTrue(result["ok"])
+        self.assertEqual(result["outcome"], "GREEN")
+        text = self.artifact.read_text(encoding="utf-8")
+        self.assertIn("outcome: GREEN", text)
+        self.assertIn("command: echo gate-ok", text)
+        self.assertIn("gate-ok", text)
+        self.assertIn("truncated: False", text)
+
+    def test_gate_red_fails_closed_with_artifact(self):
+        result = self._run(self._declare("echo failing; exit 5"))
+        self.assertFalse(result["ok"])
+        self.assertEqual(result["outcome"], "RED")
+        self.assertEqual(result["exit_code"], 5)
+        self.assertIn("outcome: RED", self.artifact.read_text(encoding="utf-8"))
+
+    def test_gate_provenance_required(self):
+        self.plan.write_text("no gates declared here", encoding="utf-8")
+        with self.assertRaises(ProvenanceError):
+            self._run("echo undeclared")
+        self.assertFalse(self.artifact.exists())
+
+    def test_gate_timeout_recorded(self):
+        result = self._run(self._declare("sleep 30"), timeout=0.5)
+        self.assertFalse(result["ok"])
+        self.assertEqual(result["outcome"], "TIMEOUT")
+        self.assertIn("exit_code: null", self.artifact.read_text(encoding="utf-8"))
+
+    def test_gate_timeout_kills_process_group(self):
+        pidfile = self.root / "child.pid"
+        command = self._declare(f"sleep 60 & echo $! > {pidfile}; wait")
+        result = self._run(command, timeout=0.5)
+        self.assertEqual(result["outcome"], "TIMEOUT")
+        time.sleep(0.2)
+        child_pid = int(pidfile.read_text().strip())
+        with self.assertRaises(ProcessLookupError):  # the CHILD died with the group
+            import os
+            os.kill(child_pid, 0)
+
+    def test_gate_refuses_existing_artifact(self):
+        self._declare("echo x")
+        self.artifact.parent.mkdir(parents=True)
+        self.artifact.write_text("old evidence", encoding="utf-8")
+        with self.assertRaises(EvidenceConflict):
+            self._run("echo x")
+        self.assertEqual(self.artifact.read_text(encoding="utf-8"), "old evidence")
+
+    def test_full_log_sidecar_over_200k(self):
+        command = self._declare("yes A | head -c 300000")
+        result = self._run(command)
+        self.assertEqual(result["outcome"], "GREEN")
+        full = Path(str(self.artifact) + "-FULL.log")
+        self.assertTrue(full.exists())
+        self.assertGreaterEqual(full.stat().st_size, 300000)
+        text = self.artifact.read_text(encoding="utf-8")
+        self.assertIn("truncated: True", text)
+        self.assertIn("output_bytes: 300000", text)
+        self.assertIn("[truncated:", text)
+
+    def test_gate_output_tail_truncation_declared(self):
+        command = self._declare("seq 1 100000")
+        self._run(command)
+        text = self.artifact.read_text(encoding="utf-8")
+        self.assertIn("100000", text)  # the tail keeps the END of the output
+
+    def test_gate_full_sidecar_conflict(self):
+        self._declare("echo x")
+        full = Path(str(self.artifact) + "-FULL.log")
+        full.parent.mkdir(parents=True)
+        full.write_text("pre-existing evidence", encoding="utf-8")
+        with self.assertRaises(EvidenceConflict):
+            self._run("echo x")
+        self.assertFalse(self.artifact.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

{regent_cli-0.4.0 → regent_cli-0.5.0}/tests/test_skills_v1.py

@@ -15,7 +15,7 @@ KNOWN_SUBCOMMANDS = {
     "regent activity start", "regent activity resume", "regent activity suspend",
     "regent activity conclude", "regent activity heartbeat",
     "regent activity takeover", "regent stop request", "regent stop check",
-    "regent control explain",
+    "regent control explain", "regent advisor consult", "regent gate run",
 }
 
 
@@ -30,7 +30,7 @@ class SkillAntiDriftTest(unittest.TestCase):
         # Only COMMAND citations count: `regent ...` inside backtick spans.
         for name, text in _templates().items():
             for span in re.findall(r"`([^`]*)`", text.replace("\n", " ")):
-                match = re.match(r"regent (?:(activity|stop|control) )?([a-z-]+)", span)
+                match = re.match(r"regent (?:(activity|stop|control|advisor|gate) )?([a-z-]+)", span)
                 if not match:
                     continue
                 group, word = match.group(1), match.group(2)
@@ -38,6 +38,11 @@ class SkillAntiDriftTest(unittest.TestCase):
                 self.assertIn(command, KNOWN_SUBCOMMANDS,
                               f"{name}: unknown command cited: {command!r}")
 
+    def test_skill_no_longer_prescribes_raw_codex(self):
+        for name, text in _templates().items():
+            self.assertNotIn("codex --ask-for-approval", text,
+                             f"{name}: raw codex invocation still prescribed")
+
     def test_skill_templates_error_codes_exist(self):
         allowed = set(_EXIT_BY_CODE) | set(WORKSPACE_VERDICTS) | {
             "SUCCESS", "DISCORDA"}