Workplan consistency optimization

api/models/workplan.py

@@ -52,6 +52,12 @@ class Workplan(Base, TimestampMixin):
         nullable=True,
         index=True,
     )
+    backing_filename: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    backing_relative_path: Mapped[str | None] = mapped_column(Text, nullable=True)
+    backing_archived: Mapped[bool | None] = mapped_column(nullable=True)
+    backing_synced_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
 
     topic: Mapped["Topic | None"] = relationship("Topic", back_populates="workplans")  # noqa: F821
     repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821

api/routers/workstreams.py

@@ -17,6 +17,7 @@ from api.events import EventEnvelope, publish_event
 from api.models.managed_repo import ManagedRepo
 from api.models.workplan import Workplan
 from api.schemas.workplan import (
+    WorkplanBindingsSync,
     WorkplanCreate,
     WorkplanRead,
     WorkplanUpdate,
@@ -212,9 +213,38 @@ async def _build_workplan_index(session: AsyncSession) -> dict[str, Any]:
                     "needs_review": bool(review and review.needs_review),
                     "health_labels": ["needs_review"] if review and review.needs_review else [],
                 }
+    await _merge_db_backing_index(session, index)
     return {"workplans": index, "workstreams": index}
 
 
+async def _merge_db_backing_index(session: AsyncSession, index: dict[str, Any]) -> None:
+    """Fill index gaps from DB-backed file bindings synced by fix-consistency."""
+    result = await session.execute(
+        select(Workplan, ManagedRepo.slug)
+        .join(ManagedRepo, Workplan.repo_id == ManagedRepo.id)
+        .where(Workplan.backing_filename.isnot(None))
+    )
+    for wp, repo_slug in result.all():
+        key = str(wp.id)
+        if key in index:
+            continue
+        index[key] = {
+            "filename": wp.backing_filename,
+            "relative_path": wp.backing_relative_path,
+            "repo_slug": repo_slug,
+            "archived": bool(wp.backing_archived),
+            "status": normalize_workplan_status(wp.status) if wp.status else None,
+            "needs_review": False,
+            "health_labels": [],
+        }
+
+
+def _invalidate_workplan_index_cache() -> None:
+    global _INDEX_CACHE, _INDEX_CACHE_AT
+    _INDEX_CACHE = None
+    _INDEX_CACHE_AT = 0.0
+
+
 def _index_with_meta(*, stale: bool, refresh_in_progress: bool) -> dict[str, Any]:
     age = time.monotonic() - _INDEX_CACHE_AT if _INDEX_CACHE_AT else None
     return {
@@ -459,6 +489,28 @@ async def workplan_index_preferred(
     return await _workplan_index(refresh=refresh, session=session)
 
 
+@workplan_router.put("/index/bindings")
+async def sync_workplan_bindings(
+    body: WorkplanBindingsSync,
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, int]:
+    """Upsert workstation workplan file bindings for remote API index fallback."""
+    synced_at = datetime.now(timezone.utc)
+    updated = 0
+    for entry in body.bindings:
+        wp = await session.get(Workplan, entry.workplan_id)
+        if wp is None:
+            continue
+        wp.backing_filename = entry.filename
+        wp.backing_relative_path = entry.relative_path
+        wp.backing_archived = entry.archived
+        wp.backing_synced_at = synced_at
+        updated += 1
+    await session.commit()
+    _invalidate_workplan_index_cache()
+    return {"updated": updated, "received": len(body.bindings)}
+
+
 @router.post("/", response_model=WorkplanRead, status_code=status.HTTP_201_CREATED)
 async def create_workstream(
     request: Request,

api/schemas/workplan.py

@@ -67,6 +67,19 @@ class WorkplanUpdate(WorkplanStatusMixin):
     repo_goal_id: uuid.UUID | None = None
 
 
+class WorkplanFileBinding(BaseModel):
+    workplan_id: uuid.UUID
+    filename: str
+    relative_path: str
+    repo_slug: str
+    archived: bool = False
+    status: WorkplanStatus | None = None
+
+
+class WorkplanBindingsSync(BaseModel):
+    bindings: list[WorkplanFileBinding]
+
+
 class WorkplanRead(WorkplanStatusMixin):
     model_config = ConfigDict(from_attributes=True)
     id: uuid.UUID
@@ -87,6 +100,10 @@ class WorkplanRead(WorkplanStatusMixin):
     queue_rank: int | None = None
     execution_group: str | None = None
     scheduled_for: datetime | None = None
+    backing_filename: str | None = None
+    backing_relative_path: str | None = None
+    backing_archived: bool | None = None
+    backing_synced_at: datetime | None = None
     created_at: datetime
     updated_at: datetime