Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

20.8 KB
Raw Blame
/**
 * Goal-fidelity follow-up — file the finding, and/or queue the fix.
 *
 * The goal-fidelity gate (`lib/goalFidelity.js`, run from `agentFinalization`)
 * answers "did this run ship what was asked?". Until now a `rethink` verdict
 * held the run and raised a Review Hub alert, and that was the end of it: the
 * finding lived in one install's run record, where it could only be acted on by
 * the person who happened to open the agent card.
 *
 * This module is the durable half. On a verdict the user configured as
 * actionable it can:
 *
 *  - FILE the finding on whichever tracker the project actually uses — GitHub,
 *    GitLab, or JIRA, resolved from the app's own `workTracker` so the issue
 *    lands where a claim would read it; and/or
 *  - QUEUE a CoS follow-up task so an agent reconciles it without a human
 *    relaying the finding by hand.
 *
 * The two are independent switches. Filing first means the queued task can name
 * the issue and run the project's normal claim flow instead of re-deriving the
 * work from prose.
 *
 * The queued task is told to CHECK THE FINDING before acting on it. A verdict is
 * one local model's reading of a diff it saw without the repository, and an
 * agent told only to reconcile will reconcile — inventing a change to satisfy a
 * finding that had nothing behind it. When the objective turns out to have been
 * delivered, the investigator reports the blind spot instead
 * (`services/goalFidelityCalibration.js`), which queues the fix for the detector
 * rather than for the run. The instructions come from
 * `lib/goalFidelityCalibration.js`; this module supplies the loopback API base,
 * which is the one half of it a pure builder cannot resolve.
 *
 * DUPLICATE SUPPRESSION is the load-bearing part, because the producer is a
 * scheduled unattended loop: a perpetual task that keeps drifting the same way
 * would otherwise file the same issue every cadence, forever. Two guards, both
 * keyed on the one fingerprint `lib/goalFidelityFollowUp.js` derives:
 *
 *  1. the issue side lists this feature's own marker LABEL across every issue
 *     STATE and reads the fingerprint back out of the rows. A label is a direct
 *     field filter — no index lag (a full-text search has minutes of it on both
 *     GitHub and JIRA, which is exactly when a schedule re-runs), every state
 *     (so an issue a human CLOSED is not re-filed), and a page bounded by our
 *     own issues rather than by the repo's whole backlog;
 *  2. the queued task goes through `fileInvestigationTask`, inheriting the
 *     shared fingerprint dedup, circuit breaker, and loop policy.
 *
 * FAIL-CLOSED on the issue side, on purpose and against the usual convention: a
 * tracker we could not read is NOT "nothing is filed". That is exactly how a
 * transient `gh` blip files a duplicate. Refusing to file costs one missed
 * issue on a finding that will recur; filing blind costs a tracker.
 *
 * Nothing here can fail a run. `agentFinalization` calls this after the verdict
 * is decided, records what happened, and proceeds either way.
 */

import { execGh } from './github.js';
import { execGlabJson } from './gitlab.js';
import { resolveForgeExecOptions } from './forgeExecOptions.js';
import { PORTOS_APP_ID, getAppById } from './apps.js';
import { getSettings } from './settings.js';
import { fileInvestigationTask } from './investigationTaskProducer.js';
import { fileForgeIssue, probeForgeReachability, scrubForgeIssueText } from './appIssues.js';
import { investigationOutcome } from '../lib/investigationTasks.js';
import { forgeCliForTracker, resolveAppForgeTarget } from '../lib/workTracker.js';
import { safeJSONParse } from '../lib/fileUtils.js';
import { boundedErrorMessage } from '../lib/errorHandler.js';
import { localApiBaseUrl } from '../lib/networkExposure.js';
import { buildGoalFidelityFalsePositiveReportBlock } from '../lib/goalFidelityCalibration.js';
import {
  GOAL_FIDELITY_ISSUE_LABEL,
  GOAL_FIDELITY_ISSUE_LABEL_SPEC,
  buildGoalFidelityFollowUpTask,
  buildGoalFidelityIssue,
  explainGoalFidelityPublicationRefusal,
  goalFidelityFingerprint,
  goalFidelityFollowUpApplies,
  goalFidelityIssueMarker,
  issueMatchesGoalFidelityMarker,
  resolveGoalFidelityFollowUp,
} from '../lib/goalFidelityFollowUp.js';

/** Rows per request for the label-filtered duplicate listing. */
const PAGE_LIMIT = 100;
/**
 * Hard ceiling on how many of our own filed issues the duplicate scan will read.
 *
 * `gh issue list --limit` paginates internally, so GitHub reaches this in one
 * call; GitLab and JIRA page up to it. A tracker that has this many
 * goal-fidelity issues on one repo is not a backlog, it is a runaway — and the
 * scan says so (below) rather than reading a truncated page as "nothing filed".
 */
const SCAN_LIMIT = 1_000;

/**
 * The managed-app record whose tracker this finding belongs on.
 *
 * A task with no `metadata.app` is PortOS's own work — and that resolves to the
 * REAL `PORTOS_APP_ID` record (always seeded by `loadApps`), not to a
 * `{ repoPath: ROOT_DIR }` literal. The three fields a literal would drop are
 * the three that decide where the issue lands: `workTracker` (an install that
 * pinned PortOS to JIRA would otherwise get a GitHub issue nothing will ever
 * claim), `forgeAccount` (the wrong credentials on a multi-account install),
 * and `jira` (without it the JIRA arm is structurally unreachable for PortOS's
 * own tasks).
 */
async function resolveFollowUpRepo(task) {
  const app = await getAppById(task?.metadata?.app || PORTOS_APP_ID).catch(() => null);
  return app?.repoPath ? app : null;
}

/**
 * Everything a forge call for this app needs, resolved ONCE.
 *
 * `resolveForgeExecOptions` is neither cached nor cheap — it shells out for the
 * origin remote, then `gh auth status` / `gh auth token`, plus `gh api user`
 * when the app pins a forge account. Resolving it per call made the list and
 * the create each pay for it; worse, the create ran with no options at all, so
 * an app pinned to a non-ambient account filed (or 404'd) under the wrong
 * login — the exact failure `resolveForgeExecOptions` exists to prevent.
 *
 * `glab` resolves its project from the working directory rather than a token
 * overlay, so only GitHub passes a repo path here.
 */
const resolveForgeContext = (app, tracker) => resolveForgeExecOptions(
  tracker === 'github' ? app.repoPath : null,
  { forgeAccount: app.forgeAccount },
);

/**
 * Every issue this feature has ever filed on this tracker, in one normalized
 * `{ number, title, body, url }` shape — or `null` when the tracker could not
 * be read.
 *
 * Filtered by LABEL across every STATE, which is what makes the dedup sound:
 *
 * - a label is a direct field filter, so unlike a full-text search it has no
 *   index lag — and the lag window (minutes, on both GitHub and JIRA) is
 *   exactly when a scheduled task re-runs and would re-file;
 * - every state, so an issue a human already CLOSED is still found and not
 *   re-filed;
 * - and it bounds the page by the thing we care about rather than by the
 *   tracker's whole backlog, so a busy repo cannot push our own issues off the
 *   end of the page and silently read as "nothing filed".
 *
 * The three trackers disagree about field names (`iid` / `key`, `description`
 * for the body, `summary` for a JIRA title). They are reconciled here, so the
 * matcher and the result have one shape to read.
 */
async function listFiledIssues({ app, target, tracker, exec }) {
  if (tracker === 'github') {
    // `gh issue list --limit N` pages internally up to N, so one call suffices.
    const raw = await execGh([
      'issue', 'list', '--repo', target.repoSpec,
      '--label', GOAL_FIDELITY_ISSUE_LABEL, '--state', 'all',
      '--limit', String(SCAN_LIMIT), '--json', 'number,title,body,url',
    ], undefined, { cwd: exec.cwd, env: exec.env }).catch((err) => {
      console.error(`❌ goal-fidelity follow-up: gh issue list failed for ${target.repoSpec}: ${err.message}`);
      return null;
    });
    const rows = safeJSONParse(raw, null);
    return Array.isArray(rows) ? rows : null;
  }

  if (tracker === 'gitlab') {
    // `--all` is every STATE, not every page — glab caps a page at 100, so the
    // pages are walked until one comes back short. Without the walk, the 101st
    // goal-fidelity issue pushes an older fingerprint off the only page read and
    // the scheduled task re-files it every cadence.
    const all = [];
    for (let page = 1; all.length < SCAN_LIMIT; page += 1) {
      const { rows } = await execGlabJson(
        ['issue', 'list', '--label', GOAL_FIDELITY_ISSUE_LABEL, '--all',
          '--per-page', String(PAGE_LIMIT), '--page', String(page)],
        app.repoPath,
      );
      if (!Array.isArray(rows)) return null;
      all.push(...rows.map((row) => ({
        number: row?.iid ?? null,
        title: row?.title || '',
        body: row?.description || '',
        url: row?.web_url || '',
      })));
      if (rows.length < PAGE_LIMIT) break;
    }
    return all;
  }

  // JIRA. The project is scoped explicitly — a label match across every project
  // the token can see would dedupe one app's finding against another's.
  // `jira.js` is imported lazily here and in the creator: only a JIRA-tracked
  // app reaches it, and a static edge would put the whole JIRA client graph on
  // the closure of every suite reaching agent finalization (server/AGENTS.md
  // "Import scoping").
  const { searchIssues, escapeJql } = await import('./jira.js');
  const jql = `project = "${escapeJql(app.jira.projectKey)}" AND labels = "${escapeJql(GOAL_FIDELITY_ISSUE_LABEL)}"`;
  const rows = await searchIssues(app.jira.instanceId, jql, {
    fields: 'summary,description,status',
    maxResults: SCAN_LIMIT,
  }).catch((err) => {
    console.error(`❌ goal-fidelity follow-up: JIRA issue search failed for ${app.jira.projectKey}: ${err.message}`);
    return null;
  });
  if (!Array.isArray(rows)) return null;
  return rows.map((row) => ({
    number: row?.key ?? null,
    title: row?.summary || '',
    body: row?.description || '',
    url: row?.url || '',
  }));
}

/** Create the marker label, then the issue — the exec half shared by every forge filer (#7687). */
function createForgeIssue({ app, target, tracker, exec, title, body }) {
  const cli = forgeCliForTracker(tracker);
  return fileForgeIssue({
    cli, cwd: exec.cwd, env: exec.env, repoPath: app.repoPath,
    repo: cli === 'glab' ? null : target.repoSpec,
    title, body,
    labels: [{ name: GOAL_FIDELITY_ISSUE_LABEL, ...GOAL_FIDELITY_ISSUE_LABEL_SPEC }],
  });
}

/**
 * Create the JIRA ticket for one finding, in the same `{ ok, number, url }`
 * shape. It carries the same marker label as its forge siblings — that label is
 * what the next run's duplicate check filters on, so a ticket filed without it
 * would be invisible to the dedup and re-filed every cadence.
 */
async function createJiraIssue({ app, title, body }) {
  const { createTicket } = await import('./jira.js');
  const created = await createTicket(app.jira.instanceId, {
    projectKey: app.jira.projectKey,
    summary: title,
    description: body,
    issueType: app.jira.defaultIssueType || 'Task',
    labels: [GOAL_FIDELITY_ISSUE_LABEL],
  }).catch((err) => ({ success: false, error: boundedErrorMessage(err, 'JIRA ticket creation failed') }));
  return created?.success
    ? { ok: true, number: created.ticketId, url: created.url }
    : { ok: false, error: created?.error || 'JIRA ticket creation failed' };
}

/**
 * Is this app's tracker one we can file to, and does it have what it needs?
 * Returns the refusal sentence, or `null` when the file may proceed.
 */
function trackerRefusal({ app, target, tracker }) {
  if (tracker === 'jira') {
    const jira = app?.jira;
    return jira?.enabled && jira.instanceId && jira.projectKey
      ? null
      : 'this project tracks work in JIRA, but its JIRA instance and project are not configured';
  }
  if (tracker !== 'github' && tracker !== 'gitlab') {
    return `this project's work tracker is ${tracker || 'unresolved'}, which has no issue to file`;
  }
  if (!target || target.forge !== tracker) {
    return `the ${tracker} tracker does not match this repository's remote`;
  }
  return null;
}

/**
 * File one goal-fidelity finding on the app's tracker.
 *
 * One flow for all three trackers, because the sequence is the same everywhere
 * and the fail-closed rule is this feature's load-bearing invariant — stating
 * it once means a later guard cannot land on two of the three.
 *
 * @returns {Promise<{issue: object|null, error: string|null}>} `issue` carries
 *   `duplicate: true` when an existing item already tracks this fingerprint —
 *   the queued task still wants that item's URL, so a duplicate is a usable
 *   result, not a failure.
 */
async function fileFollowUpIssue({ task, review, fingerprint, context }) {
  const app = await resolveFollowUpRepo(task);
  // Named, not interpolated blind: a task with no `metadata.app` is PortOS's
  // own work, and `app 'undefined' has no configured repository` is not a
  // sentence anyone can act on.
  if (!app) return { issue: null, error: `app '${task?.metadata?.app || PORTOS_APP_ID}' has no configured repository` };

  const { tracker, target } = await resolveAppForgeTarget(app).catch(() => ({ tracker: null, target: null }));
  const refusal = trackerRefusal({ app, target, tracker });
  if (refusal) return { issue: null, error: refusal };

  // A local task can quote journals, media records, or other personal prose.
  // Scrubbing token/email shapes cannot authorize publishing that content.
  // Finalization grants this provenance only to a complete fetched claim
  // objective, and it may return only to that same tracker and repository.
  const publicationRefusal = explainGoalFidelityPublicationRefusal({
    publication: context?.publication, tracker, target,
  });
  if (publicationRefusal) return { issue: null, error: publicationRefusal };

  const exec = tracker === 'jira' ? null : await resolveForgeContext(app, tracker);
  // The reachability probe runs before anything is read or created: on an
  // unreachable forge this is one failing call instead of a list and a label
  // create that each have to time out first. Kept ahead of the duplicate read
  // below rather than folded into `fileForgeIssue`'s own probe, for the same
  // reason `persistentMindIssueCapability.js` keeps its own early probe.
  const probe = await probeForgeReachability({
    cli: forgeCliForTracker(tracker), hostname: target?.apiHost, env: exec?.customEnv,
    label: 'goal-fidelity-followup',
  });
  if (!probe.ok) return { issue: null, error: probe.error };

  // Read before writing. A failed read must NOT read as "nothing is tracked" —
  // that is exactly how a transient CLI blip files the same issue twice — so an
  // unreadable tracker refuses the file rather than proceeding blind.
  const existing = await listFiledIssues({ app, target, tracker, exec });
  if (!existing) return { issue: null, error: `could not read the ${tracker} issue list to check for duplicates; nothing was filed` };
  const duplicate = existing.find((issue) => issueMatchesGoalFidelityMarker(issue, fingerprint));
  if (duplicate) return { issue: { ...duplicate, duplicate: true }, error: null };
  // A scan that came back at the ceiling did not prove ABSENCE — it proved we
  // stopped looking. Filing here is how the 1001st issue re-files the 1st, so
  // this fails closed like every other unreadable-tracker path. Reaching this
  // at all means something upstream is filing without bound; say so.
  if (existing.length >= SCAN_LIMIT) {
    return { issue: null, error: `this repository already carries ${SCAN_LIMIT}+ '${GOAL_FIDELITY_ISSUE_LABEL}' issues, so a duplicate cannot be ruled out; nothing was filed` };
  }

  const draft = buildGoalFidelityIssue({ task, review, fingerprint, context });
  if (draft.error) return { issue: null, error: draft.error };
  // Publishing the objective adds more operator-authored text than a title.
  // The shared forge scrubber strips PII and credentials; never include
  // transcripts or unrelated metadata in this public projection.
  const title = scrubForgeIssueText(draft.title);
  const body = scrubForgeIssueText(draft.body);
  // The marker hashes the local fingerprint, so redacting dates or private
  // task text cannot change the identity the duplicate scan reads back.
  const created = tracker === 'jira'
    ? await createJiraIssue({ app, title, body })
    : await createForgeIssue({ app, target, tracker, exec, title, body });
  if (!created.ok) return { issue: null, error: created.error };
  return { issue: { number: created.number, url: created.url, title, body, duplicate: false }, error: null };
}

/**
 * Queue the CoS follow-up run.
 *
 * Goes through the shared investigation producer rather than `addTask`
 * directly, so this participates in the machinery every other failure-driven
 * task already does: the durable fingerprint dedup (a second finding for the
 * same cause folds into the open task), the rolling circuit breaker (a drift
 * storm cannot mint one agent per failure), the loop policy (a cause we already
 * queued a fix for and that came back is held for the human), and the
 * worktree + PR delivery posture.
 *
 * The producer's approval verdict rides back out with the task: the loop policy
 * can HOLD a follow-up for a human (`repeat-fingerprint`, `failure-storm`), and
 * that is the case the user most needs named — reporting "queued" for a task
 * nothing will pick up is the one wrong thing to say about it.
 */
async function queueFollowUpTask({ task, review, fingerprint, context, issue }) {
  // The API base is resolved here because it is this layer's to know: the pure
  // builder cannot read the install's live network exposure to find the loopback
  // port the agent should call.
  const falsePositiveBlock = buildGoalFidelityFalsePositiveReportBlock({
    apiBase: localApiBaseUrl(),
    findingFingerprint: fingerprint,
    taskId: task?.id,
  });
  const description = buildGoalFidelityFollowUpTask({ task, review, fingerprint, context, issue, falsePositiveBlock });
  const filed = await fileInvestigationTask({
    fingerprint,
    description,
    affectedTasks: task?.id ? [task.id] : [],
    priority: 'MEDIUM',
    context: `Auto-generated from a goal-fidelity ${review?.verdict} verdict`,
    ...(task?.metadata?.app ? { app: task.metadata.app } : {}),
  });
  // One reading of the producer's return, shared with the calibration producer:
  // a HELD task is not a queued one, and a duplicate fold is a usable outcome
  // rather than a failure. Both are easy to re-derive slightly differently.
  return investigationOutcome(filed, { subject: 'the follow-up task' });
}

/**
 * Run whatever follow-up the user configured for this verdict.
 *
 * Returns `{ ran: false }` when nothing is configured or the verdict does not
 * fire the configured trigger — the overwhelmingly common path, and the reason
 * this costs a disabled install nothing but one settings read.
 *
 * Every arm is individually fallible and individually reported: a tracker that
 * refused the file must not also cancel the queued task, because the task is
 * the arm that actually gets the work done.
 *
 * @param {{ agentId: string, task: object, review: object }} args
 * @returns {Promise<{ran: boolean, fingerprint?: string, issue?: object|null,
 *   issueError?: string|null, task?: object|null, taskError?: string|null}>}
 */
export async function runGoalFidelityFollowUp({ agentId, task, review, context = null }) {
  const settings = await getSettings().catch(() => null);
  const config = resolveGoalFidelityFollowUp(settings?.codeReview);
  if (!config) return { ran: false };
  if (!goalFidelityFollowUpApplies(review, config.trigger)) return { ran: false };

  const fingerprint = goalFidelityFingerprint(task);
  const result = { ran: true, fingerprint, issue: null, issueError: null, task: null, taskError: null };

  if (config.fileIssue) {
    const filed = await fileFollowUpIssue({ task, review, fingerprint, context })
      .catch((err) => ({ issue: null, error: boundedErrorMessage(err, 'Issue filing failed') }));
    result.issue = filed.issue;
    result.issueError = filed.error;
  }

  if (config.queueTask) {
    const queued = await queueFollowUpTask({ task, review, fingerprint, context, issue: result.issue })
      .catch((err) => {
        console.error(`❌ goal-fidelity follow-up: could not queue a task for ${agentId}: ${err.message}`);
        return null;
      });
    result.task = queued?.queued
      ? {
        id: queued.taskId,
        approvalRequired: queued.approvalRequired,
        duplicate: queued.duplicate,
        ...(queued.loopReason ? { loopReason: queued.loopReason } : {}),
      }
      : null;
    // The producer's own refusal sentence, which names the loop policy's reason
    // when it has one — "could not be queued" is the least actionable thing we
    // could say about a deliberate suppression.
    if (!result.task) result.taskError = queued?.reason || 'the follow-up task could not be queued';
  }

  return result;
}