[SarthakJoshi18]

What and why

How it was tested

Checklist

• make check passes.
• Every commit is signed off under the Developer Certificate of Origin.
• Documentation reflects the change.

[runkora]

Visual Walkthrough

This change adds skill marketplace source registration, from the CRD to the skills-service read path.

Registration components

A SkillMarketplaceSource flows through the operator into the sources ConfigMap, which the skills service reads.

flowchart TB
    src[SkillMarketplaceSource CR]
    tenant[OrbitTenant allowlist]
    subgraph operator [Operator]
        rec[Reconciler]
        agg[Aggregator]
    end
    cm[Sources ConfigMap]
    subgraph skillsService [Skills service]
        reg[Registry]
        ctl[Controller]
        svc[Service]
        crawl[Crawler]
    end
    gh[GitHub API]
    src --> rec
    rec --> agg
    tenant --> agg
    agg --> cm
    cm --> reg
    ctl --> svc
    reg --> svc
    svc --> crawl
    crawl --> gh
    classDef added fill:#1f883d,stroke:#1a7f37,stroke-width:2px,color:#ffffff
    classDef changed fill:#bf8700,stroke:#9a6700,stroke-width:2px,color:#ffffff
    classDef removed fill:#cf222e,stroke:#a40e26,stroke-width:2px,stroke-dasharray:5,color:#ffffff
    classDef context fill:transparent,stroke:#8c959f,stroke-width:1px,stroke-dasharray:3,color:#8c959f
    linkStyle default stroke:#8c959f,stroke-width:2px
    class src,rec,agg,cm,reg,ctl,svc,crawl added
    class tenant,gh context
    style operator fill:transparent,stroke:#8c959f
    style skillsService fill:transparent,stroke:#8c959f

Loading

Legend: green = added, amber = changed, red = removed, dashed grey = context

Node	Code	Symbols
SkillMarketplaceSource CR	skillmarketplacesource_types.go	SkillMarketplaceSourceSpec, repoKey, effectiveBranch
Reconciler	skillmarketplacesource_controller.go	Reconcile, SetupWithManager
Aggregator	skillmarketplace_aggregator.go	Sync, buildMarketplaceSources, updateStatuses
Sources ConfigMap	marketplace.go	SourcesFile, Source
Registry	registry.go	Watch, reload, loadSources
Controller	handlers_skills_entry.go	handleListSkills, handleGetSkill, respondError
Service	service.go	ListSkills, findSource, resolveMarketplace
Crawler	crawler.go	FetchTree, FetchSkills

Operator verdict paths

Only aggregated sources reach the sources file, and each source gets a status verdict.

sequenceDiagram
    participant K as Kubernetes API
    participant R as Reconciler
    participant A as Aggregator
    participant C as Sources ConfigMap
    K->>R: source created or spec changed
    R->>A: sync all sources
    A->>K: list tenants and sources
    A->>C: patch rendered sources file
    loop each source with a changed verdict
        alt namespace is system namespace
            A->>K: status Invalid, global sources
        else no active tenant
            A->>K: status Pending, tenant not active
        else name already held
            A->>K: status Invalid, duplicate name
        else repo already held
            A->>K: status Invalid, duplicate repository
        else repo not allowlisted
            A->>K: status Pending, not allowlisted
        else aggregated
            A->>K: status Aggregated
        end
    end

Loading

Node	Code	Symbols
Reconciler	skillmarketplacesource_controller.go	Reconcile, SetupWithManager
Aggregator	skillmarketplace_aggregator.go	Sync, buildMarketplaceSources, updateStatuses
Sources ConfigMap	marketplace.go	SourcesFile, Source

Skill read path

A skills request checks the cursor, the declared sources and the cache before it crawls GitHub.

sequenceDiagram
    participant C as Controller
    participant S as Service
    participant R as Registry
    participant K as Cache
    participant W as Crawler
    participant G as GitHub
    C->>S: list or get skill
    alt cursor is invalid
        S-->>C: 400 invalid cursor
    else cursor is valid
        S->>R: find source by slug
        alt slug not declared
            S-->>C: 404 marketplace not found
        else slug declared
            S->>K: read cached entries
            alt cache read fails
                S-->>C: 503 unavailable
            else cache hit
                K-->>S: sorted entries
                S-->>C: skills page
            else cache miss
                S->>W: fetch tree and skills
                W->>G: read repository files
                alt rate limited or GitHub down
                    G-->>W: failure
                    W-->>S: failure
                    S-->>C: 503 unavailable
                else crawl succeeds
                    G-->>W: file contents
                    W-->>S: skill entries
                    S->>K: store entries
                    S-->>C: skills page
                end
            end
        end
    end

Loading

Node	Code	Symbols
Controller	handlers_skills_entry.go	handleListSkills, handleGetSkill, respondError
Service	service.go	ListSkills, findSource, resolveMarketplace
Registry	registry.go	ListSources, reload
Cache	cache.go	GetMarketplace
Crawler	crawler.go	FetchTree, FetchSkills

[runkora]

Walkthrough

The pull request adds skill marketplace source registration with a skills-service, operator aggregator and frontend pages. It also renames the Terra design system package to Hades and adds sandbox environments and run scheduling.

Severity	Finding	Location
	Remove merge-conflict markers and duplicate index entries	docs/adr/README.md:130
	Restrict the LOCAL_TENANT_ID auth bypass to local environments	backend/internal/skills/handlers_skills_entry.go:53
	Mint the installation token under a detached context	backend/internal/skills/token.go:172
	Cap the size of fetched raw content	backend/internal/platform/clients/github/client.go:336
	Escape path segments separately in the contents URL	backend/internal/platform/clients/github/client.go:317
	Backfill not_before for runs already pending	backend/cmd/orbit-agents/migrations/20261012025607_run_scheduling_queue.sql:9
	Does searchRepoQualifier treat OR queries as repo-scoped?	backend/internal/credentials/adapters/githubapp/githubapp.go:361
	Honor skillsService.replicas, pull secrets and scheduling	charts/orbit/templates/skills-service/deployment.yaml:11
	Do not rebuild the skill slug inline	frontend/src/app/(dashboard)/marketplace/[marketplace]/_components/skills-page.tsx:67
	Revalidate the sandbox image only when it changed	backend/internal/agents/environments.go:308
	Is tenant-controlled spec.image restricted to allowed registries?	backend/internal/operator/sandboximage_registry.go:58

Further minor points: setting-row.test.tsx:18 queries .text-[11.5px] but the class is text-[11px], so the absence test cannot fail; GetTree and GetRawContent errors, the nit-level test and doc mismatches in ADR 2026-10-13 (stale 8085 bullet, template comment) and docs/prd/agent-marketplace.md diverging from the base branch.

Review effort: Very high. Split into marketplace, sandbox and scheduling, and the Hades rename.
Risk: High, changes authentication bypass, stored data schema and public APIs
Coverage: 1093 of 1093 files reviewed

Where to focus

Area	Why it needs a person
backend/internal/skills	Confirm the auth bypass and token sharing behave safely in production.
backend/internal/credentials/adapters/githubapp	Decide whether search query scoping can leak other repositories.
backend/cmd/orbit-agents/migrations	Verify pending runs survive the scheduling queue migration.
charts/orbit/templates/skills-service	Confirm the template should match sibling services' scheduling and replicas.
backend/internal/operator	Decide which registry hosts tenants may reference.

Lower risk

Area	Why
frontend/src/packages/hades	Mechanical Terra to Hades rename with stories and tests.
frontend/src/app/(dashboard)/model-gateway	Import path rename only.
frontend/src/app/(dashboard)/policy	Import path rename only.
docs/adr	Documentation and renamed ADR text.

Changes by area

Area	Files	Change
backend/	220	Skills service, operator marketplace and sandbox images, run scheduling, inference gateway System One.
frontend/src/app	319	Marketplace pages, agent overview, environments wizard, Hades imports.
frontend/src/packages	285	Terra package renamed to Hades.
charts/, deploy/	40	New skills-service chart, CRDs, sandbox mount and values.
docs/	70	New ADRs and PRDs, renames.
.github/, scripts, build	25	CI gates, bake and version pins.

Checked

Inference gateway routes, egress gateway, trigger deliveries, Hades rename consistency.

[runkora]

Remove merge-conflict markers and duplicate index entries

Problem: The index still contains >>>>>>> origin/main at lines 130 and 287. The Hades Wizard entry and the Enforcement Sidecar row are each listed twice.

Fix: Delete both markers and the duplicate entry and row.

[runkora]

Restrict the LOCAL_TENANT_ID auth bypass to local environments

Problem: Setting LOCAL_TENANT_ID skips authentication, delegation and scope checks. Nothing limits it to local runs, so one stray env var in a deployed pod exposes every route.

Fix: Reject LOCAL_TENANT_ID in ApplyEnvOverrides unless the environment is local.

[runkora]

Mint the installation token under a detached context

Problem: The mint runs under the leader caller's ctx and its result is shared. If the leader is cancelled, every waiter receives context canceled although their own contexts are live.

Fix: Mint with context.WithoutCancel plus a timeout.

[runkora]

Cap the size of fetched raw content

Problem: io.ReadAll(resp.Body) has no limit. A large file in a tenant-registered repository can exhaust skills-service memory.

Fix: Wrap the body in io.LimitReader with a maximum and return an error when it is exceeded.

[runkora]

Escape path segments separately in the contents URL

Problem: url.PathEscape(path) turns / into %2F, so skills/x/SKILL.md is requested as one segment. The same applies to refs such as feature/x in GetTree.

Fix: Escape each segment and join with /.

[runkora]

Does searchRepoQualifier treat OR queries as repo-scoped?

Problem: A query such as repo:o/a OR is:open yields the qualifier a, yet GitHub boolean search may return results from other repositories under a grant limited to one repository.. Question: return an empty qualifier when the query has OR or parentheses?

[runkora]

Honor skillsService.replicas, pull secrets and scheduling

Problem: replicas: 1 ignores skillsService.replicas. The pod spec also omits orbit.imagePullSecrets and orbit.scheduling, which policy-service includes, so private registries and node selectors are ignored.

Fix: Use the value and add the two includes as in policy-service/deployment.yaml.

[runkora]

Do not rebuild the skill slug inline

Problem: The inline regex strips _, . and non-ASCII characters, so a skill named pdf_tools links as pdftools and the detail page reports not found. marketplaceSlug duplicates similar logic.

Fix: Link with the raw skill name, which the route helper already encodes.

[runkora]

Revalidate the sandbox image only when it changed

Problem: Every update re-runs validate, including the registered-image check. If the image is later removed, a description-only edit fails with 400.

Fix: Check the image and size only when those fields change.

[runkora]

Is tenant-controlled spec.image restricted to allowed registries?

Problem: name.ParseReference receives the tenant's image reference. Question: should hosts be limited to configured registries or mirrors?

[justinwilkin]

Superseded by #225