flowforge-map 0.1.0__tar.gz → 0.3.0__tar.gz

{flowforge_map-0.1.0 → flowforge_map-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowforge-map
-Version: 0.1.0
+Version: 0.3.0
 Summary: Map what your app depends on (LLMs, MCP servers, APIs), check their health and security, and see what could run faster. Local and free; the scan needs no AI.
 Project-URL: Homepage, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator
 Project-URL: Issues, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator/issues
@@ -19,14 +19,17 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.12
 Requires-Dist: anthropic>=1.11.0
+Requires-Dist: cryptography>=43
 Requires-Dist: fastapi>=0.115
 Requires-Dist: httpx>=0.27
 Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: keyring>=25
 Requires-Dist: mcp>=1.2
 Requires-Dist: openai>=1.40
 Requires-Dist: pydantic>=2.8
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: segno>=1.6
 Requires-Dist: uvicorn[standard]>=0.30
 Description-Content-Type: text/markdown
 
@@ -53,7 +56,7 @@ What makes it different: **it knows which chain of steps is the bottleneck and s
 
 ## Quick start
 
-### Install (from the first release, v0.1.0)
+### Install
 
 ```bash
 uvx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
@@ -111,7 +114,37 @@ FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can as
 claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
 ```
 
-Your agent gets six read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Your agent gets ten tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+
+### Fix what's unsafe, with one click
+
+The **Issues** page lists what the scan found unsafe, and every issue has one button:
+
+| Issue | Button | What happens |
+|---|---|---|
+| A key written in Python, or in JS/TS that runs on Node | **Fix** | FlowForge shows the change (the key masked). On **Approve**, the key goes to your keys and the line reads it from the environment, on a new branch `flowforge/fix-…`. Your branch and files aren't touched; merge it when you're ready. |
+| `http://`, an unpinned MCP server, a server given the whole disk, a key in `.mcp.json`, Dart or browser code | **Send to agent** | It joins your coding agent's list (`get_fix_requests`). Tell your agent "do the FlowForge fixes". |
+
+Fix needs a git repo and the file committed. FlowForge works out the change itself, with no AI. Replace a key that was in your code with its provider anyway: older commits still hold it.
+
+### Keys your coding agent never sees
+
+Your agent only needs a key's **name**: the code it writes reads `os.environ["STRIPE_SECRET_KEY"]`. You give FlowForge the value once, and your app gets it when it starts:
+
+```bash
+flowforge key add STRIPE_SECRET_KEY        # typed hidden; saved in your OS keychain
+flowforge key list                         # each key the code reads: saved · in .env · missing
+flowforge key import                       # move a .env into FlowForge (then delete the .env)
+flowforge run -- python app.py             # your app starts with the keys in its environment
+```
+
+Each command takes `--repo PATH` (default: the folder you're in). In the dashboard, the **Keys** page does the same with no commands: paste a missing key into its box, or click **Move into FlowForge** for one that's in `.env`. On the map, a 🔑 badge marks a block whose key is missing. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+**When your agent adds a dependency that needs a key**, it calls `request_key("STRIPE_SECRET_KEY", "for Stripe in pay.py")`. The map says "Your agent asked for a key", and the new block shows in coral, "key missing". Click it, paste the key on the Keys page, and the agent's `wait_for_keys` returns the moment it's saved. The agent only ever sees the name.
+
+**See a key again** in the **Vault**: set a password and scan the QR with an authenticator app (Google Authenticator, Authy, 1Password), once. After that, your password, then the 6-digit code on your phone, open it for 5 minutes. It lists every key with its health: healthy, written in code, in `.env`, can't read, unused, or old. It also shows where each key lives, what uses it, and whether it's a live or test key. Each value shows for 30 seconds. Forgot the password? `flowforge lock reset --forget` drops the lock (your keys stay) and the dashboard says so.
+
+What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, read your keychain, or reset the lock (the dashboard then shows it was reset), so it isn't impossible. The 2FA stops web pages, anyone at your browser, and anything without your phone. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
 
 ### Send someone the map
 
@@ -238,6 +271,9 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
+| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}`, `POST /keys/{name}/import` | The keys the code reads and their status; save one (write-only), move one in from `.env`, or forget it (D36, D37) |
+| `GET /issues`, `POST /issues/{id}/preview\|fix\|send` | Every issue with its button; the masked change; make it on a new branch; send it to your agent (D37) |
+| `GET /lock`, `POST /lock/setup\|confirm\|password\|code\|close`, `GET /vault/keys`, `POST /keys/reveal` | The Vault: its lock (your password, then the authenticator code) and, once open, every key's health and one value at a time (D37, D38) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.1.0 → flowforge_map-0.3.0}/README.md

@@ -21,7 +21,7 @@ What makes it different: **it knows which chain of steps is the bottleneck and s
 
 ## Quick start
 
-### Install (from the first release, v0.1.0)
+### Install
 
 ```bash
 uvx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
@@ -79,7 +79,37 @@ FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can as
 claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
 ```
 
-Your agent gets six read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Your agent gets ten tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+
+### Fix what's unsafe, with one click
+
+The **Issues** page lists what the scan found unsafe, and every issue has one button:
+
+| Issue | Button | What happens |
+|---|---|---|
+| A key written in Python, or in JS/TS that runs on Node | **Fix** | FlowForge shows the change (the key masked). On **Approve**, the key goes to your keys and the line reads it from the environment, on a new branch `flowforge/fix-…`. Your branch and files aren't touched; merge it when you're ready. |
+| `http://`, an unpinned MCP server, a server given the whole disk, a key in `.mcp.json`, Dart or browser code | **Send to agent** | It joins your coding agent's list (`get_fix_requests`). Tell your agent "do the FlowForge fixes". |
+
+Fix needs a git repo and the file committed. FlowForge works out the change itself, with no AI. Replace a key that was in your code with its provider anyway: older commits still hold it.
+
+### Keys your coding agent never sees
+
+Your agent only needs a key's **name**: the code it writes reads `os.environ["STRIPE_SECRET_KEY"]`. You give FlowForge the value once, and your app gets it when it starts:
+
+```bash
+flowforge key add STRIPE_SECRET_KEY        # typed hidden; saved in your OS keychain
+flowforge key list                         # each key the code reads: saved · in .env · missing
+flowforge key import                       # move a .env into FlowForge (then delete the .env)
+flowforge run -- python app.py             # your app starts with the keys in its environment
+```
+
+Each command takes `--repo PATH` (default: the folder you're in). In the dashboard, the **Keys** page does the same with no commands: paste a missing key into its box, or click **Move into FlowForge** for one that's in `.env`. On the map, a 🔑 badge marks a block whose key is missing. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+**When your agent adds a dependency that needs a key**, it calls `request_key("STRIPE_SECRET_KEY", "for Stripe in pay.py")`. The map says "Your agent asked for a key", and the new block shows in coral, "key missing". Click it, paste the key on the Keys page, and the agent's `wait_for_keys` returns the moment it's saved. The agent only ever sees the name.
+
+**See a key again** in the **Vault**: set a password and scan the QR with an authenticator app (Google Authenticator, Authy, 1Password), once. After that, your password, then the 6-digit code on your phone, open it for 5 minutes. It lists every key with its health: healthy, written in code, in `.env`, can't read, unused, or old. It also shows where each key lives, what uses it, and whether it's a live or test key. Each value shows for 30 seconds. Forgot the password? `flowforge lock reset --forget` drops the lock (your keys stay) and the dashboard says so.
+
+What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, read your keychain, or reset the lock (the dashboard then shows it was reset), so it isn't impossible. The 2FA stops web pages, anyone at your browser, and anything without your phone. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
 
 ### Send someone the map
 
@@ -206,6 +236,9 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
+| `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}`, `POST /keys/{name}/import` | The keys the code reads and their status; save one (write-only), move one in from `.env`, or forget it (D36, D37) |
+| `GET /issues`, `POST /issues/{id}/preview\|fix\|send` | Every issue with its button; the masked change; make it on a new branch; send it to your agent (D37) |
+| `GET /lock`, `POST /lock/setup\|confirm\|password\|code\|close`, `GET /vault/keys`, `POST /keys/reveal` | The Vault: its lock (your password, then the authenticator code) and, once open, every key's health and one value at a time (D37, D38) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.1.0 → flowforge_map-0.3.0}/backend/flowforge/agent/server.py

@@ -1,4 +1,4 @@
-"""FlowForge as an MCP server (D28, D29): five read-only tools a coding agent can ask about the repo it works in.
+"""FlowForge as an MCP server (D28, D29, D36): read-only tools a coding agent can ask about the repo it works in.
 
 The map and the flow are read fresh from the repo on every call (plain code, nothing run, no LLM: D20). The
 dashboard's database supplies what only it knows, when it maps the same repo: measured latencies, past checks,
@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import json
 import logging
+import time
 import uuid
 from collections import Counter
 from pathlib import Path
@@ -19,6 +20,8 @@ from mcp.server.mcpserver import MCPServer
 from mcp.types import ToolAnnotations
 
 from flowforge.api.checks import CHECKABLE, check_workflow, command_text, confirmed_commands, target_for
+from flowforge.api.issues import FIX_REQUESTS_SETTING, fix_requests
+from flowforge.api.keys import add_key_request, clear_key_requests
 from flowforge.api.scan import REPO_SETTING
 from flowforge.checks import starts_process
 from flowforge.connectors.registry import Registry
@@ -28,6 +31,7 @@ from flowforge.flowmap.validate import code_writes, critical
 from flowforge.nodes.check_node import CheckNode
 from flowforge.scan import ScanResult, scan
 from flowforge.scheduler.executor import StepState, run_workflow
+from flowforge.security.keystore import NAME, KeyStore, report
 from flowforge.security.logfilter import Redactor, redact_code, secret_values_for
 from flowforge.storage import Storage, now_iso
 
@@ -42,10 +46,12 @@ INSTRUCTIONS = (
     "each with the file:line it comes from, checks their health, and shows the order the code calls them, the "
     "critical path and which calls could run together, and what is unsafe (keys in code, plain http, risky MCP "
     "servers). It reads code without running it and sends nothing to any "
-    "LLM. Answers are masked: key values never appear. It never edits code: you make the change, then call "
-    "what_changed to confirm."
+    "LLM. Answers are masked: key values never appear. It doesn't edit code for you: you make the change, "
+    "then call what_changed to confirm. When the user says \"do the FlowForge fixes\", call get_fix_requests."
 )
 READ = ToolAnnotations(read_only_hint=True, open_world_hint=False)
+ASK = ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=True, open_world_hint=False)
+MAX_WAIT_S = 110
 CHECKS = ToolAnnotations(read_only_hint=True, open_world_hint=True)   # makes requests and may start servers
 
 
@@ -160,6 +166,16 @@ def headline(tool: str, data: dict[str, Any]) -> str | None:
     if tool == "get_security_findings":
         counts = data["summary"]
         return " · ".join(f"{counts[k]} {k}" for k in ("high", "medium", "low") if counts.get(k)) or "Nothing found"
+    if tool == "get_keys":
+        counts = data["summary"]
+        parts = [f"{counts[k]} {w}" for k, w in (("missing", "missing"), ("env_file", "in .env")) if counts.get(k)]
+        return " · ".join(parts) or ("All saved" if data["keys"] else "No keys read")
+    if tool == "request_key":
+        return f"Asked for {data['name']}"
+    if tool == "wait_for_keys":
+        return "All saved" if data["done"] else f"{_plural(len(data['waiting']), 'key')} still missing"
+    if tool == "get_fix_requests":
+        return _plural(len(data["requests"]), "fix", "fixes") + " sent to you" if data["requests"] else "Nothing sent"
     if tool == "what_changed":
         if not data["saved"]:
             return "No saved map yet"
@@ -181,6 +197,29 @@ def _security_data(result: ScanResult) -> dict[str, Any]:
             "note": "Catches known key formats and these patterns, not everything. Values are never shown."}
 
 
+def _keys_data(root: Path, result: ScanResult) -> dict[str, Any]:
+    """Names and statuses only: this server, which the agent starts, never reads a value (D36)."""
+    found = report(KeyStore(root), result, verify=False)
+    return {"keys": found, "summary": dict(Counter(k["status"] for k in found if k["status"] != "saved")),
+            "run": "flowforge run -- <the command that starts the app>",
+            "note": "saved means FlowForge has it on record; this server never reads a value, so the user's "
+                    "`flowforge key list` is what confirms it can be read"}
+
+
+def _fix_requests_data(r: _Repo) -> dict[str, Any]:
+    """The user's queue (D37), without the issues the code no longer has. Only when the dashboard maps this repo."""
+    if not r.shared:
+        return {"requests": [], "message": "The dashboard doesn't map this repo, so nothing was sent from it."}
+    queue = fix_requests(r.storage)
+    here = str(r.root)
+    now = {f.id for f in r.scan().findings}
+    done = [q for q in queue if q["repo"] == here and q["id"] not in now]   # the code no longer has it
+    if done:
+        r.storage.set_setting(FIX_REQUESTS_SETTING, json.dumps([q for q in queue if q not in done]))
+    live = [q for q in queue if q["repo"] == here and q["id"] in now]
+    return {"requests": [{k: q.get(k) for k in ("id", "kind", "title", "ref", "fix", "prompt")} for q in live]}
+
+
 def _flow_data(result: Any) -> dict[str, Any]:
     if result.flow is None:
         return {"available": False, "message": result.message}
@@ -218,7 +257,8 @@ def preview(repo: Path, storage: Storage) -> dict[str, Any]:
     tone = "bad" if "down" in checked else "warn" if "warn" in checked else "ok" if checked else "plain"
     read = r.flow()
     flow, advice = _flow_data(read), _advice_data(read)
-    security = _security_data(read.scan or r.scan())
+    scanned = read.scan or r.scan()
+    security, keys = _security_data(scanned), _keys_data(r.root, scanned)
     worst = next((lv for lv in ("high", "medium", "low") if security["summary"].get(lv)), None)
     cards = [
         {"tool": "get_map", "headline": headline("get_map", deps), "sub": kinds, "tone": "plain"},
@@ -228,12 +268,16 @@ def preview(repo: Path, storage: Storage) -> dict[str, Any]:
         {"tool": "get_security_findings", "headline": headline("get_security_findings", security),
          "sub": "keys in code, plain http, risky MCP servers",
          "tone": {"high": "bad", "medium": "warn"}.get(worst or "", "ok")},
+        {"tool": "get_keys", "headline": headline("get_keys", keys),
+         "sub": "names only: the user types each key, hidden", "tone": "warn" if keys["summary"] else "ok"},
         {"tool": "get_flow", "headline": headline("get_flow", flow) if flow["available"] else None,
          "sub": "as written → could be" if flow["available"] else flow["message"], "tone": "plain"},
         {"tool": "get_advice", "headline": (_plural(len(advice["advice"]), "way") + " to be faster")
          if advice["available"] else None,
          "sub": f"saves ~{_seconds(advice['saved_ms'])}, the change written out" if advice["available"] else None,
          "tone": "warn" if advice["available"] and advice["advice"] else "plain"},
+        {"tool": "get_fix_requests", "headline": headline("get_fix_requests", _fix_requests_data(r)),
+         "sub": "issues you send from the Issues page", "tone": "plain"},
         {"tool": "what_changed", "headline": None, "sub": "After your agent edits: what it added or removed",
          "tone": "plain"},
     ]
@@ -312,6 +356,62 @@ def build_server(repo: Path, storage: Storage, *, transport: httpx.AsyncBaseTran
         shown. Catches known key formats and these patterns, not everything."""
         return r.answer("get_security_findings", _security_data(r.scan()))
 
+    @server.tool(annotations=READ)
+    def get_keys() -> dict[str, Any]:
+        """The keys the repo's code reads from its environment (names that look like keys), each with where it is
+        read, the dependencies that use it, and its status: saved in FlowForge, only in .env, or missing. You never
+        get a value and never need one: write code that reads the name from the environment, then ask the user to
+        run the `command` given (they type the key, hidden). Their app gets the keys with `flowforge run -- <app>`."""
+        return r.answer("get_keys", _keys_data(r.root, r.scan()))
+
+    @server.tool(annotations=ASK)
+    def request_key(name: str, why: str) -> dict[str, Any]:
+        """Ask the user for a key your change needs (D38), e.g. after adding Stripe: name="STRIPE_SECRET_KEY",
+        why="for Stripe in pay.py". It shows first on FlowForge's Keys page. You never get or send the value: write
+        code that reads the name from the environment, tell the user to paste the key on the Keys page, then call
+        wait_for_keys. Their app gets it with `flowforge run`."""
+        if not NAME.fullmatch(name):
+            raise ValueError("name must be an env var name: letters, digits and _, not starting with a digit")
+        add_key_request(r.storage, r.root, name, why.strip() or "asked by your coding agent")
+        saved = KeyStore(r.root).status([name], verify=False)[name] == "saved"
+        if saved:
+            clear_key_requests(r.storage, r.root, [name])
+        where = "" if r.shared else " (open the dashboard on this repo: `flowforge --repo " + str(r.root) + "`)"
+        return r.answer("request_key", {
+            "name": name, "status": "saved" if saved else "requested",
+            "message": f"{name} is saved already: use it." if saved else
+            f"Ask the user to paste {name} on FlowForge's Keys page{where}; it's at the top. Then call wait_for_keys."})
+
+    @server.tool(annotations=READ)
+    async def wait_for_keys(names: list[str], seconds: int = 60) -> dict[str, Any]:
+        """Wait until the user has saved these keys on the Keys page (D38): returns as soon as all are saved, or
+        after `seconds` (at most 110; call again to keep waiting). Reads only which names are saved, never a
+        value."""
+        import asyncio
+
+        wanted = [n for n in dict.fromkeys(names) if NAME.fullmatch(n)]
+        deadline = time.monotonic() + max(1, min(MAX_WAIT_S, int(seconds)))
+        store = KeyStore(r.root)
+        while True:
+            status = store.status(wanted, verify=False)
+            saved = [n for n in wanted if status[n] == "saved"]
+            if len(saved) == len(wanted) or time.monotonic() >= deadline:
+                break
+            await asyncio.sleep(1)
+        clear_key_requests(r.storage, r.root, saved)
+        waiting = [n for n in wanted if n not in saved]
+        return r.answer("wait_for_keys", {
+            "saved": saved, "waiting": waiting, "done": not waiting,
+            "message": "All saved: run the app with `flowforge run -- <its command>`." if not waiting else
+            f"Still waiting for {', '.join(waiting)}: call wait_for_keys again, or remind the user."})
+
+    @server.tool(annotations=READ)
+    def get_fix_requests() -> dict[str, Any]:
+        """The issues the user sent you from FlowForge's Issues page ("do the FlowForge fixes"): each with its
+        file:line, what is wrong, how to fix it and the whole change described (masked: no key value). An issue leaves
+        the list once the code no longer has it, so call what_changed after your edit to confirm."""
+        return r.answer("get_fix_requests", _fix_requests_data(r))
+
     @server.tool(annotations=READ)
     def what_changed() -> dict[str, Any]:
         """After an edit: the dependencies added or removed since the map saved in the dashboard, and the flow's

flowforge_map-0.3.0/backend/flowforge/api/issues.py

@@ -0,0 +1,150 @@
+"""The Issues page (D37): every security finding with the button it gets. Fix (FlowForge changes the code on a new
+branch) or Send to agent (queued for the coding agent's `get_fix_requests`).
+
+GET  /issues                {repo, example, summary: {high, medium, low}, issues: [{...finding, action, state, branch}]}
+                            (read from the code each time)
+POST /issues/{id}/preview   the change Fix will make, masked, and whether it can be made now
+POST /issues/{id}/fix       make it: a new branch, the key saved → {id, branch, commit, file, name}
+POST /issues/{id}/send      queue it for the agent → {id, state: "sent"}
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from flowforge.api.keys import from_this_machine, learn_saved_keys
+from flowforge.api.scan import repo_path
+from flowforge.scan import scan as scan_repo
+from flowforge.scan.models import Finding
+from flowforge.security.fixes import CantFix, apply_fix, fixable, preview
+from flowforge.state import AppState, app_state
+from flowforge.storage import Storage, now_iso
+
+router = APIRouter()
+
+FIX_REQUESTS_SETTING = "fix_requests"   # [{repo, id, kind, title, ref, fix, prompt, sent_at}]: what the agent is asked
+FIXES_SETTING = "fixes_made"            # [{repo, id, branch, commit, at}]: fixes made on a branch, not yet merged
+# Issue ids repeat across repos (kind, path, line), so every entry names its folder and only counts there (Codex review)
+EXAMPLE_WHY = "Example data: FlowForge shows the change but makes none. Map your own repo to fix it."
+
+
+def _load(storage: Storage, key: str, empty: Any) -> Any:
+    try:
+        return json.loads(storage.setting(key) or "null") or empty
+    except ValueError:
+        return empty
+
+
+def _entries(storage: Storage, key: str) -> list[dict[str, Any]]:
+    """A list setting's entries that name their folder (older ones didn't, and are dropped)."""
+    found = _load(storage, key, [])
+    return [e for e in found if isinstance(e, dict) and e.get("repo")] if isinstance(found, list) else []
+
+
+def fix_requests(storage: Storage, repo: Path | None = None) -> list[dict[str, Any]]:
+    """The queue, or only `repo`'s part of it."""
+    queue = _entries(storage, FIX_REQUESTS_SETTING)
+    return queue if repo is None else [r for r in queue if r["repo"] == str(repo.resolve())]
+
+
+def _fixes(storage: Storage, repo: Path) -> dict[str, dict[str, Any]]:
+    """The fixes made in `repo`, by issue id."""
+    return {m["id"]: m for m in _entries(storage, FIXES_SETTING) if m["repo"] == str(repo.resolve())}
+
+
+def _branch_exists(repo: Path, branch: str) -> bool:
+    done = subprocess.run(["git", "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=repo,
+                          capture_output=True)
+    return done.returncode == 0
+
+
+def _repo(s: AppState) -> Path:
+    repo = repo_path(s)
+    if repo is None or not repo.is_dir():
+        raise HTTPException(409, "Map a folder first.")
+    return repo
+
+
+def _finding(repo: Path, issue_id: str) -> Finding:
+    """The issue as the code is now (read again, so a fix starts from the current file)."""
+    found = next((f for f in scan_repo(repo).findings if f.id == issue_id), None)
+    if found is None:
+        raise HTTPException(404, "That issue isn't in the code any more. Re-scan.")
+    return found
+
+
+@router.get("/issues")
+def issues() -> dict[str, Any]:
+    s = app_state()
+    repo = repo_path(s)
+    if repo is None or not repo.is_dir():
+        return {"repo": None, "example": s.example, "summary": {}, "issues": []}
+    result = scan_repo(repo)   # the code as it is now: a merged fix or an agent's edit shows at once
+    sent = {r["id"] for r in fix_requests(s.storage, repo)}
+    made = _fixes(s.storage, repo)
+    out = []
+    for f in result.findings:
+        branch = made.get(f.id, {}).get("branch")
+        if branch and not _branch_exists(repo, branch):
+            branch = None   # the branch was deleted: the issue is open again
+        state = "fixed" if branch else "sent" if f.id in sent else "open"
+        out.append({**f.model_dump(mode="json"), "action": "fix" if fixable(repo, f) else "agent",
+                    "state": state, "branch": branch})
+    return {"repo": repo.name, "example": s.example, "summary": dict(Counter(f.level for f in result.findings)),
+            "issues": out}
+
+
+@router.post("/issues/{issue_id}/preview")
+def preview_fix(issue_id: str) -> dict[str, Any]:
+    s = app_state()
+    repo = _repo(s)
+    try:
+        shown = preview(repo, _finding(repo, issue_id))
+    except CantFix as e:
+        raise HTTPException(409, str(e)) from None
+    if s.example:
+        shown.update(can_apply=False, why_not=EXAMPLE_WHY)
+    return shown
+
+
+@router.post("/issues/{issue_id}/fix", dependencies=[Depends(from_this_machine)])
+def fix(issue_id: str) -> dict[str, Any]:
+    s = app_state()
+    repo = _repo(s)
+    if s.example:
+        raise HTTPException(409, EXAMPLE_WHY)
+    made = _fixes(s.storage, repo)
+    if made.get(issue_id) and _branch_exists(repo, made[issue_id]["branch"]):
+        raise HTTPException(409, f"Already fixed on {made[issue_id]['branch']}: merge that branch.")
+    found = _finding(repo, issue_id)
+    if not fixable(repo, found):
+        raise HTTPException(409, "FlowForge doesn't fix this one itself: send it to your agent.")
+    try:
+        done = apply_fix(repo, found)
+    except CantFix as e:
+        raise HTTPException(409, str(e)) from None
+    learn_saved_keys(s, repo)
+    here = str(repo.resolve())
+    kept = [m for m in _entries(s.storage, FIXES_SETTING) if (m["repo"], m.get("id")) != (here, issue_id)]
+    kept.append({"repo": here, "id": issue_id, "branch": done["branch"], "commit": done["commit"], "at": now_iso()})
+    s.storage.set_setting(FIXES_SETTING, json.dumps(kept))
+    return done
+
+
+@router.post("/issues/{issue_id}/send", dependencies=[Depends(from_this_machine)])
+def send(issue_id: str) -> dict[str, Any]:
+    s = app_state()
+    repo = _repo(s)
+    found = _finding(repo, issue_id)
+    here = str(repo.resolve())
+    queue = [r for r in fix_requests(s.storage) if (r["repo"], r["id"]) != (here, issue_id)]
+    queue.append({"repo": here, "id": found.id, "kind": found.kind, "title": found.title, "ref": found.ref,
+                  "fix": found.fix, "prompt": found.prompt, "sent_at": now_iso()})
+    s.storage.set_setting(FIX_REQUESTS_SETTING, json.dumps(queue))
+    return {"id": issue_id, "state": "sent"}