wicked-crew-api-types 0.33.0 → 0.35.0

package/index.d.ts

@@ -426,9 +426,61 @@ export interface RosterSeat {
    * unknown seat keys, or a daemon predating the field).
    */
   signed_in?: boolean | null;
+  /**
+   * What `signed_in` MEANS for this seat (api-types 0.35.0, F-2R2-009): `signed_in` — a credential
+   * artifact is observable; `signed_out` — none is and the seat needs one (a council benches it on
+   * its first ballot; a chat refuses it up front); `not_required` — none is, but the seat answers
+   * on a free tier with no account (`free_tier` names it); `unknown` — the probe cannot tell
+   * cheaply (keychain-backed seats, unknown seat keys). Absent on a daemon predating the field.
+   */
+  auth?: SeatAuth;
+  /** Present when `auth` is `not_required`: the free tier the seat answers on. */
+  free_tier?: string;
+  /**
+   * Where the `not_required` reading came from: `registry` when the CLI's own record declared the
+   * credential requirement, `crew-heuristic` when the daemon's per-CLI table did (today's only
+   * source — the engine's `AgenticCli` declares none; a wicked-core follow-up). A reader can show
+   * the heuristic as such.
+   */
+  free_tier_source?: 'registry' | 'crew-heuristic';
+  /**
+   * Whether a council would seat AND keep this seat as far as the daemon can tell: enabled for
+   * council, runtime `health` active, `auth` not `signed_out`. The daemon's PREDICTION from its
+   * own records — the engine still convenes whatever roster it is handed and benches a seat only
+   * after it fails. Chat admission (`POST /chats` defaults) reads the same auth predicate.
+   */
+  council_eligible?: boolean;
+  /** Present when `council_eligible` is false: the one reason, in the operator's words. */
+  council_ineligible_reason?: string;
+  /**
+   * Present when THIS daemon's recent councils benched the seat: the engine's own
+   * `councilSeatFailed` evidence (`non_zero_exit` / `timed_out`, the derivative `benched` kind
+   * excluded), folded over a bounded window (`window_ms`) and cleared by the seat's next ok unit
+   * output. `council_eligible` is false while it is present.
+   */
+  council_bench?: RosterSeatCouncilBench;
   [k: string]: unknown;
 }
 
+/** `RosterSeat.council_bench` (api-types 0.35.0). */
+export interface RosterSeatCouncilBench {
+  /** Primary ballot failures inside the window. */
+  failures: number;
+  /** The last failure's `councilSeatFailed.kind`. */
+  last_kind: string;
+  /** ISO-8601 of the last failure. */
+  last_at: string;
+  /** The run the last failure happened in, when the frame named one. */
+  last_run?: string;
+  /** A bounded excerpt of the last failure's detail / stderr, when there was one. */
+  last_detail?: string;
+  /** The rolling window the failures were counted over, ms. */
+  window_ms: number;
+}
+
+/** A seat's auth reading (`RosterSeat.auth`; api-types 0.35.0). */
+export type SeatAuth = 'signed_in' | 'signed_out' | 'not_required' | 'unknown';
+
 /** Body for `POST /open` — open a file/folder with the OS default application (crew#273). */
 export interface OpenPathBody {
   /**
@@ -1785,6 +1837,40 @@ export interface SkillBaselineRecord {
   venv: SkillVenvState;
 }
 
+/**
+ * Why a skill's text cannot be followed on a non-Claude CLI (F-079, api-types 0.34.0; design W4
+ * §5.1 — the same tokens wicked-garden's own lint reports):
+ *
+ *   - `plugin-root` — the text contains `${CLAUDE_PLUGIN_ROOT}` (only Claude Code substitutes it);
+ *   - `skill-dir-var` — the text contains `${CLAUDE_SKILL_DIR}` (likewise Claude-only);
+ *   - `cwd-script` — an interpreter invokes a plugin script by a path relative to the worktree cwd
+ *     (`python3 scripts/domain/extract_loop.py`) instead of the `wicked-garden run …` launcher;
+ *   - `relative-link` — a `../` link whose target exists in the bundle (the flat `<name>/SKILL.md`
+ *     layout of every non-Claude install cannot follow it);
+ *   - `cross-skill-path` — a path (plugin-root or `../`) that lands in ANOTHER skill's directory;
+ *     the portable form names that skill (`wicked-garden-<x>`) instead;
+ *   - `requires-harness:claude` — the author declared `metadata.requires-harness: claude` in the
+ *     frontmatter: the skill genuinely needs the Claude harness (not an authoring defect).
+ */
+export type SkillPortabilityReason =
+  | 'plugin-root'
+  | 'skill-dir-var'
+  | 'cwd-script'
+  | 'relative-link'
+  | 'cross-skill-path'
+  | 'requires-harness:claude';
+
+/** Per-reason portability of a skill (F-079, api-types 0.34.0) — reported beside `portable`. */
+export interface SkillPortability {
+  /** The same value as `SkillEntry.portable`: `reasons.length === 0`. */
+  portable: boolean;
+  /** Sorted, unique. Empty when portable. */
+  reasons: SkillPortabilityReason[];
+  /** Up to five anchors, `<plugin-relative file>:<line>`, one per hit in file order — where the
+   *  offending text sits (the drawer's "why" and the operator's path to the line). */
+  evidence?: string[];
+}
+
 export interface SkillEntry {
   /** Plugin-relative directory, nested layout preserved (`skills/engineering/frontend`). Never
    *  renamed — sibling `../` links depend on it. */
@@ -1794,11 +1880,17 @@ export interface SkillEntry {
    *  daemon knows (core drop-ins, crew-generated, user-registered) or a skill one of those names in
    *  its SKILL.md (repo-learn → search, mem). Disabling or renaming it is blocking. */
   core: boolean;
-  /** `false` when the skill's files resolve `${CLAUDE_PLUGIN_ROOT}`, invoke a script relative to
-   *  the cwd (`python3 -u scripts/x.py`, `./scripts/x`, …), or link `../` — Claude-only by nature:
-   *  excluded from the snapshot's `views/copilot/` and from the per-launch skill lists core builds
-   *  for the other CLIs. `portable` is the admission key for every non-Claude view (design v3.2). */
+  /** `false` when the skill's files carry any `SkillPortabilityReason` — Claude-only: excluded from
+   *  the snapshot's `views/copilot/` and from the per-launch skill lists core builds for the other
+   *  CLIs. `portable` is the admission key for every non-Claude view (design v3.2); the reasons
+   *  are reported per token in `portability` (api-types 0.34.0). wicked-garden ≥ 12.33 authors
+   *  every skill portably, so a non-portable row there is either an older garden or a skill that
+   *  declares `requires-harness: claude`. */
   portable: boolean;
+  /** Per-reason portability (F-079, api-types 0.34.0): `portable` again, the sorted unique
+   *  `reasons`, and up to five `file:line` anchors. Absent on manifests written by a daemon older
+   *  than 0.7.30 — treat absence as "reasons unknown". */
+  portability?: SkillPortability;
   /** Manifest state, orthogonal to content: a disabled skill's files stay in `effective/` and are
    *  excluded from the next published snapshot. Reset never flips it. */
   enabled: boolean;
@@ -1917,6 +2009,9 @@ export type SkillFindingKind =
   | 'core-rename'
   | 'core-missing'
   | 'support-file-edit'
+  /** A write made (or would make) the skill non-portable — a WARNING, one finding PER REASON per
+   *  file (api-types 0.34.0), anchored `file:line` at the first hit and carrying the token in
+   *  `portabilityReason`. The skill leaves every non-Claude delivery view. */
   | 'non-portable'
   /** A `${CLAUDE_PLUGIN_ROOT}/<p>` or `../<p>` reference in an enabled skill's files that does not
    *  resolve inside the would-be snapshot. Severity follows the TARGET (design v3.4 §1): a reference
@@ -2002,6 +2097,9 @@ export interface SkillConflictFinding {
   evidence: string;
   /** Why it matters. */
   explanation: string;
+  /** On a `non-portable` finding: WHICH reason this finding reports (one finding per reason per
+   *  file). Absent on every other kind (api-types 0.34.0). */
+  portabilityReason?: SkillPortabilityReason;
 }
 
 /** `POST /skills/analyze` 200 body (a PURE dry run of the publish validation: nothing persisted,
@@ -2779,6 +2877,20 @@ export interface CodeGraphData {
   stats: { nodeCount: number; edgeCount: number; fileCount: number };
 }
 
+/**
+ * `GET /repos/:id/graph` → 200 (api-types 0.35.0, F-2R2-005). `graph: null` = the repo's code
+ * graph has not been built (nothing at its registered graph path) — and `reason` says WHY, so a
+ * consumer of this route alone can tell "not indexed" from "empty": the same finding text the
+ * repos wire carries when the engine has one (`finding` — e.g. `in_tree_code_graph_ignored`: a
+ * checkout's in-tree graph is ignored and no live graph exists yet; re-run onboarding), else the
+ * daemon's own sentence. Both absent when `graph` is present.
+ */
+export interface RepoGraphResponse {
+  graph: CodeGraphData | null;
+  reason?: string;
+  finding?: RepoFinding;
+}
+
 export interface GitCommit {
   sha: string;
   shortSha: string;
@@ -3357,8 +3469,10 @@ export interface ChatScope {
   cwd: string;
   /** Whether a READ-ONLY estate MCP over a code graph is attached, and why / why not. `repoLabel`
    *  is the estate label the project graph indexes the (single) scoped repo under, when the
-   *  binding was repo-bound — informational; the engine binds by graph path. */
-  graph: { bound: boolean; reason: string; repoLabel?: string };
+   *  binding was repo-bound — informational; the engine binds by graph path. `action` (api-types
+   *  0.35.0, F-2R2-008) names the UI action that would change a `bound: false` outcome, when one
+   *  would: `projects.graph.refresh` = build the project graph from the project page. */
+  graph: { bound: boolean; reason: string; repoLabel?: string; action?: ProjectGraphAction };
   /** `crew.repo` members of the project whose registry record is gone — named, not readable. */
   dangling: string[];
 }
@@ -3370,6 +3484,18 @@ export interface ChatSeatOutcome {
   error?: string;
 }
 
+/**
+ * One seat a `POST /chats` did NOT seat, and why (api-types 0.35.0, F-2R2-007): a DEFAULT seat the
+ * daemon's admission dropped before the engine saw it (signed out; not admissible to a scoped chat
+ * — its ACP adapter asks no permissions and arms no sandbox, or it has no ACP adapter), or a
+ * REQUESTED seat (`clis`) the engine refused (`ChatSeatOutcome.ok: false`, its `error` repeated
+ * here as `reason`). One list for the scope card and the thread to read.
+ */
+export interface ChatSeatRefusal {
+  cliKey: string;
+  reason: string;
+}
+
 /** `POST /chats` → 201. */
 export interface ChatOpenResponse {
   chatId: string;
@@ -3378,8 +3504,27 @@ export interface ChatOpenResponse {
   scope: ChatScope;
   /** Present when the chat opened but its `crew.chat` filing into `projectId` failed. */
   projectAttachError?: string;
+  /** Every seat that was asked for or defaulted and is NOT in `seats` as warm, with its reason
+   *  (api-types 0.35.0). Empty when every seat warmed; absent on a daemon predating the field. */
+  refused?: ChatSeatRefusal[];
 }
 
+/**
+ * A seat refused at `POST /chats` (api-types 0.35.0, F-2R2-007). DAEMON-SYNTHETIC: broadcast
+ * straight to `/ws` once per refused seat, right after the open, so the chat thread can say why a
+ * seat is missing (the studio's `chat-scope-admission` copy) — the engine emits nothing for a seat
+ * it never saw. `chat` names the chat the way the engine's `chatClosed` does; `project_id` rides
+ * along when the chat was filed. An anonymous object type on purpose, like the stall frames, so it
+ * flows through `CoreEvent`-typed seams.
+ */
+export type ChatSeatRefusedFrame = {
+  type: 'chatSeatRefused';
+  chat: string;
+  cliKey: string;
+  reason: string;
+  project_id?: string;
+};
+
 /** One live chat on `GET /chats` (FINDING-027 gap 4; scope fields with crew#502). */
 export interface ChatSummary {
   chatId: string;
@@ -3476,11 +3621,21 @@ export interface ProjectGraphRepo {
 }
 
 /** `GET /projects/:id/graph` — what the project graph holds and what it cannot answer. */
+/** The UI action that resolves a project-graph state or a declined binding (api-types 0.35.0):
+ *  `projects.graph.refresh` = `POST /projects/:id/graph/refresh`, surfaced as the project page's
+ *  build/refresh control. */
+export type ProjectGraphAction = 'projects.graph.refresh';
+
 export interface ProjectGraphStatus {
   projectId: string;
   state: ProjectGraphState;
-  /** One sentence naming the state's cause and its remedy. Always present, never empty. */
+  /** One sentence naming the state's cause and its remedy, in the operator's words — never a raw
+   *  route (F-2R2-008); the route rides on `action`. Always present, never empty. */
   detail: string;
+  /** Present when one UI action resolves the state (today: `not-indexed` with registered members
+   *  → `projects.graph.refresh`). Absent when no single action does (dangling-only members, no
+   *  members, or a graph that is already built). api-types 0.35.0. */
+  action?: ProjectGraphAction;
   /** Absolute path of the co-located database; `null` when there is none to point at. */
   dbPath: string | null;
   repos: ProjectGraphRepo[];
@@ -4036,16 +4191,24 @@ export interface DiagnosticsGovernanceDeadletters {
   /** `true` when the fold stopped at its byte cap — `count` is then a floor. */
   truncated: boolean;
   /** The pre-fix outbox under HOME (`~/.something-wicked/wicked-apps/emit-outbox.ndjson`) when it exists and is
-   *  non-empty — events earlier daemons on this host spooled there; `null` otherwise. Reported, never written. */
-  legacyOutbox: { path: string; bytes: number } | null;
+   *  non-empty — events earlier daemons on this host spooled there; `null` otherwise. Reported, never written.
+   *  `scope` (api-types 0.35.0, F-2R2-006): `own` = this daemon runs in that HOME's default state home, so the
+   *  file is its own earlier versions' outbox (the finding is a warning with the replay recipe); `host` = this
+   *  daemon's state home is isolated, so the file — shared by every daemon on the host — cannot be attributed
+   *  to it (an `info` finding with a read-only `--dry-run` inspect recipe and no replay). REQUIRED, deliberately:
+   *  the daemon always attributes the file it reports, so a `legacyOutbox` object without `scope` never leaves a
+   *  daemon shipping this contract; a skin that talks to an OLDER daemon must treat the whole `legacyOutbox`
+   *  object as best-effort (it predates the attribution), not the field alone. */
+  legacyOutbox: { path: string; bytes: number; scope: 'own' | 'host' } | null;
 }
 
 /** One governance finding. `governance.store` (error) = no store resolved, every emit dead-letters;
- *  `governance.deadletter` (error) = the outbox holds entries; `governance.legacy-outbox` (warning) =
- *  the pre-fix HOME outbox exists. Every message names the replay command. */
+ *  `governance.deadletter` (error) = the outbox holds entries; `governance.legacy-outbox` = the pre-fix
+ *  HOME outbox exists — `warning` with the replay command when it is this daemon's own, `info` with none
+ *  when it is shared across the host's daemons and not this one's (api-types 0.35.0). */
 export interface DiagnosticsGovernanceFinding {
   kind: 'governance.store' | 'governance.deadletter' | 'governance.legacy-outbox';
-  severity: 'warning' | 'error';
+  severity: 'info' | 'warning' | 'error';
   message: string;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",