mandrel 1.73.0 → 1.75.0

package/.agents/scripts/lib/orchestration/column-sync.js

@@ -35,6 +35,7 @@
  */
 
 import { AGENT_LABELS } from '../label-constants.js';
+import { resolveProjectMeta } from './project-meta-resolver.js';
 
 export const LABEL_TO_COLUMN = Object.freeze({
   [AGENT_LABELS.REVIEW_SPEC]: 'Todo',
@@ -141,49 +142,29 @@ export class ColumnSync {
   async #loadMeta() {
     if (this._meta !== null) return this._meta || null;
     try {
-      let project;
-      if (this.projectOwner) {
-        // When the project is owned by a different account than the
-        // authenticated viewer, `viewer.projectV2` returns null. Use
-        // `user(login: $owner).projectV2` instead. (Story #3560)
-        const data = await this.provider.graphql(
-          `
-          query($owner: String!, $number: Int!) {
-            user(login: $owner) {
-              projectV2(number: $number) {
-                id
-                field(name: "Status") {
-                  ... on ProjectV2SingleSelectField {
-                    id
-                    options { id name }
-                  }
-                }
-              }
+      // Resolve the board by walking the owner-type ladder
+      // (organization → user → viewer) via the shared resolver so the
+      // org-owned path can't drift from `workflow-audit.js`. The Status
+      // single-select field is projected alongside the board id in one
+      // round-trip. (Story #4237; org-owner support extends the
+      // user/viewer ladder added in #3560.)
+      const project = await resolveProjectMeta({
+        provider: this.provider,
+        // Prefer the explicit `github.projectOwner`; fall back to the repo
+        // owner so an org-owned board still gets a login to scope
+        // `organization(login:)` / `user(login:)` by even when no separate
+        // projectOwner is configured. `viewer` is always the final rung.
+        owner: this.projectOwner ?? this.provider.owner ?? null,
+        projectNumber: this.projectNumber,
+        projectFields: `
+          id
+          field(name: "Status") {
+            ... on ProjectV2SingleSelectField {
+              id
+              options { id name }
             }
           }`,
-          { owner: this.projectOwner, number: this.projectNumber },
-        );
-        project = data?.user?.projectV2;
-      } else {
-        const data = await this.provider.graphql(
-          `
-          query($number: Int!) {
-            viewer {
-              projectV2(number: $number) {
-                id
-                field(name: "Status") {
-                  ... on ProjectV2SingleSelectField {
-                    id
-                    options { id name }
-                  }
-                }
-              }
-            }
-          }`,
-          { number: this.projectNumber },
-        );
-        project = data?.viewer?.projectV2;
-      }
+      });
       const field = project?.field;
       if (!project || !field) {
         this._meta = false;

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-discriminator.js

@@ -45,7 +45,7 @@
  * @property {string}  [reason]   Structured reason code when allowed=false.
  */
 
-import { AGENT_LABELS } from '../label-constants.js';
+import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
 
 /**
  * Execution-signal labels that block Close. Stored as a frozen Set for
@@ -245,6 +245,57 @@ export class LabelAllowListViolation extends Error {
   }
 }
 
+/**
+ * Error class thrown synchronously by `assertStoryTypeLabel` when a Story
+ * create operation carries no `type::story` label. Named distinctly from
+ * `LabelAllowListViolation` so callers can route it separately.
+ *
+ * The class carries structured metadata (`slug`, `title`) so the error
+ * message can name the offending Story clearly.
+ */
+export class MissingTypeLabelError extends Error {
+  /**
+   * @param {string} message
+   * @param {{slug?: string, title?: string}} [meta]
+   */
+  constructor(message, meta = {}) {
+    super(message);
+    this.name = 'MissingTypeLabelError';
+    if (meta.slug !== undefined) this.slug = meta.slug;
+    if (meta.title !== undefined) this.title = meta.title;
+  }
+}
+
+/**
+ * Diff-time assertion. Throws `MissingTypeLabelError` synchronously when a
+ * Story create operation is missing the mandatory `type::story` label.
+ *
+ * Symmetric with `assertNoAgentLabels`: both fire at diff time so the plan
+ * fails loudly before the apply pipeline touches GitHub.
+ *
+ * Only validates Story create ops — Epic creates carry a different mandatory
+ * label (`type::epic`) that the caller already hard-codes at issue-creation
+ * time; the assertion is not needed there.
+ *
+ * @param {{slug?: string, title?: string, entity?: string, labels?: string[]}} op
+ * @returns {void}
+ */
+export function assertStoryTypeLabel(op) {
+  if (!op || typeof op !== 'object') return;
+  if (op.entity !== 'story') return;
+  // A create op for a Story MUST carry type::story. An absent or empty labels
+  // array means the mandatory label is missing — fail loud so the operator
+  // sees a named Story rather than a silent unlabeled issue on GitHub.
+  if (!Array.isArray(op.labels) || !op.labels.includes(TYPE_LABELS.STORY)) {
+    throw new MissingTypeLabelError(
+      `create plan for story slug=${op.slug ?? '?'} ("${op.title ?? ''}") is ` +
+        `missing the mandatory "${TYPE_LABELS.STORY}" label. Add it to the ` +
+        `spec's labels array for this Story and re-run.`,
+      { slug: op.slug, title: op.title },
+    );
+  }
+}
+
 /**
  * Diff-time assertion. Throws `LabelAllowListViolation` synchronously
  * when an operation targets an `agent::*` label. The assertion is the
@@ -329,7 +380,10 @@ export function assertNoAgentLabels(op) {
  */
 export function assertPlanLabelAllowList(plan) {
   if (!plan || typeof plan !== 'object') return;
-  for (const op of plan.creates ?? []) assertNoAgentLabels(op);
+  for (const op of plan.creates ?? []) {
+    assertNoAgentLabels(op);
+    assertStoryTypeLabel(op);
+  }
   for (const op of plan.updates ?? []) assertNoAgentLabels(op);
   // closes/relinks do not carry label payloads — nothing to assert.
 }

package/.agents/scripts/lib/orchestration/project-meta-resolver.js

@@ -0,0 +1,129 @@
+/**
+ * project-meta-resolver — shared GitHub Projects v2 owner-resolution
+ * primitive (Story #4237).
+ *
+ * Background:
+ *   Both `ColumnSync._loadMeta` (`lib/orchestration/column-sync.js`) and
+ *   `resolveProjectIdByNumber` (`lib/bootstrap/workflow-audit.js`)
+ *   needed to turn a `(owner, projectNumber)` pair into a Projects v2
+ *   board node id. Each historically resolved only **user-owned** /
+ *   `viewer`-owned boards: `viewer.projectV2(number:)` first, then
+ *   `user(login:$owner).projectV2(number:)` (Story #3560). Neither had an
+ *   `organization(login:$owner)` branch, so for an **org-owned** board
+ *   every lookup failed with `NOT_FOUND` and the `agent::*` → board
+ *   Status mirror silently no-oped (reproduced on `Beestera/swarm-os`).
+ *
+ * Fix:
+ *   A single shared resolver that walks the owner-type ladder in order —
+ *   `organization(login:$owner)` → `user(login:$owner)` → `viewer` —
+ *   returning the first board it can resolve. Centralising the ladder in
+ *   one place means the org path can never again drift between the two
+ *   call sites.
+ *
+ * The resolver issues a sub-query for the project itself (`field(name:
+ * "Status") { … }` for the column-sync caller, or a bare `id` for the
+ * workflow-audit caller). Pass the desired projection in via
+ * `projectFields`; the resolver wraps it in the right owner scope and
+ * extracts the resolved `projectV2` node.
+ */
+
+/**
+ * The owner-resolution ladder, in priority order. Each entry names the
+ * GraphQL root field and whether it requires the `$owner` variable.
+ *
+ * `organization` and `user` are keyed by `login: $owner`; `viewer` is the
+ * authenticated identity and takes no owner argument. The viewer rung is
+ * the historical default and stays last so a configured owner is always
+ * preferred over the ambient identity.
+ */
+const OWNER_SCOPES = Object.freeze([
+  { root: 'organization', needsOwner: true },
+  { root: 'user', needsOwner: true },
+  { root: 'viewer', needsOwner: false },
+]);
+
+/**
+ * Build the GraphQL document for a single owner scope.
+ *
+ * @param {{ root: string, needsOwner: boolean }} scope
+ * @param {string} projectFields — the inner `projectV2(number: $number) { … }`
+ *   selection body (everything between the braces).
+ * @returns {string}
+ */
+function buildScopedQuery(scope, projectFields) {
+  if (scope.needsOwner) {
+    return `
+      query($owner: String!, $number: Int!) {
+        ${scope.root}(login: $owner) {
+          projectV2(number: $number) {
+            ${projectFields}
+          }
+        }
+      }`;
+  }
+  return `
+    query($number: Int!) {
+      ${scope.root} {
+        projectV2(number: $number) {
+          ${projectFields}
+        }
+      }
+    }`;
+}
+
+/**
+ * Resolve a Projects v2 board node by walking the owner-type ladder.
+ *
+ * Tries `organization(login:$owner)` → `user(login:$owner)` → `viewer` in
+ * order, returning the first non-null `projectV2` node. A scope that
+ * throws (e.g. GitHub returns `NOT_FOUND` for the wrong owner type) or
+ * resolves to `null` is treated as a miss and the ladder advances to the
+ * next rung. Returns `null` when every rung misses.
+ *
+ * When `owner` is falsy, only the `viewer` rung is attempted (there is no
+ * login to scope `organization`/`user` by) — this preserves the original
+ * viewer-only behaviour for callers that never configured a project owner.
+ *
+ * @param {{
+ *   provider: { graphql: Function },
+ *   owner?: string | null,
+ *   projectNumber: number,
+ *   projectFields: string,
+ * }} args
+ * @returns {Promise<object|null>} the resolved `projectV2` node, or null.
+ */
+export async function resolveProjectMeta(args) {
+  const { provider, owner, projectNumber, projectFields } = args ?? {};
+  if (!provider || typeof provider.graphql !== 'function') {
+    throw new TypeError('resolveProjectMeta requires a provider with graphql');
+  }
+  if (typeof projectFields !== 'string' || projectFields.length === 0) {
+    throw new TypeError(
+      'resolveProjectMeta requires a projectFields selection',
+    );
+  }
+
+  for (const scope of OWNER_SCOPES) {
+    // Skip the owner-scoped rungs when no owner login is available.
+    if (scope.needsOwner && !owner) continue;
+
+    const query = buildScopedQuery(scope, projectFields);
+    const vars = scope.needsOwner
+      ? { owner, number: projectNumber }
+      : { number: projectNumber };
+
+    let data;
+    try {
+      data = await provider.graphql(query, vars);
+    } catch {
+      // Wrong owner type (NOT_FOUND), missing scope, etc. — advance the
+      // ladder rather than aborting the whole resolution.
+      continue;
+    }
+
+    const node = data?.[scope.root]?.projectV2;
+    if (node) return node;
+  }
+
+  return null;
+}

package/.agents/scripts/providers/github/project-board.js

@@ -2,11 +2,11 @@
  * GitHub Provider — ProjectBoardGateway.
  *
  * Owns the Projects V2 bootstrap surface: `resolveOrCreateProject`,
- * `ensureStatusField`, `ensureProjectViews`, `ensureProjectFields`. The
- * low-level GraphQL mutations live in `./projects-v2-graphql.js`; this
- * class threads the parent provider's `_ctx` (which carries `projectNumber`,
- * `projectOwner`, `state`, and the shared cache) into each call so the
- * legacy shim contract is preserved.
+ * `ensureStatusField`, `ensureProjectFields`. The low-level GraphQL
+ * mutations live in `./projects-v2-graphql.js`; this class threads the
+ * parent provider's `_ctx` (which carries `projectNumber`, `projectOwner`,
+ * `state`, and the shared cache) into each call so the legacy shim contract
+ * is preserved.
  *
  * Extracted from `../github.js` in Story #2462 / Task #2479. Public
  * surface on `GitHubProvider` is unchanged — every project-board method
@@ -36,10 +36,6 @@ export class ProjectBoardGateway {
     return projects.ensureStatusField(this._ctx, optionNames);
   }
 
-  async ensureProjectViews(viewDefs) {
-    return projects.ensureProjectViews(this._ctx, viewDefs);
-  }
-
   /* node:coverage ignore next */
   async ensureProjectFields(fieldDefs) {
     return projects.ensureProjectFields(this._ctx, fieldDefs);

package/.agents/scripts/providers/github/projects-v2-graphql.js

@@ -21,14 +21,8 @@ const Q_PROJ = (scope, fields) =>
 const M_PROJ = `mutation($ownerId:ID!,$title:String!){createProjectV2(input:{ownerId:$ownerId,title:$title}){projectV2{id number}}}`;
 const M_FIELD = `mutation($projectId:ID!,$name:String!,$options:[ProjectV2SingleSelectFieldOptionInput!]!){createProjectV2Field(input:{projectId:$projectId,dataType:SINGLE_SELECT,name:$name,singleSelectOptions:$options}){projectV2Field{... on ProjectV2SingleSelectField{id name}}}}`;
 const M_UPDATE = `mutation($fieldId:ID!,$name:String!,$options:[ProjectV2SingleSelectFieldOptionInput!]!){updateProjectV2Field(input:{fieldId:$fieldId,name:$name,singleSelectOptions:$options}){projectV2Field{... on ProjectV2SingleSelectField{id name}}}}`;
-// Projects V2 view creation uses the REST API — the GraphQL
-// `createProjectV2View` mutation is not generally available. Endpoints:
-//   org-owned:  POST /orgs/{org}/projectsV2/{number}/views        ({org} login)
-//   user-owned: POST /users/{user_id}/projectsV2/{number}/views   (numeric id)
-const REST_API_VERSION = '2026-03-10';
 const M_ITEM = `mutation($projectId:ID!,$contentId:ID!){addProjectV2ItemById(input:{projectId:$projectId,contentId:$contentId}){item{id}}}`;
 const F_STATUS = `id fields(first:50){nodes{... on ProjectV2SingleSelectField{id name options{id name}}}}`;
-const F_VIEWS = `id views(first:50){nodes{name}}`;
 const F_FIELDS = `id fields(first:50){nodes{... on ProjectV2Field{name} ... on ProjectV2IterationField{name} ... on ProjectV2SingleSelectField{name}}}`;
 const SCOPES_RE =
   /INSUFFICIENT_SCOPES|Resource not accessible by personal access token|your token has not been granted the required scopes/i;
@@ -106,97 +100,6 @@ async function gql(ctx, query, variables, { retry = false } = {}) {
   return retry ? withTransientRetry(run) : run();
 }
 
-/**
- * Issue a REST request against api.github.com, reusing the same token and
- * fetch seam as `gql`. Throws on non-2xx with the response body for context.
- * Pass `{ retry: true }` to retry transient network blips (idempotent calls).
- */
-async function rest(ctx, method, apiPath, body, { retry = false } = {}) {
-  const run = async () => {
-    const fetchImpl = ctx.fetchImpl ?? globalThis.fetch;
-    const response = await fetchImpl(`https://api.github.com${apiPath}`, {
-      method,
-      headers: {
-        Accept: 'application/vnd.github+json',
-        Authorization: `Bearer ${ctx.token ?? resolveToken()}`,
-        'Content-Type': 'application/json',
-        'User-Agent': 'node.js',
-        'X-GitHub-Api-Version': REST_API_VERSION,
-      },
-      ...(body ? { body: JSON.stringify(body) } : {}),
-    });
-    if (!response.ok) {
-      const text = await response.text().catch(() => '');
-      const err = new Error(
-        `[GitHubProvider] REST ${method} ${apiPath} → ${response.status}: ${text}`,
-      );
-      err.status = response.status;
-      throw err;
-    }
-    return response.json().catch(() => ({}));
-  };
-  return retry ? withTransientRetry(run) : run();
-}
-
-/**
- * Resolve an owner login to its account type and numeric id via
- * `GET /users/{login}` (which serves both users and orgs). The REST views
- * endpoint keys orgs by login but users by numeric id, so we need both.
- */
-async function resolveOwnerAccount(ctx, owner) {
-  const data = await rest(
-    ctx,
-    'GET',
-    `/users/${encodeURIComponent(owner)}`,
-    undefined,
-    { retry: true },
-  );
-  return { id: data?.id ?? null, type: data?.type ?? null };
-}
-
-/**
- * Build the candidate REST views endpoints to try, in order. Orgs key by
- * login. For user-owned projects the docs label the path param `{user_id}`
- * but it's ambiguous (numeric id vs login) and the numeric form was observed
- * to 404 — so we try the login first (mirroring the org endpoint) then fall
- * back to the numeric id, treating a 404 as "wrong param, try the next".
- */
-function viewsEndpoints(account, owner, projectNumber) {
-  if (account.type === 'Organization') {
-    return [
-      `/orgs/${encodeURIComponent(owner)}/projectsV2/${projectNumber}/views`,
-    ];
-  }
-  const candidates = [];
-  if (owner) {
-    candidates.push(
-      `/users/${encodeURIComponent(owner)}/projectsV2/${projectNumber}/views`,
-    );
-  }
-  if (account.id != null) {
-    candidates.push(`/users/${account.id}/projectsV2/${projectNumber}/views`);
-  }
-  return candidates;
-}
-
-/**
- * POST a view to the first candidate endpoint that does not 404. A 404 means
- * the path param shape was wrong (login vs numeric id) — try the next. Any
- * other status is a real failure and propagates.
- */
-async function createView(ctx, endpoints, body) {
-  let lastError = null;
-  for (const endpoint of endpoints) {
-    try {
-      return await rest(ctx, 'POST', endpoint, body, { retry: true });
-    } catch (err) {
-      lastError = err;
-      if (err.status !== 404) throw err;
-    }
-  }
-  throw lastError ?? new Error('[GitHubProvider] No views endpoint available.');
-}
-
 async function lookupProject(ctx, fragment, strict = false) {
   if (!ctx.projectNumber) return null;
   let lastError = null;
@@ -357,75 +260,6 @@ export async function ensureStatusField(ctx, optionNames) {
   }
 }
 
-export async function ensureProjectViews(ctx, viewDefs) {
-  if (!ctx.projectNumber)
-    throw new Error(
-      '[GitHubProvider] ensureProjectViews requires projectNumber.',
-    );
-  const created = [],
-    skipped = [];
-  let project;
-  try {
-    project = await lookupProject(ctx, F_VIEWS, true);
-  } catch {
-    return {
-      created,
-      skipped: viewDefs.map((view) => view.name),
-      unavailable: true,
-    };
-  }
-  if (!project)
-    throw new Error(
-      `[GitHubProvider] Project #${ctx.projectNumber} not found for ${ctx.projectOwner}.`,
-    );
-  const existingViewNames = new Set(
-    (project.views?.nodes ?? []).map((view) => view?.name).filter(Boolean),
-  );
-
-  // Resolve the owner account once to pick the right REST endpoint shape.
-  let account;
-  try {
-    account = await resolveOwnerAccount(ctx, ctx.projectOwner);
-  } catch (err) {
-    return {
-      created,
-      skipped: viewDefs.map((view) => view.name),
-      unavailable: true,
-      error: err.message,
-    };
-  }
-
-  const endpoints = viewsEndpoints(
-    account,
-    ctx.projectOwner,
-    ctx.projectNumber,
-  );
-  let unavailable = false;
-  let error;
-  for (const def of viewDefs) {
-    if (existingViewNames.has(def.name) || unavailable) {
-      skipped.push(def.name);
-      continue;
-    }
-    try {
-      await createView(ctx, endpoints, {
-        name: def.name,
-        // PROJECT_VIEW_DEFS predate REST layouts; the GraphQL path always
-        // created board views, so default to 'board' (override via
-        // `def.layout` = 'table' | 'board' | 'roadmap').
-        layout: def.layout ?? 'board',
-        ...(def.filter ? { filter: def.filter } : {}),
-      });
-      created.push(def.name);
-    } catch (err) {
-      unavailable = true;
-      error = err.message;
-      skipped.push(def.name);
-    }
-  }
-  return { created, skipped, unavailable, ...(error ? { error } : {}) };
-}
-
 export async function ensureProjectFields(ctx, fieldDefs) {
   if (!ctx.projectNumber) return { created: [], skipped: [] };
   const project = await lookupProject(ctx, F_FIELDS);

package/.agents/scripts/providers/github/tickets.js

@@ -23,6 +23,7 @@
 
 import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
 import { Logger } from '../../lib/Logger.js';
+import { TYPE_LABELS } from '../../lib/label-constants.js';
 import { addIssueToBoard } from './board-add.js';
 import { createInlineTicketCache } from './cache.js';
 import { withTransientRetry } from './errors.js';
@@ -318,13 +319,21 @@ export class TicketGateway {
       dependencies: ticketData.dependencies ?? [],
     });
 
+    // Mirror the Epic create path (issues.js:160 → `labels: TYPE_LABELS.EPIC`):
+    // always inject TYPE_LABELS.STORY so a spec that omits the labels array
+    // cannot produce an unlabeled, undispatchable Story. Dedupe to avoid
+    // duplicates when the caller already carries the label.
+    const callerLabels = ticketData.labels ?? [];
+    const labels = callerLabels.includes(TYPE_LABELS.STORY)
+      ? callerLabels
+      : [TYPE_LABELS.STORY, ...callerLabels];
     const result = await this._gh.api({
       method: 'POST',
       endpoint: `/repos/${this.owner}/${this.repo}/issues`,
       body: {
         title: ticketData.title,
         body: renderedBody,
-        labels: ticketData.labels ?? [],
+        labels,
       },
     });
     const issue = parseApiJson(result);

package/.agents/scripts/providers/github.js

@@ -130,7 +130,6 @@ const DELEGATIONS = [
   ['setMergeMethods', 'mergeMethods.setMergeMethods'],
   ['resolveOrCreateProject', 'projectBoard.resolveOrCreateProject'],
   ['ensureStatusField', 'projectBoard.ensureStatusField'],
-  ['ensureProjectViews', 'projectBoard.ensureProjectViews'],
   ['ensureProjectFields', 'projectBoard.ensureProjectFields'],
 ];
 for (const [name, target] of DELEGATIONS) {