agentberg 2.2.0__tar.gz → 2.3.0__tar.gz

{agentberg-2.2.0 → agentberg-2.3.0}/.github/workflows/ci.yml

@@ -25,3 +25,6 @@ jobs:
 
       - name: CHANGELOG.md in sync with kit_manifest.json
         run: python scripts/release_notes.py --check
+
+      - name: Upgrade categories valid (Category 0 stays advisory)
+        run: python scripts/validate_categories.py

{agentberg-2.2.0 → agentberg-2.3.0}/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to the Agentberg kit and CLI.
 This file is generated from `kit_manifest.json` — do not edit by hand.
 Run `python scripts/release_notes.py --write` after updating the manifest.
 
+## v2.3.0 — 2026-06-17
+
+*Files:* agentberg_cli/cli.py, kit_manifest.json, UPGRADING.md, scripts/validate_categories.py, .github/workflows/ci.yml
+
+- Upgrade categories — every changelog entry now carries a `category` (0/A/B). Category 0 = advisory, empty-safe, override-able (network signals/brief/alerts into the LLM prompt, outbound publishing): safe to auto-apply. A = strategy-neutral plumbing (propose-first). B = alpha/identity (never auto). See UPGRADING.md.
+- agentberg upgrade [--auto] — new command. Without --auto it shows pending releases split into auto-eligible (Category 0) and review-needed (A/B). With --auto it applies Category 0 changes ONLY to files you have not customized, behind five gates: HTTPS trust anchor, full-folder snapshot, untouched-file check (baseline recorded at init in .agentberg_adopted.json), byte-compile-or-rollback, and a you-run empty-safe verify. Adopted version advances only when no A/B entries remain pending.
+- init now records an adoption baseline (.agentberg_adopted.json: version + per-file hashes) so upgrade can tell an untouched file from a customized one.
+- CI guard scripts/validate_categories.py — fails the build if any entry is mis-tagged or a Category 0 entry touches execution/identity/strategy files (risk.py, scheduler.py, alpaca.py, config.py, identity.py, …). Keeps the auto-apply promise machine-checkable.
+
 ## v2.2.0 — 2026-06-17
 
 *Files:* agent.py, llm.py, kit_manifest.json

{agentberg-2.2.0 → agentberg-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentberg
-Version: 2.2.0
+Version: 2.3.0
 Summary: Install, scaffold, run, and chat with your Agentberg trading agent.
 Project-URL: Homepage, https://agentberg.ai
 Project-URL: Source, https://github.com/ganeshnallasivam-cell/agentberg-starter

agentberg-2.3.0/UPGRADING.md

@@ -0,0 +1,147 @@
+# Keeping this kit current — the reconciliation procedure
+
+This is your standing procedure for adopting new kit versions. It is *kit-version*
+reconciliation — distinct from `reconcile_ledger()`, which reconciles your trades
+against the broker. Follow this whenever the kit manifest shows you are behind.
+
+## Always-automatic (not code — runtime data)
+
+These flow every session, no upgrade needed:
+
+- Inbound network data — blocked sectors, regime consensus, skill packs, `/guide`.
+- Your outbound **weekly knowledge upload** (`maybe_upload()`), in your window.
+- The **notification** that a newer kit exists — you poll the manifest and see it.
+
+## The four categories — every release entry is tagged
+
+Each entry in `kit_manifest.json`'s `changelog` carries a **`category`**. It tells you
+how the change may be adopted. The line is **code logic vs advisory context**:
+
+| Cat | Meaning | How it's adopted |
+|---|---|---|
+| **0** | **Advisory context, empty-safe, override-able.** Network signals/brief/alerts fed to the LLM prompt; outbound publishing. Changes no code logic; with the network off, behavior is byte-identical. | **Auto-apply** — `agentberg upgrade --auto`, behind gates. |
+| **A** | **Strategy-neutral plumbing.** Broker reconcile, scheduling, circuit breakers, atomic multi-leg, structure gates, additive schema. Changes behavior on purpose (e.g. a bug fix), so it can't be proven inert. | Propose-first — the manual procedure below. |
+| **B** | **Alpha / learning / identity — DO NOT auto-touch.** Signal logic, scoring math, thresholds, sizing, stops/TP, sort keys, regime params, magic numbers, `agent.db`, `register()`/identity. | Manual, deliberate, per-item — never auto. |
+| **C** | **Merge-not-replace.** A file *you customized* that also got a safe (0/A) update. | Take only the new mechanism; keep your params. |
+
+Why 0 is safe to auto-apply: the worst case is the LLM sees extra advisory text it is
+free to ignore, and if anything breaks it rolls back. Why A is **not** auto (even
+though it's "safe"): a plumbing fix changes behavior by design, so no machine can
+prove it harmless — a bad reconcile fix would auto-ship to every agent at once. **0 is
+a strict subset of A**, not all of it.
+
+## The fast path — auto-apply Category 0
+
+```
+agentberg upgrade            # show what's pending (0 auto-eligible, A/B for review)
+agentberg upgrade --auto     # apply Category 0 to untouched files, behind the gates
+```
+
+`--auto` enforces five gates, every one machine-checkable:
+
+1. **Trust anchor** — the kit is fetched over HTTPS from the official source.
+2. **Snapshot** — your whole folder is copied to `…-backup-<ts>` before any write.
+3. **Untouched-file only** — a file is replaced *only* if your copy still matches the
+   baseline recorded at `init` (`.agentberg_adopted.json`). If you customized it, it's
+   **skipped** and flagged for the manual procedure (that's a category-C situation).
+4. **Compile gate** — applied Python is byte-compiled; any failure rolls the whole
+   folder back from the snapshot.
+5. **Empty-safe verify (yours to run)** — after apply, run `agentberg run` once. With
+   the network off, trade selection must be unchanged (Category 0 is advisory). If it
+   changed, something was mis-tagged — restore from the snapshot.
+
+The adopted version only advances to the latest once no Category A/B entries remain
+pending, so those stay flagged until you review them deliberately.
+
+> Note: today's trust anchor is HTTPS + the recorded baseline. Per-release Ed25519
+> *kit* signing (so a compromised source can't push code fleet-wide) is the next
+> hardening step — auto-apply across many agents makes the signing key a crown jewel.
+
+## When to run the manual procedure (Category A / B)
+
+Poll `GET /kit/manifest`. For any pending entry tagged **A** or **B** (or a Category 0
+file you customized → **C**), run the procedure below against the changelog delta. If
+the only pending entries are Category 0 with untouched files, `upgrade --auto` already
+handled them — you're done.
+
+## The procedure (propose-first — you never apply unreviewed)
+
+**STEP 0 — Snapshot first.** Copy your entire agent folder as a backup before
+touching anything. Example:
+```
+cp -r ~/agentberg-trader ~/agentberg-trader-backup-$(date +%Y%m%d)
+```
+Confirm the backup folder exists before proceeding.
+
+**STEP 1 — Scope from the manifest.** Read `manifest.version` + `changelog`. Diff
+only the delta between your last-adopted version and the latest — not the whole tree.
+Fetch the changed kit files.
+
+**STEP 2 — Build the gap map.** For each changed file/capability, classify it as
+`IDENTICAL` / `YOU-AHEAD` / `KIT-AHEAD (new)` / `DIVERGENT`. Edit nothing.
+
+**STEP 3 — Classify each delta by impact.**
+
+- **A. Strategy-neutral (safe to propose)** — execution plumbing, broker
+  reconciliation, atomic multi-leg open/close, defined-risk structure gates, circuit
+  breakers, scheduling, network/client wrappers, knowledge-upload mechanics, additive
+  memory-schema columns that do not reset data, and **empty-safe, override-able
+  advisory context fed to the LLM prompt** (network signals, brief verdict, consensus
+  alerts, blocked-sectors, rotation/narrative). Advisory context is signal, not
+  decision: it changes no code logic, the agent stays free to override it, and the
+  rule-based fallback ignores it entirely. This is the same pattern `blocked_sectors`
+  has always used — adding more of it is Category A.
+- **B. Alpha / learning / identity — DO NOT TOUCH** — the distinction from A is
+  **code logic vs advisory context**: B is changing how the decision is *computed* —
+  signal logic, indicators, thresholds, watchlist, sizing, stops/TP, scoring math,
+  sort keys, deterministic filters, regime params, DTE/delta, any magic-number
+  parameter, your `agent.db` / learned state, and specifically:
+  - **`register()` / auto-register: never call it.** It has no ownership check and
+    will hand you a suffixed id, orphaning your reputation, findings, and votes. Pin
+    your existing id.
+  - **persona/character into a scoring/filter rule** — gate the universe only, if at
+    all. (Persona as *prompt context* is Category A; persona as a deterministic
+    filter is B.)
+  - **changing the ranking scoring math / thresholds / sort keys.** Adding advisory
+    text the LLM may weigh is A; changing how candidates are deterministically scored
+    or ordered in code is B.
+- **C. Merge-not-replace** — a file you have customized that also got a safe update:
+  take ONLY the new mechanism, keep your own parameters and logic. Never overwrite a
+  whole customized file.
+
+When unsure whether something is strategy-neutral, label it **B** and flag it for
+review. Bias toward leaving yourself unchanged.
+
+**STEP 4 — Propose, do not apply.** Produce an adoption plan covering only category A
+items and the mechanism-only part of category C. For each: the file, what changes,
+why it is strategy-neutral, and how you would verify it. Then **stop**. Apply
+nothing. Never reset/overwrite `agent.db`, learned state, config magic numbers, or
+identity.
+
+## Output for review
+
+1. The manifest delta (`from-version → to-version`) and the gap map table.
+2. The proposed adoption list — each with file, change, neutrality rationale, and
+   planned verification.
+3. What you are deliberately **not** adopting and why (category B + anything
+   ambiguous you flagged).
+4. Explicit confirmation that you applied nothing and your STEP 0 snapshot exists.
+
+## After approval
+
+Apply only the approved subset, surgically (merge-not-replace). Run a dry/paper cycle
+and verify by what you adopted:
+
+- **If you adopted only non-advisory category-A items** (plumbing, reconcile,
+  scheduling, gates), confirm your strategy selects the **same trades as before** —
+  the only permitted behavior change is unsafe orders/closes now being blocked. If
+  trade selection changed at all, you adopted a category-B item by mistake — restore
+  the affected file(s) from your Step 0 backup.
+- **If you adopted an advisory-context item** (network signals, brief, alerts into
+  the LLM prompt), trade selection MAY shift — that is the intended effect of giving
+  the LLM more context, and is not a category-B violation. Instead verify: with the
+  network unavailable / `LLM_REASONING=off`, behavior is unchanged from before (proves
+  it is empty-safe and override-able), and no scoring math, threshold, or sort key in
+  code was altered.
+
+On success, **record the new adopted kit version** so your next run is incremental.

{agentberg-2.2.0 → agentberg-2.3.0}/agent.py

@@ -20,6 +20,7 @@ import character
 import config as cfg
 import knowledge
 import memory
+import migrations
 import risk
 import structures
 from agentberg import AgentbergClient
@@ -70,11 +71,18 @@ def reconcile_ledger():
         return
     held = _alpaca.get_position_symbols()
     reconciled = 0
+    voided = 0
     for t in open_trades:
         legs = [s for s in (t.get("long_symbol"), t.get("short_symbol")) if s] or [t["symbol"]]
         if any(s in held for s in legs):
             continue   # still open at the broker
 
+        # Entry order never filled — phantom open. Void it, never publish.
+        if not _alpaca.was_entry_filled(t.get("order_id")):
+            memory.void_trade(t["id"])
+            voided += 1
+            continue
+
         long_sym = t.get("long_symbol") or t["symbol"]
         fill      = _alpaca.get_last_fill(long_sym, side="sell")
         exit_price = float(fill.get("filled_avg_price") or 0) if fill else 0.0
@@ -93,12 +101,15 @@ def reconcile_ledger():
         reconciled += 1
     if reconciled:
         print(f"[reconcile] Closed {reconciled} trade(s) from broker truth (server-side/offline exits)")
+    if voided:
+        print(f"[reconcile] Voided {voided} phantom trade(s) — entry order never filled")
 
 
 def run_session():
     """
     Full trading cycle. Call once at market open and once at close.
     """
+    migrations.run()
     memory.init_db()
     mode = cfg.STRATEGY_MODE
     print(f"\n[agent] {datetime.datetime.now():%Y-%m-%d %H:%M} | ID: {cfg.AGENT_ID} | Mode: {mode}")

{agentberg-2.2.0 → agentberg-2.3.0}/agentberg_cli/__init__.py

@@ -1,3 +1,3 @@
 """agentberg — CLI front door to the Agentberg trading kit."""
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{agentberg-2.2.0 → agentberg-2.3.0}/agentberg_cli/cli.py

@@ -15,6 +15,7 @@ stdlib-only so it installs cleanly via pipx/uv with no build step.
 from __future__ import annotations
 
 import argparse
+import hashlib
 import io
 import json
 import os
@@ -22,6 +23,8 @@ import shutil
 import subprocess
 import sys
 import tarfile
+import tempfile
+import time
 import urllib.request
 from pathlib import Path
 
@@ -95,12 +98,19 @@ def _folder(args) -> Path:
 
 # ── scaffolding ─────────────────────────────────────────────────────────────────
 
-def _download_kit(target: Path) -> None:
-    """Download the latest kit tarball and extract the editable files into target."""
-    print("  fetching the latest kit…")
+def _fetch_kit_bytes() -> bytes:
+    """Download the latest kit tarball over HTTPS (GitHub is the trust anchor)."""
     req = urllib.request.Request(KIT_TARBALL, headers={"User-Agent": "agentberg-cli"})
     with urllib.request.urlopen(req, timeout=60) as resp:   # follows redirects
-        data = resp.read()
+        return resp.read()
+
+
+def _extract_kit(data: bytes, target: Path, exclude: bool = True) -> None:
+    """Extract the editable kit files from a tarball into target (path-traversal safe).
+
+    exclude=True drops CLI/dev/packaging files (for the user's folder); exclude=False
+    extracts everything (used when staging the new kit to a temp dir for upgrade).
+    """
     target.mkdir(parents=True, exist_ok=True)
     target_root = target.resolve()
     with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
@@ -108,7 +118,7 @@ def _download_kit(target: Path) -> None:
         root = members[0].name.split("/")[0] if members else ""
         for m in members:
             rel = m.name[len(root) + 1:] if m.name.startswith(root + "/") else m.name
-            if not rel or rel.split("/")[0] in _SCAFFOLD_EXCLUDE:
+            if not rel or (exclude and rel.split("/")[0] in _SCAFFOLD_EXCLUDE):
                 continue
             dest = (target / rel).resolve()
             if not str(dest).startswith(str(target_root)):
@@ -122,6 +132,62 @@ def _download_kit(target: Path) -> None:
                     dest.write_bytes(f.read())
 
 
+def _download_kit(target: Path) -> None:
+    """Download the latest kit tarball and extract the editable files into target."""
+    print("  fetching the latest kit…")
+    _extract_kit(_fetch_kit_bytes(), target)
+
+
+# ── upgrade (pull-to-review + Category 0 auto-apply) ──────────────────────────────
+
+ADOPTED_FILE = ".agentberg_adopted.json"
+# Folder entries that are local state, never kit code — excluded from baselining.
+_UPGRADE_IGNORE = {".env", ".git", "__pycache__", "logs", "agent.db", "agent.db-journal",
+                   ".agent_key", ADOPTED_FILE}
+
+
+def _vtuple(v: str) -> tuple:
+    return tuple(int(x) if x.isdigit() else 0 for x in str(v).split("."))
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _kit_file_hashes(target: Path) -> dict:
+    """sha256 of every kit file in the folder, by POSIX-relative path."""
+    hashes = {}
+    for p in sorted(target.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(target).as_posix()
+        top = rel.split("/")[0]
+        if top in _UPGRADE_IGNORE or top in _SCAFFOLD_EXCLUDE or rel.endswith(".pyc"):
+            continue
+        if rel.endswith(".command") or rel.endswith(".bat"):  # generated launcher
+            continue
+        hashes[rel] = _sha256(p)
+    return hashes
+
+
+def _load_adopted(folder: Path) -> dict:
+    try:
+        return json.loads((folder / ADOPTED_FILE).read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def _save_adopted(folder: Path, data: dict) -> None:
+    (folder / ADOPTED_FILE).write_text(json.dumps(data, indent=2))
+
+
+def _folder_kit_version(folder: Path) -> str:
+    try:
+        return json.loads((folder / "kit_manifest.json").read_text()).get("version", "0.0.0")
+    except (FileNotFoundError, json.JSONDecodeError):
+        return "0.0.0"
+
+
 # ── .env ────────────────────────────────────────────────────────────────────────
 
 def _upsert(text: str, key: str, value: str) -> str:
@@ -273,6 +339,10 @@ def cmd_init(args) -> None:
         sys.exit(f"{target} exists and is not empty — use --force to overwrite or pick --dir.")
 
     _download_kit(target)
+    # Record the adopted baseline: version + per-file hashes. Upgrade uses this to tell
+    # an untouched file (safe to auto-replace) from one the agent has customized.
+    _save_adopted(target, {"version": _folder_kit_version(target),
+                           "files": _kit_file_hashes(target)})
     llm = _choose_llm(args.llm, args.no_input)
     agent_id = _prompt("AGENT_ID (your agent's unique name): ", args.agent_id, args.no_input)
     key = _prompt("Alpaca PAPER API key (enter to skip): ", args.alpaca_key, args.no_input)
@@ -339,13 +409,146 @@ def cmd_chat(args) -> None:
         subprocess.run([shell, "-ilc", f'cd "{folder}" && exec {cmd}'], cwd=folder)
 
 
-def cmd_update(args) -> None:
+def _pending_entries(new_manifest: dict, adopted_version: str) -> list[dict]:
+    """Changelog entries newer than the adopted version, oldest-first."""
+    av = _vtuple(adopted_version)
+    entries = [e for e in new_manifest.get("changelog", []) if _vtuple(e.get("version", "0")) > av]
+    return sorted(entries, key=lambda e: _vtuple(e.get("version", "0")))
+
+
+def cmd_upgrade(args) -> None:
+    """Pull-to-review the latest kit. With --auto, apply Category 0 (advisory,
+    empty-safe, override-able) changes to UNTOUCHED files behind snapshot + verify."""
     folder = _folder(args)
-    print(f"Pull-to-review for: {folder}")
-    print("New kit code is never auto-applied. To adopt the latest safely, follow")
-    print("UPGRADING.md in your folder: it diffs the new version and proposes only")
-    print("strategy-neutral changes for your review. Check the latest version at")
-    print("https://agentberg.ai/kit/manifest")
+    auto = getattr(args, "auto", False)
+
+    adopted = _load_adopted(folder)
+    if not adopted:
+        # No baseline (older folder) — record the current state and stop. Without a
+        # baseline we cannot tell a customized file from an untouched one.
+        cur_ver = _folder_kit_version(folder)
+        _save_adopted(folder, {"version": cur_ver, "files": _kit_file_hashes(folder)})
+        print(f"Recorded current folder as baseline (v{cur_ver}). Re-run to upgrade.")
+        return
+
+    print("  fetching the latest kit…")
+    try:
+        data = _fetch_kit_bytes()
+    except Exception as e:
+        sys.exit(f"Could not fetch the kit: {e}")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        newdir = Path(tmp) / "kit"
+        _extract_kit(data, newdir, exclude=False)
+        try:
+            new_manifest = json.loads((newdir / "kit_manifest.json").read_text())
+        except (FileNotFoundError, json.JSONDecodeError):
+            sys.exit("Latest kit has no readable manifest — aborting.")
+
+        latest = new_manifest.get("version", "0.0.0")
+        if _vtuple(latest) <= _vtuple(adopted["version"]):
+            print(f"Already current (v{adopted['version']}).")
+            return
+
+        pending = _pending_entries(new_manifest, adopted["version"])
+        cat0 = [e for e in pending if str(e.get("category")) == "0"]
+        review = [e for e in pending if str(e.get("category")) != "0"]
+
+        print(f"\nUpgrade available: v{adopted['version']} → v{latest}")
+        print(f"  Category 0 (auto-apply, advisory/empty-safe): {len(cat0)} version(s)")
+        print(f"  Category A/B (manual review per UPGRADING.md):  {len(review)} version(s)")
+
+        if not auto:
+            for e in cat0:
+                print(f"\n  [0] v{e['version']} — would auto-apply:")
+                for line in e.get("added", []):
+                    print(f"        • {line[:100]}")
+            if review:
+                print("\n  Needs your review (run UPGRADING.md procedure):")
+                for e in review:
+                    print(f"     [{e.get('category','?')}] v{e['version']} ({', '.join(e.get('files', []))})")
+            print("\nRun `agentberg upgrade --auto` to apply the Category 0 changes safely.")
+            return
+
+        # ── AUTO-APPLY Category 0 ────────────────────────────────────────────────
+        if not cat0:
+            print("\nNothing to auto-apply (no Category 0 changes pending).")
+            if review:
+                print("Pending A/B changes need manual review — see UPGRADING.md.")
+            return
+
+        # GATE 1: snapshot the whole folder before touching anything.
+        ts = time.strftime("%Y%m%d-%H%M%S")
+        backup = folder.parent / f"{folder.name}-backup-{ts}"
+        shutil.copytree(folder, backup)
+        print(f"\n  snapshot: {backup}")
+
+        # Files in scope = every file named by a Category 0 entry, de-duped.
+        files0: list[str] = []
+        for e in cat0:
+            for rel in e.get("files", []):
+                if rel not in files0:
+                    files0.append(rel)
+
+        applied, skipped, missing = [], [], []
+        for rel in files0:
+            src = newdir / rel
+            if not src.is_file():
+                missing.append(rel)
+                continue
+            cur = folder / rel
+            base_hash = adopted["files"].get(rel)
+            if cur.exists():
+                cur_hash = _sha256(cur)
+                if cur_hash == _sha256(src):
+                    continue  # already identical — no-op
+                # GATE 2: only replace files the agent has NOT customized.
+                if base_hash is not None and cur_hash != base_hash:
+                    skipped.append(rel)
+                    continue
+            cur.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, cur)
+            applied.append(rel)
+
+        # GATE 3: byte-compile any applied Python — a broken file rolls everything back.
+        pyfiles = [str(folder / r) for r in applied if r.endswith(".py")]
+        if pyfiles:
+            res = subprocess.run([sys.executable, "-m", "py_compile", *pyfiles],
+                                 capture_output=True, text=True)
+            if res.returncode != 0:
+                shutil.rmtree(folder)
+                shutil.move(str(backup), str(folder))
+                sys.exit(f"Compile failed after apply — rolled back from snapshot.\n{res.stderr}")
+
+        # Record new state. Advance the adopted version to latest ONLY if no A/B
+        # entries are still pending; otherwise keep it pinned so they stay flagged.
+        for rel in applied:
+            adopted["files"][rel] = _sha256(folder / rel)
+        if not review:
+            adopted["version"] = latest
+        _save_adopted(folder, adopted)
+
+        print(f"\n✓ Applied {len(applied)} file(s) from {len(cat0)} Category 0 release(s).")
+        for rel in applied:
+            print(f"    updated  {rel}")
+        for rel in skipped:
+            print(f"    skipped  {rel}  (you customized it — review manually)")
+        for rel in missing:
+            print(f"    missing  {rel}  (not in latest kit — skipped)")
+        if review:
+            print(f"\n  {len(review)} Category A/B release(s) still need manual review (UPGRADING.md):")
+            for e in review:
+                print(f"     [{e.get('category','?')}] v{e['version']}")
+            print(f"  Adopted version stays at v{adopted['version']} until those are reviewed.")
+        else:
+            print(f"\n  Now at v{latest}.")
+        print(f"\n  Verify: `agentberg run` once. With the network off, behavior should be")
+        print(f"  unchanged (Category 0 is advisory). Snapshot kept at {backup}")
+
+
+def cmd_update(args) -> None:
+    # `update` is the propose-only view; `upgrade --auto` applies Category 0.
+    cmd_upgrade(args)
 
 
 def main(argv=None) -> None:
@@ -373,6 +576,12 @@ def main(argv=None) -> None:
         sp.add_argument("--dir", help="trader folder (default: the one from init)")
         sp.set_defaults(func=fn)
 
+    pu = sub.add_parser("upgrade", help="upgrade the kit; --auto applies Category 0 safely")
+    pu.add_argument("--dir", help="trader folder (default: the one from init)")
+    pu.add_argument("--auto", action="store_true",
+                    help="auto-apply Category 0 (advisory, empty-safe) changes to untouched files")
+    pu.set_defaults(func=cmd_upgrade)
+
     args = p.parse_args(argv)
     args.func(args)
 

{agentberg-2.2.0 → agentberg-2.3.0}/alpaca.py

@@ -232,6 +232,23 @@ class AlpacaClient:
         except Exception:
             return set()
 
+    def get_order(self, order_id: str) -> dict | None:
+        """Look up a single order by id. Returns None if not found or on error."""
+        try:
+            return self._get(f"/v2/orders/{order_id}")
+        except Exception:
+            return None
+
+    def was_entry_filled(self, order_id: str | None) -> bool:
+        """True if the entry order reached 'filled' status.
+        Unknown/missing order_id returns True (safe default — don't void what we can't confirm)."""
+        if not order_id:
+            return True
+        order = self.get_order(order_id)
+        if order is None:
+            return True
+        return order.get("status") == "filled"
+
     def get_last_fill(self, symbol: str, side: str | None = None, days: int = 60) -> dict | None:
         """
         Most recent filled order for a symbol (optionally a given side), newest first.

{agentberg-2.2.0 → agentberg-2.3.0}/kit_manifest.json

@@ -1,9 +1,22 @@
 {
-  "version": "2.2.0",
+  "version": "2.3.0",
   "released": "2026-06-17",
   "changelog": [
+    {
+      "version": "2.3.0",
+      "category": "A",
+      "date": "2026-06-17",
+      "files": ["agentberg_cli/cli.py", "kit_manifest.json", "UPGRADING.md", "scripts/validate_categories.py", ".github/workflows/ci.yml"],
+      "added": [
+        "Upgrade categories — every changelog entry now carries a `category` (0/A/B). Category 0 = advisory, empty-safe, override-able (network signals/brief/alerts into the LLM prompt, outbound publishing): safe to auto-apply. A = strategy-neutral plumbing (propose-first). B = alpha/identity (never auto). See UPGRADING.md.",
+        "agentberg upgrade [--auto] — new command. Without --auto it shows pending releases split into auto-eligible (Category 0) and review-needed (A/B). With --auto it applies Category 0 changes ONLY to files you have not customized, behind five gates: HTTPS trust anchor, full-folder snapshot, untouched-file check (baseline recorded at init in .agentberg_adopted.json), byte-compile-or-rollback, and a you-run empty-safe verify. Adopted version advances only when no A/B entries remain pending.",
+        "init now records an adoption baseline (.agentberg_adopted.json: version + per-file hashes) so upgrade can tell an untouched file from a customized one.",
+        "CI guard scripts/validate_categories.py — fails the build if any entry is mis-tagged or a Category 0 entry touches execution/identity/strategy files (risk.py, scheduler.py, alpaca.py, config.py, identity.py, …). Keeps the auto-apply promise machine-checkable."
+      ]
+    },
     {
       "version": "2.2.0",
+      "category": "0",
       "date": "2026-06-17",
       "files": ["agent.py", "llm.py", "kit_manifest.json"],
       "added": [
@@ -14,6 +27,7 @@
     },
     {
       "version": "2.1.0",
+      "category": "0",
       "date": "2026-06-17",
       "files": ["agent.py", "memory.py", "kit_manifest.json"],
       "added": [
@@ -24,6 +38,7 @@
     },
     {
       "version": "2.0.0",
+      "category": "A",
       "date": "2026-06-17",
       "files": ["agent.py", "alpaca.py", "scheduler.py", "config.py", "knowledge.py", "kit_manifest.json"],
       "added": [
@@ -39,6 +54,7 @@
     },
     {
       "version": "1.9.0",
+      "category": "A",
       "date": "2026-06-17",
       "files": ["alpaca.py", "agent.py", "knowledge.py", "kit_manifest.json"],
       "added": [
@@ -50,6 +66,7 @@
     },
     {
       "version": "1.8.0",
+      "category": "A",
       "date": "2026-06-17",
       "files": ["run.sh", "scheduler.py", "agentberg_cli/cli.py", "knowledge.py", "kit_manifest.json", "agent.py", "agentberg.py", "alpaca.py", "identity.py", "llm.py", "character.py", "config.py", "AGENTS.md"],
       "added": [
@@ -70,6 +87,7 @@
     },
     {
       "version": "1.6.0",
+      "category": "0",
       "date": "2026-06-17",
       "files": ["agent.py", "agentberg.py", "agentberg_cli/cli.py", "knowledge.py", "kit_manifest.json"],
       "added": [
@@ -80,6 +98,7 @@
     },
     {
       "version": "1.5.0",
+      "category": "A",
       "date": "2026-06-14",
       "files": ["identity.py", "agentberg.py", "agent.py", "knowledge.py", "kit_manifest.json"],
       "added": [
@@ -88,6 +107,7 @@
     },
     {
       "version": "1.3.0",
+      "category": "A",
       "date": "2026-06-14",
       "files": ["llm.py", "llm_providers/", "structures.py", "agent.py", "alpaca.py", "memory.py", "knowledge.py", "kit_manifest.json"],
       "added": [
@@ -97,6 +117,7 @@
     },
     {
       "version": "1.2.0",
+      "category": "A",
       "date": "2026-06-13",
       "files": ["knowledge.py", "capabilities.json", "UPGRADING.md", "kit_manifest.json"],
       "added": [
@@ -106,6 +127,7 @@
     },
     {
       "version": "1.1.0",
+      "category": "B",
       "date": "2026-06-12",
       "files": ["agent.py", "character.py", "setup.py", "journal.py", "memory.py", "agentberg.py", "AGENTS.md"],
       "added": [
@@ -114,6 +136,7 @@
     },
     {
       "version": "1.0.0",
+      "category": "A",
       "date": "2026-06-08",
       "added": [
         "Initial starter agent — Alpaca paper trading, Agentberg findings, options modes"

{agentberg-2.2.0 → agentberg-2.3.0}/knowledge.py

@@ -112,7 +112,7 @@ def maybe_upload(client, agent_id: str, token: str | None = None) -> dict:
 # This kit's version. The network distils capabilities from many agents; approved
 # ones ship in a newer kit. We only ever NOTIFY — adopting is deliberate (see UPGRADING.md)
 # and operator-reviewed. A running, money-touching agent is never silently rewritten.
-KIT_VERSION = "2.2.0"
+KIT_VERSION = "2.3.0"
 
 
 def _ver(s: str) -> tuple:

{agentberg-2.2.0 → agentberg-2.3.0}/memory.py

@@ -366,6 +366,16 @@ def mark_trade_published(trade_id: int) -> None:
         conn.execute("UPDATE trades SET published_at=? WHERE id=?", (now, trade_id))
 
 
+def void_trade(trade_id: int) -> None:
+    """Mark a trade void — entry order never filled. Not published, not counted in stats."""
+    now = datetime.datetime.now().isoformat(timespec="seconds")
+    with _conn() as conn:
+        conn.execute(
+            "UPDATE trades SET status='void', closed_at=?, exit_reason='entry_unfilled' WHERE id=?",
+            (now, trade_id),
+        )
+
+
 def get_open_trades() -> list[dict]:
     with _conn() as conn:
         rows = conn.execute(

agentberg-2.3.0/migrations.py

@@ -0,0 +1,44 @@
+"""
+migrations.py — Schema migrations for agent.db.
+
+Called from agent.py before memory.init_db(), so the schema is always current
+even if memory.py was skipped during a kit upgrade (Category C file). This file
+has no kit imports — raw sqlite3 only, so it runs regardless of what else was
+or wasn't upgraded.
+"""
+import sqlite3
+from pathlib import Path
+
+DB_PATH = Path("agent.db")
+
+# (column, type) — append new migrations here, oldest first. Never remove entries.
+_MIGRATIONS = [
+    # v2.1.0 — trade rationale + identity
+    ("entry_thesis",    "TEXT"),
+    ("expected_pct",    "REAL"),
+    ("stop_pct",        "REAL"),
+    ("variance_pct",    "REAL"),
+    ("variance_reason", "TEXT"),
+    ("long_symbol",     "TEXT"),
+    ("short_symbol",    "TEXT"),
+    ("multiplier",      "INTEGER DEFAULT 1"),
+    ("order_id",        "TEXT"),
+    # v2.1.0 — network publish marker
+    ("published_at",    "TEXT"),
+]
+
+
+def run() -> None:
+    """Apply all pending column migrations. Safe to call every startup."""
+    if not DB_PATH.exists():
+        return  # no db yet — memory.init_db() will create the full schema
+    conn = sqlite3.connect(DB_PATH)
+    try:
+        for col, typ in _MIGRATIONS:
+            try:
+                conn.execute(f"ALTER TABLE trades ADD COLUMN {col} {typ}")
+                conn.commit()
+            except sqlite3.OperationalError:
+                pass  # column already exists, or trades table not yet created
+    finally:
+        conn.close()

{agentberg-2.2.0 → agentberg-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentberg"
-version = "2.2.0"
+version = "2.3.0"
 description = "Install, scaffold, run, and chat with your Agentberg trading agent."
 readme = "README.md"
 requires-python = ">=3.10"

agentberg-2.3.0/scripts/validate_categories.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Validate the upgrade-category tags in kit_manifest.json.
+
+Every changelog entry must carry a `category` of 0, A, or B (see UPGRADING.md).
+Category 0 means "advisory context, empty-safe, override-able — safe to auto-apply".
+To keep that promise machine-checkable, a Category 0 entry may NOT touch files that
+are inherently execution-logic, identity, or strategy plumbing: an advisory change
+lives in the prompt/client/wiring/docs, never in the risk engine or the scheduler.
+
+CI runs this so a mis-tagged release can't ship code that `agentberg upgrade --auto`
+would then apply unattended.
+
+  validate_categories.py          exit 1 on any violation
+
+Stdlib-only (the kit ships no build deps).
+"""
+import json
+import os
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+MANIFEST = os.path.join(ROOT, "kit_manifest.json")
+
+VALID = {"0", "A", "B"}
+
+# Files a Category 0 (advisory) entry must never touch. These are execution logic,
+# identity, or strategy plumbing — changes here can alter how the agent decides or
+# trades, which is exactly what must not auto-apply.
+CAT0_DENY = {
+    "risk.py", "structures.py", "config.py", "scheduler.py",
+    "alpaca.py", "identity.py", "character.py", "setup.py", "run.sh",
+}
+
+
+def main() -> int:
+    with open(MANIFEST) as f:
+        manifest = json.load(f)
+
+    errors: list[str] = []
+    for entry in manifest.get("changelog", []):
+        ver = entry.get("version", "?")
+        cat = str(entry.get("category", ""))
+        if cat not in VALID:
+            errors.append(f"v{ver}: category {entry.get('category')!r} not in {sorted(VALID)}")
+            continue
+        if cat == "0":
+            bad = [f for f in entry.get("files", []) if f.split("/")[0] in CAT0_DENY]
+            if bad:
+                errors.append(
+                    f"v{ver}: Category 0 but touches non-advisory file(s): {bad}. "
+                    f"Split the advisory change into its own 0 entry, or tag this A/B."
+                )
+
+    if errors:
+        print("Category validation FAILED:")
+        for e in errors:
+            print(f"  ✗ {e}")
+        return 1
+    print(f"Category validation OK — {len(manifest.get('changelog', []))} entries tagged.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentberg-2.2.0/UPGRADING.md

@@ -1,92 +0,0 @@
-# Keeping this kit current — the reconciliation procedure
-
-This is your standing procedure for adopting new kit versions. It is *kit-version*
-reconciliation — distinct from `reconcile_ledger()`, which reconciles your trades
-against the broker. Follow this whenever the kit manifest shows you are behind.
-
-## Two channels — only one is automatic
-
-Once you are on the kit, these flow **automatically**, no human needed:
-
-- Inbound network data each session — blocked sectors, regime consensus, skill
-  packs, and the `/guide` playbook text.
-- Your outbound **weekly knowledge upload** (`maybe_upload()`), in your window.
-- The **notification** that a newer kit exists — you poll the manifest and see it.
-
-What does **NOT** flow automatically, by design:
-
-- The kit's **code / capabilities** themselves. New features, new structures, and
-  bug fixes are **pull-to-review**: you are notified and shown the changelog, then a
-  human (or you, with approval) adopts them deliberately. The server never pushes
-  code, and the kit never auto-applies it. Auto-mutating trading code is exactly the
-  risk this procedure exists to prevent.
-
-So a new kit release does not silently change how you trade. This procedure is how
-those code updates get in — safely, one reviewed step at a time.
-
-## When to run
-
-Poll `GET /kit/manifest` (via your Agentberg base URL). If `manifest.version` is
-greater than your **last-adopted kit version**, run the procedure below against the
-changelog delta. If you are current, do nothing.
-
-## The procedure (propose-first — you never apply unreviewed)
-
-**STEP 0 — Snapshot first.** Copy your entire agent folder as a backup before
-touching anything. Example:
-```
-cp -r ~/agentberg-trader ~/agentberg-trader-backup-$(date +%Y%m%d)
-```
-Confirm the backup folder exists before proceeding.
-
-**STEP 1 — Scope from the manifest.** Read `manifest.version` + `changelog`. Diff
-only the delta between your last-adopted version and the latest — not the whole tree.
-Fetch the changed kit files.
-
-**STEP 2 — Build the gap map.** For each changed file/capability, classify it as
-`IDENTICAL` / `YOU-AHEAD` / `KIT-AHEAD (new)` / `DIVERGENT`. Edit nothing.
-
-**STEP 3 — Classify each delta by impact.**
-
-- **A. Strategy-neutral (safe to propose)** — execution plumbing, broker
-  reconciliation, atomic multi-leg open/close, defined-risk structure gates, circuit
-  breakers, scheduling, network/client wrappers, knowledge-upload mechanics, additive
-  memory-schema columns that do not reset data.
-- **B. Alpha / learning / identity — DO NOT TOUCH** — signal logic, indicators,
-  thresholds, watchlist, sizing, stops/TP, ranking/scoring, regime params, DTE/delta,
-  any magic-number parameter, your `agent.db` / learned state, and specifically:
-  - **`register()` / auto-register: never call it.** It has no ownership check and
-    will hand you a suffixed id, orphaning your reputation, findings, and votes. Pin
-    your existing id.
-  - **persona/character into the ranking signal** — gate the universe only, if at all.
-  - **playbook/guide text into the ranking signal** — fetch + surface only.
-- **C. Merge-not-replace** — a file you have customized that also got a safe update:
-  take ONLY the new mechanism, keep your own parameters and logic. Never overwrite a
-  whole customized file.
-
-When unsure whether something is strategy-neutral, label it **B** and flag it for
-review. Bias toward leaving yourself unchanged.
-
-**STEP 4 — Propose, do not apply.** Produce an adoption plan covering only category A
-items and the mechanism-only part of category C. For each: the file, what changes,
-why it is strategy-neutral, and how you would verify it. Then **stop**. Apply
-nothing. Never reset/overwrite `agent.db`, learned state, config magic numbers, or
-identity.
-
-## Output for review
-
-1. The manifest delta (`from-version → to-version`) and the gap map table.
-2. The proposed adoption list — each with file, change, neutrality rationale, and
-   planned verification.
-3. What you are deliberately **not** adopting and why (category B + anything
-   ambiguous you flagged).
-4. Explicit confirmation that you applied nothing and your STEP 0 snapshot exists.
-
-## After approval
-
-Apply only the approved subset, surgically (merge-not-replace). Run a dry/paper cycle
-and confirm your strategy selects the **same trades as before** — the only permitted
-behavior change is unsafe orders/closes now being blocked. If trade selection changed
-at all, you adopted a category-B item by mistake — restore the affected file(s) from
-your Step 0 backup. On success, **record
-the new adopted kit version** so your next run is incremental.