Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

fix(tick): make the Needs-you panel the single source of truth for repeated asks

Yuting Zhongb96bb5f03f9c
diff --git a/notfair/src/server/goals/identity.ts b/notfair/src/server/goals/identity.ts
index 4d6aa7ca..93b00b7f 100644
--- a/notfair/src/server/goals/identity.ts
+++ b/notfair/src/server/goals/identity.ts
@@ -187,12 +187,15 @@ only the user can change. When you identify one, log it as a
\`decision\` action whose description STARTS WITH
\`USER ACTION REQUIRED:\` followed by the exact fix the user must
make — that prefix is a UI contract: it pins the ask in the goal
-screen's "Needs you" panel and marks the goal in the sidebar. Then
-repeat the ask in EVERY tick summary until the state provably
-changes — a finding mentioned once is a finding lost; the diary is
-your only channel to the user, and they read it in five-second
-glances. Never let a known user-action blocker live only in a
-learning.
+screen's "Needs you" panel and marks the goal in the sidebar. Every
+tick brief mirrors that panel under "## Needs you" — repeat exactly
+the asks it lists in EVERY tick summary, and ONLY those. A finding
+mentioned once is a finding lost, but an ask absent from that list
+was handled or retired, and re-raising it from memory makes the
+diary lie: if telemetry proves the problem persists after the user
+marked it handled, escalate a NEW \`USER ACTION REQUIRED\` action
+with the fresh evidence. Never let a known user-action blocker live
+only in a learning.
The same anti-drift pressure applies to your own conduct: if your
last 3 ticks were research-only while the metric is off target, the
@@ -211,10 +214,11 @@ wastes every tick, so you are REQUIRED to escalate misfit instead of
silently absorbing it. When the same failure class has been classified
unfixable-by-design on 3+ heartbeats (deliberate quota enforcement, a
customer's broken account, user-input errors), or the metric provably
-counts events outside this goal's control, put the recommendation in
-your diary summary EVERY tick until the user acts: the exact revised
-query or exclusion you propose, or the telemetry enrichment needed to
-express it. Missing measurement fields are a legitimate code mutation
+counts events outside this goal's control, escalate it as a
+\`USER ACTION REQUIRED\` decision action (the contract above): the
+exact revised query or exclusion you propose, or the telemetry
+enrichment needed to express it. It then rides every tick brief's
+"## Needs you" list — and your summaries — until the user acts. Missing measurement fields are a legitimate code mutation
in their own right — instrumenting structured error classes so the
metric CAN distinguish fixable from deliberate is often the highest-
leverage PR available to you. The user applies metric changes; your
diff --git a/notfair/src/server/goals/tick.test.ts b/notfair/src/server/goals/tick.test.ts
index d0cc6982..2309bd73 100644
--- a/notfair/src/server/goals/tick.test.ts
+++ b/notfair/src/server/goals/tick.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
-import { decideAgentTurn } from "@/server/goals/tick";
+import { buildTickMessage, decideAgentTurn, type TickContext } from "@/server/goals/tick";
+import type { Goal, GoalAction } from "@/server/db/goals";
/** Baseline: the one situation that should NOT wake the agent — an
* achieve goal mid-flight with everything inside observation windows. */
@@ -65,3 +66,49 @@ describe("decideAgentTurn", () => {
).toBe(true);
});
});
+
+/** Minimal brief context: an achieve goal mid-flight with nothing pending. */
+const briefCtx: TickContext = {
+ goal: {
+ metric_name: "fixable-error rate",
+ baseline_value: 10,
+ target_value: 1,
+ metric_direction: "down",
+ mode: "achieve",
+ deadline: null,
+ spend_envelope_usd: null,
+ } as unknown as Goal,
+ tickNumber: 92,
+ nowIso: "2026-07-21T00:00:00.000Z",
+ measurement: { ok: true, value: 3 },
+ supportReadings: [],
+ targetMet: false,
+ pastDeadline: false,
+ actionsDueForReview: [],
+ gatedActions: [],
+ gatedByOthers: [],
+ userActionRequests: [],
+ loggedSpendUsd: 0,
+ recentLearnings: [],
+ lastTick: null,
+ pullRequests: [],
+};
+
+describe("buildTickMessage — Needs you section", () => {
+ it("mirrors the open escalations verbatim as the only asks to repeat", () => {
+ const ask = {
+ id: "act-1",
+ description: "USER ACTION REQUIRED: rotate the PostHog API key",
+ } as GoalAction;
+ const msg = buildTickMessage({ ...briefCtx, userActionRequests: [ask] });
+ expect(msg).toContain("## Needs you");
+ expect(msg).toContain("[act-1] USER ACTION REQUIRED: rotate the PostHog API key");
+ expect(msg).toContain("only these");
+ });
+
+ it("with no open asks, forbids repeating retired ones from memory", () => {
+ const msg = buildTickMessage(briefCtx);
+ expect(msg).toContain("## Needs you");
+ expect(msg).toContain("do NOT repeat any earlier ask");
+ });
+});
diff --git a/notfair/src/server/goals/tick.ts b/notfair/src/server/goals/tick.ts
index aa418ff8..3f7d50ec 100644
--- a/notfair/src/server/goals/tick.ts
+++ b/notfair/src/server/goals/tick.ts
@@ -20,6 +20,7 @@ import {
listGatedActions,
listGatedActionsForOtherAgents,
listGoalLearnings,
+ listUserActionRequests,
loggedSpendTotal,
markGoalTicked,
recordMetricSnapshot,
@@ -74,6 +75,8 @@ export type TickContext = {
actionsDueForReview: GoalAction[];
gatedActions: GoalAction[];
gatedByOthers: Array<GoalAction & { agent_id: string }>;
+ /** Open USER ACTION REQUIRED escalations — the "Needs you" panel's list. */
+ userActionRequests: GoalAction[];
loggedSpendUsd: number;
recentLearnings: GoalLearning[];
lastTick: GoalTick | null;
@@ -264,6 +267,23 @@ export function buildTickMessage(ctx: TickContext): string {
lines.push("");
}
+ lines.push(
+ '## Needs you — open user asks (read from the "Needs you" panel just now; this list is the ONLY truth)',
+ );
+ if (ctx.userActionRequests.length === 0) {
+ lines.push(
+ "- none — do NOT repeat any earlier ask in your summary. An ask absent from this list was marked handled by the user or retired; if telemetry proves the problem persists, escalate a NEW `USER ACTION REQUIRED` decision action with the fresh evidence instead of re-raising from memory.",
+ );
+ } else {
+ for (const a of ctx.userActionRequests.slice(0, 10)) {
+ lines.push(`- [${a.id}] ${a.description}`);
+ }
+ lines.push(
+ "- Repeat exactly these asks in your diary summary — and only these. If one is obsolete, close it via review_goal_action rather than repeating it.",
+ );
+ }
+ lines.push("");
+
lines.push("## Recent learnings");
if (ctx.recentLearnings.length === 0) {
lines.push("- none yet — use search_learnings for older ones once they exist");
@@ -475,6 +495,7 @@ async function runClaimedTick(
actionsDueForReview,
gatedActions,
gatedByOthers: listGatedActionsForOtherAgents(goal.project_slug, goal.id, nowIso),
+ userActionRequests: listUserActionRequests(goal.id),
loggedSpendUsd: loggedSpendTotal(goal.id),
recentLearnings: listGoalLearnings(goal.id, 8),
lastTick: getLastAgentTick(goal.id),