@wardby/cli 0.2.1 → 0.4.0

package/prisma/schema.prisma

@@ -42,12 +42,21 @@ model Agent {
   tools    AgentTool[]
   maxTurns Int         @default(10)
 
-  // Phase 4: ownership. Null = public/unowned (pre-Phase-4 agents migrate this way).
-  ownerId    String?
-  owner      Principal?       @relation(fields: [ownerId], references: [id])
-  secrets    AgentSecret[]
-  datastores AgentDatastore[]
-  webhooks   Webhook[]
+  // Phase 4: ownership. Null = owner-less, a transition state only: access
+  // then comes from ResourceGrant rows alone (the migration gives everyone
+  // execute), and `wardby grants adopt-public` assigns an owner. See
+  // ResourceGrant.
+  ownerId      String?
+  owner        Principal?        @relation(fields: [ownerId], references: [id])
+  secrets      AgentSecret[]
+  datastores   AgentDatastore[]
+  webhooks     Webhook[]
+  repositories AgentRepository[]
+  issueProjects AgentIssueProject[]
+
+  /// Self-defects opt-in: the Jira project and issue type wardby files the agent's own failures into. Both or neither.
+  defectProjectKey String?
+  defectIssueType  String?
 
   // Phase 7: at most one budget group. Null = uncapped beyond its own budgetUsd.
   budgetGroupId String?
@@ -59,6 +68,11 @@ model Agent {
   /// created for it.
   memoryEnabled Boolean @default(false)
 
+  /// Un-phased: reasoning effort for native agents (low, medium, high,
+  /// xhigh, max). Validated against the model in code, not a DB enum.
+  /// Null = the provider's default.
+  effort String?
+
   /// Un-phased: sub-agent composition edges (see AgentSubAgent below). An
   /// agent can be a parent (has children it can delegate to) and/or a
   /// child (is delegated to by others) independently.
@@ -134,7 +148,11 @@ enum RunStatus {
 /// Phase 3: a WASM-sandboxed, Zod-validated tool a model can call.
 model Tool {
   id          String      @id @default(cuid())
-  name        String      @unique
+  /// Unique per owner (@@unique below), not globally: the name is what the
+  /// model calls, so what must never repeat is a name within one agent's
+  /// attachments — attach_tool, `wardby tool attach` and the importer refuse
+  /// a second same-named tool on an agent.
+  name        String
   description String
   /// Zod schema *source text*; compiled and evaluated inside the sandbox,
   /// never in the host process.
@@ -143,7 +161,8 @@ model Tool {
   /// and cached here — re-deriving it on every run would spin a fresh QuickJS
   /// runtime and evaluate the whole vendored zod bundle per attached tool,
   /// before the first LLM call, on every single run. Safe to cache because
-  /// there's no "update tool" path — paramsZod can't change without a new row.
+  /// every write of paramsZod (create, and MCP update_tool) re-derives it in
+  /// the same write. A run pins the version its load step read.
   jsonSchema  Json
   /// Tool body source; run inside the sandbox with the validated params.
   code        String
@@ -151,9 +170,12 @@ model Tool {
   updatedAt   DateTime    @updatedAt
   agents      AgentTool[]
 
-  // Phase 4: ownership. Null = public/unowned.
+  // Phase 4: ownership. Null = owner-less (a transition state; tool grants
+  // arrive in the resource-sharing grants Phase 2, see ResourceGrant).
   ownerId String?
   owner   Principal? @relation(fields: [ownerId], references: [id])
+
+  @@unique([ownerId, name])
 }
 
 /// Phase 3: explicit many-to-many join between Agent and Tool.
@@ -175,6 +197,17 @@ model AgentTool {
   allowedHosts                   Json @default("[]")
   allowedSharedDatastorePrefixes Json @default("{}")
 
+  /// Who created the attachment. Audit only: plain text, no FK (same
+  /// convention as AgentRepository.authorizedById).
+  attachedById            String?
+  /// The principal whose consent the four capability fields above carry.
+  /// The runner honours them only while this equals the agent's CURRENT
+  /// ownerId (resource-sharing grants spec §3.4.2): a write-grantee's
+  /// attachment, a make_owner transfer, or a pre-grants row nobody vouched
+  /// for runs with no secrets, no datastore and no fetch until the owner
+  /// re-grants with attach_tool. Plain text, no FK.
+  capabilitiesGrantedById String?
+
   @@id([agentId, toolId])
 }
 
@@ -270,19 +303,20 @@ enum RunTrigger {
   scheduled
   webhook
   subagent
+  host_event
 }
 
 model Run {
-  id               String     @id @default(cuid())
-  agent            Agent      @relation(fields: [agentId], references: [id])
+  id               String        @id @default(cuid())
+  agent            Agent         @relation(fields: [agentId], references: [id])
   agentId          String
-  status           RunStatus  @default(pending)
-  trigger          RunTrigger @default(manual)
-  tokensIn         Int        @default(0)
-  tokensOut        Int        @default(0)
-  costUsd          Decimal    @default(0) @db.Decimal(10, 6)
+  status           RunStatus     @default(pending)
+  trigger          RunTrigger    @default(manual)
+  tokensIn         Int           @default(0)
+  tokensOut        Int           @default(0)
+  costUsd          Decimal       @default(0) @db.Decimal(10, 6)
   error            String?
-  startedAt        DateTime   @default(now())
+  startedAt        DateTime      @default(now())
   finishedAt       DateTime?
   /// Phase 2: beaten by the executor while running; a stale value past
   /// HEARTBEAT_TIMEOUT is how the reconciler finds an orphaned run.
@@ -295,15 +329,27 @@ model Run {
   /// Phase 4: EngineResult.turns, persisted for the same reason as
   /// finalText — MCP's list_runs/get_run need it and it was previously
   /// dropped after the engine returned.
-  turns            Int        @default(0)
+  turns            Int           @default(0)
+  /// The run's model catalog entry, recorded when it started (native: the
+  /// runner's load step; coding: dispatch). The run is billed at these rates
+  /// for its whole life, resumes included. Null on runs from before the
+  /// model catalog.
+  pricingVersion   String?
+  pricingSnapshot  Json?
   /// Detached executors are recovered by handle rather than inferred from trigger.
-  executionManaged Boolean    @default(false)
+  executionManaged Boolean       @default(false)
   /// Phase 6: which durable executor backend holds this run, if any
   /// ("dbos" = a DBOS workflow whose id equals this run's id). Null for
   /// in-process runs. The reconciler consults the backend before declaring a
   /// stale run lost, and can adopt one orphaned by a dead instance.
   executionBackend String?
   codingRun        CodingRun?
+  hostCheck        RunHostCheck?
+  hostStatus       RunHostStatus?
+  issueStatus      RunIssueStatus?
+  attribution      RunAttribution?
+  modelUsage       RunModelUsage[]
+  serviceStatuses  CodingRunServiceStatus[]
 
   /// Un-phased: sub-agent dispatch (see AgentSubAgent). Null for a
   /// top-level run; set when this run was created by a parent run's
@@ -326,6 +372,19 @@ model Run {
   /// loaded systemPrompt at run time so the stable prefix stays
   /// prompt-cache-eligible across dispatches.
   taskOverride            String?
+  /// The principal the run is visible to besides the agent's owner
+  /// (resource-sharing grants spec §3.5): the trigger_agent caller, a
+  /// webhook's creator, or a sub-agent's parent run's triggerer. Null for
+  /// scheduled, host-event and CLI runs, which only the owner sees. Plain
+  /// text, no FK.
+  triggeredById           String?
+
+  @@index([agentId, triggeredById])
+  /// The admin viewer's graph window (runs started since a time, or still
+  /// pending/running) and its ancestor/children walks (docs/viewer-api.md).
+  @@index([startedAt])
+  @@index([status])
+  @@index([parentRunId])
 }
 
 /// Phase 5: owner-configured coding behavior. Runtime credentials and opaque
@@ -339,13 +398,31 @@ model CodingAgentProfile {
   defaultTask              String?
   allowWebhookTaskOverride Boolean @default(false)
   timeoutSec               Int     @default(1800)
-  allowedEgress            Json
+  /// Unused; dropped after rollout (see the package-registry plan, Task 14).
+  allowedEgress            Json    @default("[]")
   protectedPaths           Json
+  collectExclude           Json    @default("[]")
   toolchain                String  @default("node")
   toolchainVersion         String?
   workerImageRef           String?
   /// Per-agent workspace size in MiB; null = CODING_DISK_MB.
   workspaceDiskMb          Int?
+  packageAllowlist         Json    @default("{}")
+  packagePolicy            Json    @default("{}")
+  /// Admin-requested debug trace: while now < debugTraceUntil, every coding
+  /// run of this agent is dispatched with CodingRun.debugTrace set. Null = off.
+  debugTraceUntil          DateTime?
+  /// Coding-run services (docs/coding-services.md): the catalog names
+  /// (CodingService.name) this agent's runs may start, any version the catalog
+  /// has. Empty = none. Owner-set through update_agent.
+  services                 Json      @default("[]")
+
+  /// How `repository` was authorized for this agent (see AgentRepository.authorizedVia):
+  /// "host_permission", "admin", or "grandfathered". Null = never authorized; runs are refused.
+  repositoryAuthorizedVia  String?
+  /// The principal whose GitHub access (or admin approval) authorized it. Audit only, no FK.
+  repositoryAuthorizedById String?
+  repositoryAuthorizedAt   DateTime?
 }
 
 /// Phase 5: immutable dispatch inputs plus opaque execution/result state for
@@ -360,8 +437,10 @@ model CodingRun {
   provider          String
   model             String
   timeoutSec        Int
-  allowedEgress     Json
+  /// Unused; dropped after rollout (see the package-registry plan, Task 14).
+  allowedEgress     Json                @default("[]")
   protectedPaths    Json
+  collectExclude    Json                @default("[]")
   jobBackend        String?
   jobHandle         String?
   result            Json?
@@ -371,6 +450,8 @@ model CodingRun {
   failureCategory   String?
   diagnosticId      String?
   workerImage       String?
+  /// Claude Code's tool-runner image, resolved from the agent's toolchain at dispatch; null for Codex runs.
+  toolImage         String?
   budgetReservedUsd Decimal             @db.Decimal(10, 6)
   /// Phase 12 concurrency queue: set when start() found every coding slot
   /// taken (CODING_MAX_CONCURRENT), cleared when the run claims a slot. A
@@ -378,6 +459,18 @@ model CodingRun {
   queuedAt          DateTime?
   /// Per-agent workspace size in MiB; null = CODING_DISK_MB.
   workspaceDiskMb   Int?
+  packageAllowlist  Json                @default("{}")
+  packagePolicy     Json                @default("{}")
+  /// Fixed at dispatch from the profile's debugTraceUntil: the worker writes a
+  /// full stream trace to its own pod log (never to the database).
+  debugTrace        Boolean             @default(false)
+  /// Coding-run services resolved at dispatch from the base branch's
+  /// .wardby/services.yaml: one snapshot per service (the catalog entry minus
+  /// kind), fixed for the run's lifetime. Empty = none.
+  services          Json                @default("[]")
+  /// The originating tracker issue ("jira" + key), set by the control plane from the run tree, never from model output.
+  issueProvider     String?
+  issueKey          String?
   createdAt         DateTime            @default(now())
   updatedAt         DateTime            @updatedAt
   proxySession      CodingProxySession?
@@ -392,12 +485,84 @@ model CodingRun {
   rootCodingRun   CodingRun?  @relation("CodingRunContinuation", fields: [rootCodingRunId], references: [runId])
   continuations   CodingRun[] @relation("CodingRunContinuation")
 
+  registryAllowances       RegistryAllowance[]
+  registryFetches          RegistryFetch[]
+  registryApprovedVersions RegistryApprovedVersion[]
+  registryPlanRefusals     RegistryPlanRefusal[]
+
   @@index([jobBackend, jobHandle])
   @@index([failureCategory])
   @@index([queuedAt])
   @@index([rootCodingRunId])
 }
 
+/// Coding-run services (docs/coding-services.md): the catalog a repository's
+/// .wardby/services.yaml names entries from. Admin-managed over MCP
+/// (list/get_service: agents:read; create/update/delete_service:
+/// services:manage, audit-logged).
+/// Built-in rows ship with wardby, seeded by migration, and change only with a
+/// wardby release. `kind` is "sidecar" (a fresh instance in each run's pod);
+/// "external" is reserved.
+model CodingService {
+  id            String   @id @default(cuid())
+  name          String
+  version       String
+  kind          String   @default("sidecar")
+  /// Digest-pinned image reference (repo@sha256:...).
+  image         String
+  port          Int
+  /// Environment for the service container itself: throwaway per-run values, never secrets.
+  serviceEnv    Json     @default("{}")
+  /// Variables the agent's shells receive (DATABASE_URL, PG*, REDIS_URL, ...).
+  testEnv       Json     @default("{}")
+  /// { command, periodSeconds, timeoutSeconds, failureThreshold }: the sidecar's startup probe.
+  readiness     Json
+  /// { cpuMillicores, memoryMib, diskMib }: requests equal limits.
+  resources     Json
+  /// Where the service writes its data: an emptyDir in the run pod.
+  dataPath      String
+  /// Further directories the image writes to (socket directory, /tmp): each an emptyDir.
+  writablePaths Json     @default("[]")
+  builtin       Boolean  @default(false)
+  /// The admin who created it. Audit only, no FK; null for built-ins.
+  createdById   String?
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+
+  @@unique([name, version])
+}
+
+enum CodingServiceState {
+  pending
+  probing
+  ready
+  failed
+}
+
+/// Live start-up state of one coding-run service (one row per run x
+/// service), written by the job launcher as it observes the service, for
+/// display only (the viewer). The run's CodingRun.services
+/// snapshot says what was started; this says how far each one got.
+/// `attempts` is the readiness probes made so far, known only where wardby
+/// runs the probe itself (Docker); `reason` is a fixed identifier
+/// (image_unavailable, start_failed, exited, probe_failed, timed_out),
+/// never probe output.
+model CodingRunServiceStatus {
+  id        String             @id @default(cuid())
+  runId     String
+  run       Run                @relation(fields: [runId], references: [id], onDelete: Cascade)
+  name      String
+  state     CodingServiceState @default(pending)
+  attempts  Int?
+  reason    String?
+  readyAt   DateTime?
+  failedAt  DateTime?
+  createdAt DateTime           @default(now())
+  updatedAt DateTime           @updatedAt
+
+  @@unique([runId, name])
+}
+
 enum CodingProxySessionStatus {
   active
   cancelled
@@ -426,6 +591,22 @@ model CodingProxySession {
   createdAt      DateTime                 @default(now())
   updatedAt      DateTime                 @updatedAt
   requests       CodingProxyRequest[]
+  /// Hash of the derived registry-only token (see deriveRegistryToken); the
+  /// token itself is never persisted.
+  registryTokenHash String?               @unique
+  /// Set the first time the proxy refuses a request of this session for
+  /// budget; lets the executor report the run as out of budget.
+  budgetExhaustedAt DateTime?
+  /// The upstream error code (a fixed identifier, never a message) of the
+  /// first provider failure the proxy relayed for this session; lets the
+  /// executor say the model provider refused the run.
+  upstreamFailure   String?
+  /// The run's catalog entry, copied from Run.pricingSnapshot when the session
+  /// is created; the proxy prices and shapes requests from it. Null on
+  /// sessions from before the model catalog (the proxy falls back to the
+  /// shipped catalog).
+  pricingVersion String?
+  catalogEntry   Json?
 
   @@index([deadlineAt])
 }
@@ -458,6 +639,96 @@ model CodingProxyRequest {
   @@index([sessionId, status])
 }
 
+enum RegistryFetchOutcome {
+  served
+  refused
+}
+
+/// One package a run's profile has approved from a given ecosystem, resolved
+/// once at dispatch (see CodingRun.packageAllowlist) and used to gate every
+/// proxy fetch for the run's lifetime.
+model RegistryAllowance {
+  runId     String
+  ecosystem String
+  name      String
+  createdAt DateTime  @default(now())
+  run       CodingRun @relation(fields: [runId], references: [runId], onDelete: Cascade)
+
+  @@id([runId, ecosystem, name])
+}
+
+/// Audit ledger of every package fetch the registry proxy served or refused
+/// for a run.
+model RegistryFetch {
+  id        String               @id @default(cuid())
+  runId     String
+  ecosystem String
+  name      String
+  version   String?
+  filename  String?
+  integrity String?
+  sizeBytes Int?
+  outcome   RegistryFetchOutcome
+  reason    String?
+  createdAt DateTime             @default(now())
+  run       CodingRun            @relation(fields: [runId], references: [runId], onDelete: Cascade)
+
+  @@index([runId, createdAt])
+}
+
+/// Immutable facts about one published package version, read from the
+/// registry itself (never from a lockfile) by lockfile verification: its
+/// publish time, integrity, download URL and declared dependencies
+/// ([{ key, name, range }], aliases resolved). Stored once and reused
+/// forever; allow/deny decisions are never cached here.
+model RegistryVersionFact {
+  ecosystem    String
+  name         String
+  version      String
+  publishedAt  DateTime
+  integrity    String
+  downloadUrl  String
+  dependencies Json
+  createdAt    DateTime @default(now())
+
+  @@id([ecosystem, name, version])
+}
+
+/// One exact package version a run's lockfile plan (POST
+/// /registry/<ecosystem>/-/plan) verified and approved: a download of it is
+/// served directly, integrity-checked against this value.
+model RegistryApprovedVersion {
+  runId     String
+  ecosystem String
+  name      String
+  version   String
+  integrity String
+  createdAt DateTime  @default(now())
+  run       CodingRun @relation(fields: [runId], references: [runId], onDelete: Cascade)
+
+  @@id([runId, ecosystem, name, version])
+}
+
+/// One exact package version a run's lockfile plan refused for a reason
+/// intrinsic to the registry's name@version (too new, an advisory, not
+/// published, no integrity, hosted elsewhere): a download of it is answered
+/// from here with the same code and reason, without a graph walk.
+model RegistryPlanRefusal {
+  runId     String
+  ecosystem String
+  name      String
+  version   String
+  code        String
+  reason      String
+  /// Set for a too-new refusal: the answer re-checks the version's age
+  /// against the run's cutoff at answer time, so the refusal lapses.
+  publishedAt DateTime?
+  createdAt   DateTime  @default(now())
+  run         CodingRun @relation(fields: [runId], references: [runId], onDelete: Cascade)
+
+  @@id([runId, ecosystem, name, version])
+}
+
 /// Phase 2: single-row-per-scope lease so exactly one scheduler process
 /// ticks at a time. `holder` is a process instance id (crypto.randomUUID()).
 model SchedulerLease {
@@ -481,6 +752,46 @@ model Principal {
   webhooks     Webhook[]
   authUser     AuthUser?
   budgetGroups BudgetGroup[]
+
+  hostIdentities           HostIdentity[]
+  hostIdentityLinkRequests HostIdentityLinkRequest[]
+  grants                   ResourceGrant[]
+}
+
+/// Explicit sharing of one resource with one grantee (docs/private/
+/// 2026-09-26-resource-sharing-grants-spec-and-plan.md). Polymorphic on
+/// (resourceType, resourceId) -- no FK to the resource, so every resource
+/// delete path removes its grants in the same transaction. Levels are
+/// ordered per type and validated in code (core/grants.ts), like
+/// AgentRepository.provider, so a new type or level needs no enum migration.
+model ResourceGrant {
+  id                 String     @id @default(cuid())
+  /// "agent" | "tool" | "budget_group" (later "secret" | "datastore").
+  resourceType       String
+  resourceId         String
+  /// "principal" | "everyone" (later "group").
+  granteeKind        String
+  granteePrincipalId String?
+  granteePrincipal   Principal? @relation(fields: [granteePrincipalId], references: [id], onDelete: Cascade)
+  /// Normalised grantee identity for uniqueness: "principal:<id>", "everyone"
+  /// (later "group:<id>"). Needed because NULL granteePrincipalId values are
+  /// distinct in a unique index. Shape enforced by a hand-written CHECK
+  /// (ResourceGrant_grantee_shape, not representable here).
+  granteeKey         String
+  /// Per-type ordered level (core/grants.ts LEVELS).
+  level              String
+  /// "owner" (grant_access), "migration_public", "implied_attachment",
+  /// "import", "operator". Audit only.
+  source             String     @default("owner")
+  /// Principal who created/last changed it. Audit only: plain text, no FK
+  /// (same convention as AgentRepository.authorizedById).
+  grantedById        String?
+  createdAt          DateTime   @default(now())
+  updatedAt          DateTime   @updatedAt
+
+  @@unique([resourceType, resourceId, granteeKey])
+  @@index([granteeKey, resourceType])
+  @@index([granteePrincipalId])
 }
 
 /// Phase 4: durable handle backing both a triggered run and (reserved,
@@ -619,6 +930,11 @@ model AuthUser {
   principal   Principal                @relation(fields: [principalId], references: [id])
   displayName String?
   status      String                   @default("enabled")
+  /// wardby roles (src/mcp/auth/resource-server.ts ROLE_PERMISSIONS: admin,
+  /// package-approver, service-manager, model-manager), set with `wardby auth user grant`. Empty = member.
+  /// A privileged operation needs its scope on the token AND a role here
+  /// that grants it; unknown values grant nothing.
+  roles       String[]                 @default([])
   createdAt   DateTime                 @default(now())
   updatedAt   DateTime                 @updatedAt
   loginKeys   AuthLoginKey[]
@@ -729,3 +1045,329 @@ model AuthRateLimit {
 
   @@index([expiresAt])
 }
+
+/// Which repositories on which code-review host a native agent may act on,
+/// and which host events trigger it. See
+/// docs/private/2026-09-25-code-review-host-design.md §4.1.
+model AgentRepository {
+  id         String   @id @default(cuid())
+  agentId    String
+  agent      Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  /// "github" today; validated in code so adding a host needs no enum migration.
+  provider   String
+  /// Canonical lower-case owner/name for the provider.
+  repository String
+  /// "read" or "write".
+  access     String
+  /// Subset of "pull_request", "mention", "push".
+  triggers   String[] @default([])
+  /// Only with the "pull_request" trigger (required there); names the agent's
+  /// check. Unique per repository across all links (NULLs are distinct).
+  checkName  String?
+  createdAt  DateTime @default(now())
+
+  /// How this link was authorized: "host_permission" (the agent owner's
+  /// verified host identity had enough access), "admin" (a wardby admin
+  /// approved it explicitly), or "grandfathered" (existed before
+  /// authorization was enforced). Null = never authorized; use is refused.
+  authorizedVia  String?
+  /// The principal who authorized it. Audit only: plain text, no FK.
+  authorizedById String?
+  authorizedAt   DateTime?
+
+  @@unique([agentId, provider, repository])
+  @@unique([provider, repository, checkName])
+  @@index([provider, repository])
+}
+
+/// The host check a run owns, so the review tool can complete it and the
+/// run finalizer can close it if the run ends without publishing.
+model RunHostCheck {
+  runId       String    @id
+  run         Run       @relation(fields: [runId], references: [id], onDelete: Cascade)
+  provider    String
+  repository  String
+  checkId     String
+  headSha     String
+  /// The pull request the run was dispatched for. The review tool only
+  /// completes or creates a check for this PR. Null on rows written before it
+  /// existed: such a run publishes without a check.
+  prNumber    Int?
+  completedAt DateTime?
+}
+
+/// De-duplicates host webhook redeliveries; pruned after 7 days.
+/// The status comment wardby posts on the issue or pull request whose
+/// @-mention started this run ("working on it"), edited with the outcome
+/// when the run ends. One per mention run.
+model RunHostStatus {
+  runId                  String    @id
+  run                    Run       @relation(fields: [runId], references: [id], onDelete: Cascade)
+  provider               String
+  repository             String
+  /// The issue or pull request number the comment is on.
+  number                 Int
+  /// "conversation" (issue/PR comment) or "inline" (a reply in a review thread).
+  commentKind            String
+  /// Null until the "working on it" comment is posted. The row is written
+  /// with the run, so a run that dies before the comment exists still gets
+  /// an outcome comment (from the reconciler).
+  commentId              String?
+  /// For an inline mention: the review comment to reply to when the outcome
+  /// has to be posted as a new comment.
+  replyToReviewCommentId String?
+  createdAt              DateTime  @default(now())
+  completedAt            DateTime?
+}
+
+model HostEventDelivery {
+  provider   String
+  deliveryId String
+  receivedAt DateTime @default(now())
+
+  @@id([provider, deliveryId])
+  @@index([receivedAt])
+}
+
+/// A principal's verified identity on a code-review host (GitHub today),
+/// linked through the host's user-authorization flow (link_host_account).
+/// Only the numeric user id and login are stored, never a user token. A host
+/// user belongs to at most one principal.
+model HostIdentity {
+  principalId String
+  principal   Principal @relation(fields: [principalId], references: [id], onDelete: Cascade)
+  /// "github" today; validated in code.
+  provider    String
+  /// The host's numeric user id, as text.
+  hostUserId  String
+  /// Last known login; refreshed when the host reports a rename.
+  login       String
+  linkedAt    DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@id([principalId, provider])
+  @@unique([provider, hostUserId])
+}
+
+/// An in-flight host identity link (link_host_account): the OAuth state and
+/// PKCE verifier, then, after the host's callback, the verified user and the
+/// hash of the one-time confirmation code the same principal must submit.
+/// Lives 10 minutes.
+model HostIdentityLinkRequest {
+  id           String    @id @default(cuid())
+  principalId  String
+  principal    Principal @relation(fields: [principalId], references: [id], onDelete: Cascade)
+  provider     String
+  /// sha256 of the OAuth state; the state itself is never stored.
+  stateHash    String    @unique
+  /// PKCE verifier: useless without the authorization code and the client secret.
+  codeVerifier String
+  hostUserId   String?
+  login        String?
+  /// sha256 of the confirmation code shown on the callback page.
+  confirmHash  String?
+  /// Wrong confirmation codes submitted; the request is dead at 5.
+  attempts     Int       @default(0)
+  callbackAt   DateTime?
+  expiresAt    DateTime
+  createdAt    DateTime  @default(now())
+
+  @@index([principalId])
+  @@index([expiresAt])
+}
+
+/// Which issue-tracker projects (Jira today) a native agent may act on, and
+/// which issue events trigger it. Admin-approved in phase 1 (no way to verify
+/// an owner's Jira access). See
+/// docs/private/2026-09-30-jira-issue-tracker-design.md §3.
+model AgentIssueProject {
+  id                    String   @id @default(cuid())
+  agentId               String
+  agent                 Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  /// "jira" today; validated in code.
+  provider              String
+  /// Upper-case Jira project key.
+  projectKey            String
+  /// "read" or "write".
+  access                String
+  /// Subset of "created", "transitioned", "labeled", "assigned", "mention".
+  triggers              String[] @default([])
+  /// With "transitioned": the status names (case-insensitive) that trigger.
+  triggerStatuses       String[] @default([])
+  /// With "labeled": the labels whose addition triggers.
+  triggerLabels         String[] @default([])
+  /// Optional JQL the issue must also match for any trigger.
+  jqlFilter             String?
+  /// Jira accountIds whose @-mention or assignment may trigger (required for those triggers).
+  trustedAccountIds     String[] @default([])
+  /// Optional project role that the agent's comments are restricted to.
+  commentVisibilityRole String?
+  /// Target status names (case-insensitive) jira_transition may move issues to. Empty = no transitions.
+  allowedTransitions    String[] @default([])
+  /// Field ids jira_update_fields may change ("labels", "components", "priority", "customfield_NNNNN"). Empty = none.
+  writableFields        String[] @default([])
+  /// Issue link type names (case-insensitive) jira_link_issues may create. Empty = linking off.
+  allowedLinkTypes      String[] @default([])
+  /// Status to move the issue to when a pull request for it opens (a control-plane move, not gated by allowedTransitions). Null = none.
+  onPullRequestOpened   String?
+  /// Status to move the issue to when a pull request for it merges. Null = none.
+  onPullRequestMerged   String?
+  /// Issue type names (case-insensitive) jira_create_issue may create. Empty = creation off.
+  creatableIssueTypes   String[] @default([])
+  /// Cap on issues one run may create in this project. Null = no cap.
+  maxNewIssuesPerRun    Int?
+  authorizedById        String
+  authorizedAt          DateTime @default(now())
+  createdAt             DateTime @default(now())
+
+  @@unique([agentId, provider, projectKey])
+  @@index([provider, projectKey])
+}
+
+/// Dedupe record: an issue wardby created for a fingerprint (several over time — regressions).
+model IssueFingerprint {
+  id              String   @id @default(cuid())
+  issueProvider   String
+  projectKey      String
+  /// sha256 hex of the agent- or control-plane-supplied fingerprint (raw value never stored).
+  fingerprintHash String
+  issueKey        String
+  agentId         String
+  createdByRunId  String?
+  seenCount       Int      @default(1)
+  firstSeenAt     DateTime @default(now())
+  lastSeenAt      DateTime @default(now())
+
+  @@unique([issueProvider, issueKey])
+  @@index([issueProvider, projectKey, fingerprintHash])
+  @@index([createdByRunId])
+}
+
+/// A pull request wardby opened for a tracker issue (the Jira -> code bridge). Provider-neutral on both sides.
+/// Deliberately no foreign keys to Agent or Run: audit-style rows that survive agent/run deletion.
+model IssuePullRequest {
+  id            String   @id @default(cuid())
+  /// "jira"
+  issueProvider String
+  issueKey      String
+  /// "github" today; "bitbucket" next.
+  codeProvider  String
+  repository    String
+  number        Int
+  url           String
+  /// The issue-linked agent whose run tree opened it (the parent native agent).
+  agentId       String
+  /// The coding run that opened it (continuePriorRun target for follow-ups).
+  openedByRunId String
+  /// "open" | "merged" | "closed"
+  state         String   @default("open")
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+
+  @@unique([codeProvider, repository, number, issueProvider, issueKey])
+  @@index([issueProvider, issueKey])
+  /// The admin viewer's outcome lookup by run.
+  @@index([openedByRunId])
+}
+
+/// The status comment wardby posts on the Jira issue whose event started this
+/// run ("working on it"), edited with the outcome when the run ends.
+model RunIssueStatus {
+  runId          String    @id
+  run            Run       @relation(fields: [runId], references: [id], onDelete: Cascade)
+  provider       String
+  issueKey       String
+  /// Null until the "working on it" comment is posted.
+  commentId      String?
+  visibilityRole String?
+  createdAt      DateTime  @default(now())
+  completedAt    DateTime?
+
+  @@index([completedAt])
+}
+
+/// Latest known state of an issue/epic in an external tracker (Jira, later
+/// Linear). Shared by every run attributed to it; titles are refreshed by the
+/// next snapshot, so reports always show current names.
+model WorkItem {
+  id           String           @id @default(cuid())
+  /// "jira" | "linear" | ...
+  provider     String
+  /// PAY-241, ENG-123
+  key          String
+  title        String?
+  type         String?
+  url          String?
+  /// Jira project / Linear team.
+  scopeKey     String
+  /// The current parent (epic or parent issue), refreshed on each snapshot.
+  parentKey    String?
+  /// "epic" | "parent" | ...
+  parentKind   String?
+  /// Last successful snapshot; null = key-only (never snapshotted).
+  refreshedAt  DateTime?
+  createdAt    DateTime         @default(now())
+  updatedAt    DateTime         @updatedAt
+  attributions RunAttribution[]
+
+  @@unique([provider, key])
+  @@index([provider, parentKey])
+  @@index([provider, scopeKey])
+}
+
+/// Which work item a run's cost belongs to, with its parent frozen as of
+/// dispatch. Written in dispatchRun's persist transaction; child runs copy
+/// their parent's row (source "inherited"). Control-plane data only.
+model RunAttribution {
+  runId          String   @id
+  run            Run      @relation(fields: [runId], references: [id], onDelete: Cascade)
+  workItemId     String
+  workItem       WorkItem @relation(fields: [workItemId], references: [id])
+  parentKeyAtRun String?
+  /// issue_event | linked_pr | explicit | inherited
+  source         String
+  createdAt      DateTime @default(now())
+
+  @@index([workItemId])
+  @@index([parentKeyAtRun])
+}
+
+/// Per-run, per-model usage by priced token kind. Sum of costUsd over a
+/// run's rows equals Run.costUsd (to Run.costUsd's 6 decimal places).
+model RunModelUsage {
+  runId             String
+  run               Run     @relation(fields: [runId], references: [id], onDelete: Cascade)
+  model             String
+  /// Input tokens NOT served from cache (LlmUsage.inputTokens - cachedInputTokens).
+  freshInputTokens  Int     @default(0)
+  cachedInputTokens Int     @default(0)
+  cacheWriteTokens  Int     @default(0)
+  outputTokens      Int     @default(0)
+  costUsd           Decimal @default(0) @db.Decimal(18, 10)
+
+  @@id([runId, model])
+}
+
+/// A deployment's override of the shipped model catalog
+/// (src/providers/llm/catalog-shipped.ts), written by set_model /
+/// disable_model (models:admin). A row fully replaces the shipped entry with
+/// the same key; enabled=false removes the model; a row with no shipped match
+/// adds one. Rates are the provider's exact published numbers (sourceUrl).
+model ModelCatalogEntry {
+  provider           String
+  modelId            String
+  enabled            Boolean
+  encoding           String
+  inputPerMTok       Float
+  outputPerMTok      Float
+  cachedInputPerMTok Float
+  cacheWritePerMTok  Float
+  efforts            String[]
+  thinkingMode       String
+  sourceUrl          String
+  updatedBy          String
+  createdAt          DateTime @default(now())
+  updatedAt          DateTime @updatedAt
+
+  @@id([provider, modelId])
+}