App-qualified agent ids

backend/druks/agents.py

@@ -90,7 +90,7 @@ def get_artifact(self) -> dict[str, str]:
 @dataclass(frozen=True)
 class Agent:
     contract: type[AgentOutput]
-    # Display label for the settings UI; ``id`` is shown when it's None.
+    # Display label for the settings UI; the attribute name shows when it's None.
     name: str | None = None
     # Short human-friendly blurb of what the agent does, shown in the settings UI.
     description: str = ""
@@ -105,10 +105,11 @@ class Agent:
     # ``include_plugins=False`` skips the operator's plugin state for prompts
     # that hit no MCP server.
     include_plugins: bool = True
-    # ``id`` is the agent's durable key (settings, timeline, registry): the attribute
-    # name it's declared as, or an explicit ``id=`` for a standalone agent (a test, a
-    # one-off). ``app`` is the owning App's name, read from the class in
-    # __set_name__ to group the settings UI — blank for a standalone agent (no owner).
+    # ``id`` is the agent's durable key (settings, timeline, registry, step name):
+    # ``<app>.<attribute>`` for an agent declared on an App, or the explicit ``id=``
+    # of a standalone agent (a test, a one-off). ``app`` is the owning App's name,
+    # read from the class in __set_name__ to group the settings UI — blank for a
+    # standalone agent (no owner).
     id: str = field(default="", compare=False)
     app: str = field(init=False, compare=False, default="")
 
@@ -119,7 +120,7 @@ def __post_init__(self) -> None:
     def __set_name__(self, owner: type, attr: str) -> None:
         if self.id:  # explicit id: already registered in __post_init__
             return
-        object.__setattr__(self, "id", attr)
+        object.__setattr__(self, "id", f"{owner.name}.{attr}")
         object.__setattr__(self, "app", owner.name)
         agents.register(self)
 

backend/druks/contrib/software_factory/app.py

@@ -150,7 +150,7 @@ async def get_tracker(cls, source: str | None = None) -> Tracker | None:
         ``source`` to get it only when that source is the selected one — a
         work item syncs only to the tracker that owns it."""
         settings = await cls.settings()
-        if source is not None and source != settings.tracker:
+        if source and source != settings.tracker:
             return
         try:
             if settings.tracker == "linear":
@@ -172,8 +172,9 @@ async def get_tracker(cls, source: str | None = None) -> Tracker | None:
         except ServiceNotConnectedError:
             return
 
-    # The app's agents — any of its workflows run them. The attribute name is each
-    # agent's id (its durable settings/timeline key).
+    # The app's agents — any of its workflows run them. The app name and the
+    # attribute name form each agent's id (``software_factory.implement``), its
+    # durable settings and timeline key.
     generate_plan = Agent(
         description="ticket → implementation plan",
         prompt="software_factory/build/generate_plan.md",

backend/druks/user_settings/reads.py

@@ -28,7 +28,8 @@ async def get_agent_setting(agent: "Agent") -> AgentSettingResponse:
     effort = await SettingsOverride.agent_effort(agent.id)
     timeout = await SettingsOverride.agent_timeout(agent.id, agent.timeout)
     return AgentSettingResponse(
-        name=agent.name or agent.id,
+        name=agent.id,
+        label=agent.name or agent.id.rsplit(".", 1)[-1],
         description=agent.description,
         harness=harness.value,
         harness_source=harness.source,

backend/druks/user_settings/schemas.py

@@ -62,6 +62,7 @@ class UpdateUserSettingsRequest(BaseModel):
 
 class AgentSettingResponse(Schema):
     name: str
+    label: str
     description: str
     harness: str
     harness_source: Source

backend/migrations/versions/d2f7a9c4e816_app_qualified_agent_ids.py

@@ -0,0 +1,67 @@
+"""An agent override and a recorded agent step key on the app-qualified agent id.
+
+Revision ID: d2f7a9c4e816
+Revises: b4d7e2a9c1f6
+Create Date: 2026-09-06
+"""
+
+import re
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "d2f7a9c4e816"
+down_revision: str | Sequence[str] | None = "b4d7e2a9c1f6"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_KEYS = ("agent_harness", "agent_model", "agent_billing", "agent_effort", "agent_timeout")
+# The bundled app's agents at this revision. The database does not record which
+# app declares an agent, so an override or a recorded step of any other app's
+# agent keeps its flat name; the operator sets the override again in Settings → Apps.
+_AGENTS = (
+    "generate_plan",
+    "review_plan",
+    "revise_contract",
+    "implement",
+    "evaluate_implementation",
+    "triage_human_feedback",
+    "repo_profiler",
+    "review_pull_request",
+)
+
+
+def _rename(old: str, new: str) -> None:
+    """Move the bundled agents' names from the ``old`` prefix to the ``new`` one."""
+    op.execute(
+        sa.text(
+            "UPDATE settings_overrides SET key = split_part(key, ':', 1) || ':' || :new "
+            "|| substr(split_part(key, ':', 2), CAST(:cut AS integer)) "
+            "WHERE split_part(key, ':', 1) IN :keys AND split_part(key, ':', 2) IN :names"
+        ).bindparams(
+            sa.bindparam("new", value=new),
+            sa.bindparam("cut", value=len(old) + 1),
+            sa.bindparam("keys", expanding=True, value=list(_KEYS)),
+            sa.bindparam("names", expanding=True, value=[old + agent for agent in _AGENTS]),
+        )
+    )
+    # DBOS replays a retried run's steps under their recorded names, so they
+    # follow the id. A fresh install migrates before DBOS creates its schema.
+    if op.get_bind().execute(sa.text("SELECT to_regclass('dbos.operation_outputs')")).scalar():
+        pattern = r"\.agent\." + re.escape(old) + "(" + "|".join(_AGENTS) + r")(\.retry_wait)?$"
+        op.execute(
+            sa.text(
+                "UPDATE dbos.operation_outputs "
+                "SET function_name = regexp_replace(function_name, :pattern, :replacement) "
+                "WHERE function_name ~ :pattern"
+            ).bindparams(pattern=pattern, replacement=rf".agent.{new}\1\2")
+        )
+
+
+def upgrade() -> None:
+    _rename("", "software_factory.")
+
+
+def downgrade() -> None:
+    _rename("software_factory.", "")