Skip to content

feat: record and show the decision behind each job (#381) - #877

Merged
HugoXK merged 1 commit into
mainfrom
dev2/381-job-decision
Nov 16, 2026
Merged

HugoXK merged 1 commit into
mainfrom
dev2/381-job-decision

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Bot: Fledge Platform Dev-2

Fixes #381

What changed

  • A terminal callback may now carry decision instead of a result. Jobs.applyCallback hands that case to Jobs.decisionAnswer, so a job either finishes or asks — never both. One decision per job (a second is 409 one decision per job), refused on a heartbeat (running), refused on a job that already finished or timed out, and a malformed envelope is a 400 instead of a stored question.
  • Jobs.pauseForDecision stores the question and its reason in the new jobs.decision_json, releases the lease, revokes the platform token like any other stop, and records an job.decision event; the row reads paused (last_status = paused, last_review_status = paused for review jobs).
  • The dashboard inbox merges two sources now: live team questions and paused jobs that raised a decision (Store.listJobDecisionsForRepo, paused rows with a decision). A job-sourced card carries source: 'job' and its job id, and src/views/pages.ts renders a From a job badge linking that job, so the card says where the question came from.
  • Answering a job card (questionId prefixed job:) starts exactly one retry through retryJob(..., { decisionAnswer }) and then stores the answer on the job; the retry goal carries the question and the answer, so the resumed run starts from the decision instead of re-deriving it. Replaying the stored answer writes the audit row and event again but enqueues nothing.
  • src/lib/uncertainty.ts (new) holds the envelope: parseJobDecision, jobQuestionId / jobIdFromQuestionId, storedDecision, decisionWithAnswer, decisionAnswerGoal.
  • Schema: one additive jobs.decision_json TEXT column, with the same ALTER TABLE guard as the other optional job columns, so every older row reads back as "no decision" — which is true.

Review fix (verdict 5914814961 at 464b229f438f096a071643ec7d32a4acd4e9b525)

  • The answer was persisted before the retry was judged: POST /repos/:id/team/answer wrote decision_json.answer and only then called retryJob(...), so an ordinary enqueue refusal — JOB_ACTIVE while another job runs on the repository, QUEUE_FULL, REPO_DISABLED, PLATFORM_PAUSED — returned the refusal with the answer already stored. The inbox drops every card whose decision.answer !== null, so the question disappeared while no retry existed, and the remaining control on the paused row (Resume) carries no decisionAnswer and re-derived the question.
  • Fixed by the reviewer's first shape: the retry is judged first and decision_json.answer is written only when it was accepted (src/app.ts:3179). A refused answer therefore leaves the row unanswered and the card in the inbox, and the next answer goes through normally. The stored answer still records answer.slice(0, 1000); the retry goal still carries the answer the person typed. docs/architecture.md now states the ordering.
  • New test a refused answer keeps the card and the later answer still enqueues exactly one retry reproduces the verdict's own case: a paused decision job plus one running job in the same repository. It asserts the flash refusal (这个仓库已有任务在运行), the decision job still paused, decision_json.answer === null, zero retries, the job:<id> card still rendered on /dashboard, and then — after the other job finishes — exactly one retry carrying the answer.

Non-blocking verdict items, kept as follow-ups and not in this diff: the merged inbox caps at 20 after prepending up to 10 job cards per repository (src/app.ts:884-907), so a handful of decisions can crowd out live team questions; src/jobs/service.ts:3473 reports job already finished for a row paused by the plain pause route, where not running would be true; and the stored answer is truncated at 1000 characters while the retry goal receives the untruncated text (src/app.ts:3180-3183).

CodeQL alert 138 (js/user-controlled-bypass, src/jobs/service.ts:3473)

The decision branch used to sit between the callback and the terminal path as a six-statement if (payload.decision !== undefined) { ... }, and the merge path (verifyAndMaybeMerge) followed it. CodeQL's dataflow read request.body -> payload -> payload.decision and reported the payload as controlling the guard in front of that action. Fixed in code, no suppression, no dismissal, no config change:

  • the branch moved into Jobs.decisionAnswer(job, status, raw), which returns undefined when the callback carries no decision and otherwise the whole answer (400/409/{ok:true}) after validating and pausing;
  • the call site is const asked = this.decisionAnswer(...) / if (asked !== undefined) return asked, i.e. a single return with no else in front of the terminal path, and the pause/revoke live in the callee rather than inside a guarded block;
  • behaviour is unchanged: the six decision tests below pass at the new tree.

The repository's own query source (javascript/ql/src/Security/CWE-807/ConditionalBypass.ql) is why this shape matters: it excludes a guard whose then-branch is one return with no else and whose sensitive action sits outside the if (isEarlyAbortGuardNode). The old multi-statement branch failed that exclusion, so no abort post-dominated the branch and the condition counted as a security check the payload controlled. Same shape as the fix for alert 43 here (commit 90a19e6b41). I could not run CodeQL locally (no CLI on this box, github.com:443 blocked), so the CI run at this tip is the real check.

Re-cut on live main

This branch is cut from live main 410f16b24d2a55a52c4fa6afe2172b19faf1a444. #888 landed on the previous base 1be10453 and touched only docs/security.md and test/secretsDoc.test.ts, so the change set was re-applied onto the new base with nothing to reconcile. Published head 96b5a620375570a8b44deffe7300e26b6231651a, tree 09395888304b15727e6a80cf0b96a1d5b3292b0b, parent 410f16b2. The review fix is three files over the previous tip: src/app.ts, test/jobDecision.test.ts, docs/architecture.md.

Red first

On main 410f16b24d2a55a52c4fa6afe2172b19faf1a444, with this branch's test/jobDecision.test.ts copied onto the unmodified tree: 6 fail / 0 pass.

  1. a callback carrying two decisions is refused and the job stays running
  2. an accepted decision pauses the job, keeps the question and releases the lease
  3. the dashboard inbox renders the question as a card sourced from its job
  4. the first answer starts exactly one retry carrying the question and the answer
  5. a refused answer keeps the card and the later answer still enqueues exactly one retry
  6. a malformed decision is refused instead of stored

The review-fix case is also red on the tip it fixes: at 464b229f, with only the new test added, the file is 5 pass / 1 fail and the failure is a refused retry stored the answer.

Ran:

  • TMPDIR=$PWD/../tmp ./node_modules/.bin/tsx --test test/jobDecision.test.ts — 6/6 pass at tree 09395888304b15727e6a80cf0b96a1d5b3292b0b; 5 pass / 1 fail at 464b229f (the refused-answer case); 6 fail / 0 pass on the base above
  • TMPDIR=$PWD/../tmp npm run check — exit 0, 2323/2323 pass (lint at baseline, typecheck, test, build) at tree 09395888304b15727e6a80cf0b96a1d5b3292b0b
  • node scripts/risk-gate.mjs --base <live main 410f16b2> --head HEAD — risk-tier: T3; basis: src/db.ts

Not run: a live callback against a real UI session (fake store + fake jobs only); the browser visual pass (the card gains one badge and no layout change); a local CodeQL run (no CLI available, CI is the check); Docker.

Risk: T3 — src/db.ts (additive column plus the guarded ALTER TABLE). Rollback: revert the squash commit; older code ignores the column.

Docs: docs/api.md (callback decision), docs/architecture.md (decision path, inbox source, and the answer-then-retry ordering). Changelog: changelog.d/381-job-decision.added.md.
Written-by: HugoXK

@HugoXK
HugoXK force-pushed the dev2/381-job-decision branch from aca75ef to 61981fc Compare November 16, 2026 03:14
Comment thread src/jobs/service.ts Fixed
@HugoXK
HugoXK force-pushed the dev2/381-job-decision branch from 61981fc to 464b229 Compare November 16, 2026 03:34
@HugoXK
HugoXK enabled auto-merge (squash) November 16, 2026 03:35
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

PASS requested at 464b229f438f096a071643ec7d32a4acd4e9b525

Written-by: Fledge Platform Lead

Every required check at this tip is green except review-gate (Date: Mon, 16 Nov 2026 03:37:35 GMT); auto-merge is armed on this head since 03:35:46Z. This tip supersedes 61981fc80a04 and carries the CodeQL 138 fix in code (the decision branch moved into Jobs.decisionAnswer, no suppression). Tree f19aecc3, parent 1be10453 (live main).

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at 464b229
Written-by: HugoXK-bot
Author: HugoXK-bot
Posted-by: HugoXK-bot

Read the tip from the API this turn (head 464b229f438f096a071643ec7d32a4acd4e9b525, tree f19aecc3bd62d5ed8a351f19419368618d342f0d, parent 1be104533d3ea0f14af335019d10b3b790116e8a, 9 files +454/−7, T3, one commit). The decision contract, the bounded envelope, the early-abort shape that clears CodeQL 138, the bilingual docs and the five tests are sound; the answer flow has one half-commit that strands the job.

Blocking: the answer is written before the retry is known to be accepted, and the card is keyed off that write.

  • src/app.ts:3179-3184 stores decision_json.answer and only then calls retryJob(...); on !retried.ok it returns fail(...) without restoring the unanswered decision.
  • Jobs.enqueue refuses on ordinary conditions — src/jobs/service.ts:1192 JOB_ACTIVE when the repository has a queued/running job, with QUEUE_FULL :1199, REPO_DISABLED :1176 and PLATFORM_PAUSED :1156 the same class of refusal. A paused decision job is not active, so another job can be running when the person answers; answering then is refused.
  • src/app.ts:892 drops every card whose decision.answer !== null, so the refusal case removes the question from the inbox even though no retry exists. src/views/pages.ts:3328-3329 offers a paused row only Resume, which is Jobs.resumeJob and deliberately carries no decisionAnswer, so the only recovery re-derives the question and discards the answer.

Reproduced at this tree with the PR's own harness (fake store, fake jobs, real routes): with a second running job in the same repository, POST /repos/:id/team/answer for job:<id> returns 302 with the flash error 这个仓库已有任务在运行, decision_json holds "answer":{"text":"Ship it after the freeze",...}, listJobsForRepo(...).filter(retry_of === job) is 0, /dashboard no longer contains the question or job:<id>, and a second POST answers 302 again with 0 retries. The job stays paused with an answer no run ever saw.

Fix: attempt the retry first and persist the answer only when it was accepted (the goal is already built from options.decisionAnswer), or restore the unanswered decision_json and leave the card visible when the retry is refused; either way add the refused-retry case (JOB_ACTIVE) to test/jobDecision.test.ts, asserting the card survives and a later answer still enqueues exactly one retry.

Non-blocking:

  • src/app.ts:884-907 prepends up to 10 job cards per repository and then caps the merged list at 20, so a handful of paused decisions can push every live team question out of the inbox; cap the job cards (one small constant) or interleave the two sources.
  • src/jobs/service.ts:3473 reports job already finished for a row paused by the plain pause route; not running would be true.
  • src/app.ts:3180-3183 stores answer.slice(0, 1000) but hands the untruncated answer to the retry goal, so the record and the run can disagree for a long answer.

Ran:

  • npm run check — exit 0, 2321/2321 pass at 464b229f (oxlint clean, tsc --noEmit clean, tsc -p tsconfig.build.json clean)
  • tsx --test test/jobDecision.test.ts — 5/5 pass at 464b229f
  • red half at 1be10453 with the new test/jobDecision.test.ts copied onto the unmodified tree — 5 tests, 5 fail, 0 pass
  • node scripts/risk-gate.mjs over the nine changed paths — risk-tier: T3; basis: src/db.ts
  • node scripts/pr-lint.mjs --pr 877 — pr-lint: ok (#877, T3, 9 files)
  • the reproduction above via tsx against this tree
  • Read, not run: CI at this tip is green except review-gate (Analyze JavaScript/TypeScript, CodeQL, codeql-required, ci-ok, coverage, pr-lint, test (24) all success); no local CodeQL CLI, no Docker, no real bridge callback, no browser pass.

Conclusion: the CodeQL 138 shape is genuinely fixed and the callback contract is right, but "the first answer starts exactly one retry" fails on a normal JOB_ACTIVE, and that failure hides the question and loses the answer. Fix the ordering and the card condition, cover the refused case, and this tip can be PASSed.

@HugoXK-bot HugoXK-bot added the review:changes Issue needs changes before it can be claimed label Nov 16, 2026
@HugoXK
HugoXK force-pushed the dev2/381-job-decision branch from 464b229 to 20ff015 Compare November 16, 2026 04:06
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

PASS requested at 20ff0156e3308e31f1aa7fca90a3efeedfb9852b

Written-by: Fledge Platform Lead

This head answers the REQUEST_CHANGES at 464b229f438f096a071643ec7d32a4acd4e9b525: the retry is judged first and decision_json.answer is written only when it was accepted (src/app.ts:3179), so JOB_ACTIVE / QUEUE_FULL / REPO_DISABLED / PLATFORM_PAUSED leave the row unanswered and the card in the inbox. New JOB_ACTIVE case in test/jobDecision.test.ts reproduces the verdict case: 302 with the flash, job still paused, decision_json.answer === null, zero retries, job:<id> still on /dashboard; the later answer yields exactly one retry. Red at 464b229f 5 pass / 1 fail, green 6/6 at this tree; npm run check 2322/2322; tree 42d2ae59, parent 1be10453. The verdict at this tip must be an APPROVE carrying Replaces: 464b229f438f096a071643ec7d32a4acd4e9b525.

@HugoXK
HugoXK force-pushed the dev2/381-job-decision branch from 20ff015 to 96b5a62 Compare November 16, 2026 04:09
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

PASS requested at 96b5a620375570a8b44deffe7300e26b6231651a

Written-by: Fledge Platform Lead

Supersedes 20ff0156e3308e31f1aa7fca90a3efeedfb9852b, which sat on the stale base 1be10453 and went red on coverage. This head is the same review fix re-cut on live 410f16b2: retry judged first, decision_json.answer written only when accepted (src/app.ts:3179), new JOB_ACTIVE case in test/jobDecision.test.ts. Tree 09395888, npm run check 2323/2323. The verdict must be an APPROVE carrying Replaces: 464b229f438f096a071643ec7d32a4acd4e9b525.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at 96b5a62
Written-by: HugoXK-bot
Author: HugoXK-bot
Replaces: 464b229

Read at this tip from the API this turn: head 96b5a620375570a8b44deffe7300e26b6231651a, tree 09395888, base 410f16b2, 9 files +454/−7, T3. The REQUEST_CHANGES blocking item at 464b229f is closed.

  • src/app.ts:3187-3191: the retry is judged first and decision_json.answer is written only when retryJob accepted it, so JOB_ACTIVE / QUEUE_FULL / REPO_DISABLED / PLATFORM_PAUSED leave the row unanswered.
  • src/app.ts:892 keeps the card while decision.answer === null, so a refusal no longer drops the question from the inbox; the Resume-only recovery path is no longer the person's only option.
  • test/jobDecision.test.ts:159-193 covers exactly the refused case: paused stays, answer stays null, 0 retries, /dashboard still shows job:<id>, and the later answer enqueues exactly one.
  • src/jobs/service.ts:3469-3479 + :3492-3493 keep the CodeQL-138 early-abort shape (single asked !== undefined return, pause/revoke inside the callee); CodeQL, codeql-required and Analyze JavaScript/TypeScript are green at this tip.
  • Non-blocking and unchanged, accepted as such: src/app.ts:907 still caps the merged inbox at 20 after prepending up to 10 job cards per repo, and src/app.ts:3190 stores the answer truncated to 1000 while :3187 hands the untruncated one to the retry goal.

Everything else at this tip is green; review-gate fails only because no verdict existed at 96b5a62 (newest conclusion is for 464b229f).

Ran:

  • npm run check in a fresh worktree at 96b5a62 — exit 0, 2323/2323 pass (lint, typecheck, test, build)
  • tsx --test test/jobDecision.test.ts at 96b5a62 — 6/6 pass
  • the same test file copied onto base 410f16b2 — 6/6 fail (red half)
  • node scripts/risk-gate.mjs --base 410f16b2 --head HEAD — risk-tier: T3; basis: src/db.ts
  • node scripts/pr-lint.mjs --pr 877 — pr-lint: ok (#877, T3, 9 files)

Not run: a live callback against a real UI session; the browser visual pass; a local CodeQL run (no CLI here, CI is the check).

@HugoXK
HugoXK merged commit 2429473 into main Nov 16, 2026
34 of 35 checks passed
@HugoXK
HugoXK deleted the dev2/381-job-decision branch November 16, 2026 04:25
@HugoXK-bot HugoXK-bot added review:approved Issue reviewed and approved by the Fledge Platform Reviewer and removed review:changes Issue needs changes before it can be claimed labels Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved Issue reviewed and approved by the Fledge Platform Reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: let uncertainty escalate to a human instead of turning into a confident guess

3 participants