agent-afk 5.126.0 → 5.127.0

package/dist/agent/providers/xai/index.d.ts

@@ -34,5 +34,5 @@ export declare class XaiProvider implements ModelProvider {
 export { resolveXaiAuth, formatXaiAuthDiagnostic, formatXaiHttpAuthError, type XaiAuthResolution, type XaiAuthSource, } from './auth.js';
 export { resolveXaiEndpoint, DEFAULT_XAI_API_BASE_URL, DEFAULT_XAI_OAUTH_BASE_URL, type XaiAuthMode, } from './endpoints.js';
 export { readXaiTokens, writeXaiTokens, clearXaiTokens, getXaiAuthPath, } from './auth-store.js';
-export { startDeviceCodeFlow, pollDeviceCodeToken, buildPkceAuthorizeUrl, exchangeAuthorizationCode, generateCodeVerifier, generateOAuthState, refreshXaiTokens, ensureFreshAccessToken, discoverXaiOidc, } from './oauth.js';
+export { startDeviceCodeFlow, pollDeviceCodeToken, buildPkceAuthorizeUrl, exchangeAuthorizationCode, generateCodeVerifier, generateOAuthState, refreshXaiTokens, ensureFreshAccessToken, discoverXaiOidc, discoverXaiOidcCached, clearOidcCache, } from './oauth.js';
 export { deriveXaiCallCostUsd, isGrokModelId, XAI_MODEL_PRICING, } from './pricing.js';

package/dist/agent/providers/xai/oauth-http.d.ts

@@ -13,8 +13,11 @@ export interface OAuthHttpDeps {
     clientId?: string;
     scopes?: string;
     nowSeconds?: () => number;
+    nowMs?: () => number;
 }
 export declare function asNonEmptyString(v: unknown): string | undefined;
 export declare function safeText(res: Response): Promise<string>;
+export declare function clearOidcCache(): void;
 export declare function discoverXaiOidc(deps?: OAuthHttpDeps): Promise<XaiOidcDiscovery>;
+export declare function discoverXaiOidcCached(deps?: OAuthHttpDeps): Promise<XaiOidcDiscovery>;
 export declare function tokenResponseToBundle(json: Record<string, unknown>, nowSeconds?: () => number, fallbackRefresh?: string): XaiTokenBundle | null;

package/dist/agent/providers/xai/oauth.d.ts

@@ -1,7 +1,7 @@
 import { type XaiAuthStoreDeps, type XaiTokenBundle } from './auth-store.js';
 import { type OAuthHttpDeps } from './oauth-http.js';
 export type { FetchFn, OAuthHttpDeps, XaiOidcDiscovery } from './oauth-http.js';
-export { discoverXaiOidc, tokenResponseToBundle } from './oauth-http.js';
+export { clearOidcCache, discoverXaiOidc, discoverXaiOidcCached, tokenResponseToBundle } from './oauth-http.js';
 export { startDeviceCodeFlow, pollDeviceCodeToken, type DeviceCodeStart, type DevicePollResult, } from './oauth-device.js';
 export { buildPkceAuthorizeUrl, codeChallengeS256, exchangeAuthorizationCode, generateCodeVerifier, generateOAuthState, type PkceAuthorizeParams, } from './oauth-pkce.js';
 export declare function refreshXaiTokens(refreshToken: string, deps?: OAuthHttpDeps & {

package/dist/agent/subagent/fork-lifecycle.d.ts

@@ -5,7 +5,7 @@ export interface EmitForkStartedArgs {
     id: string;
     parentSessionId: string | undefined;
     rootId: string;
-    effectiveChildModel: AgentModelInput | undefined;
+    effectiveChildModel: AgentModelInput;
     childConfig: AgentConfig;
     promptHead: string | undefined;
     effectiveAgentType: string | undefined;

package/dist/agent/subagent.d.ts

@@ -4,9 +4,9 @@ import { type ReadScopeInputs } from './subagent-read-scope.js';
 import { type SubagentHandle } from './subagent/handle.js';
 import type { SubagentStatus, SubagentResult, SubagentTrace } from './subagent/result.js';
 export type { SubagentStatus, SubagentResult, SubagentTrace, SubagentHandle };
-import { DENY_ELICITATION, SUBAGENT_DEFAULT_MAX_TOOL_USE_ITERATIONS, SUBAGENT_DEFAULT_TIMEOUT_MS, SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS, SUBAGENT_BACKGROUND_TIMEOUT_MS, resolveSubagentTimeoutMs, resolveSubagentIdleTimeoutMs } from './subagent/constants.js';
+import { DENY_ELICITATION, SUBAGENT_DEFAULT_MAX_TOOL_USE_ITERATIONS, SUBAGENT_DEFAULT_TIMEOUT_MS, SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS, SUBAGENT_BACKGROUND_TIMEOUT_MS, SUBAGENT_DRAIN_TIMEOUT_MS, resolveSubagentTimeoutMs, resolveSubagentIdleTimeoutMs } from './subagent/constants.js';
 import type { ForkParent, ForkSubagentOptions, SubagentManagerOptions } from './subagent/fork-types.js';
-export { DENY_ELICITATION, SUBAGENT_DEFAULT_MAX_TOOL_USE_ITERATIONS, SUBAGENT_DEFAULT_TIMEOUT_MS, SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS, SUBAGENT_BACKGROUND_TIMEOUT_MS, resolveSubagentTimeoutMs, resolveSubagentIdleTimeoutMs, };
+export { DENY_ELICITATION, SUBAGENT_DEFAULT_MAX_TOOL_USE_ITERATIONS, SUBAGENT_DEFAULT_TIMEOUT_MS, SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS, SUBAGENT_BACKGROUND_TIMEOUT_MS, SUBAGENT_DRAIN_TIMEOUT_MS, resolveSubagentTimeoutMs, resolveSubagentIdleTimeoutMs, };
 export type { ForkParent, ForkSubagentOptions, SubagentManagerOptions };
 export declare class SubagentManager {
     private readonly active;

package/dist/agent/tools/subagent/background-branch.d.ts

@@ -8,6 +8,7 @@ export interface RunBackgroundBranchArgs {
     prompt: string;
     model: string | undefined;
     parentSessionId: string | undefined;
+    onSettled?: (isError: boolean) => void;
 }
 export declare function runBackgroundBranch(args: RunBackgroundBranchArgs): Promise<ToolResult>;
 export {};

package/dist/bundled-plugins/awa-bundled/skills/false-completion-gate/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: false-completion-gate
+description: "Fires when a state-mutating task is about to be declared Done (success summary or completion verdict) — to catch silent success, the highest-frequency invisible agent failure where confident 'done' language hides work that never landed. Decomposes the completion into receipt-checkable assertions, then dispatches a reconciliation auditor that cross-references each claim against the session's tool-call LEDGER (did the producing action fire?) and a fresh postcondition READ-BACK of the named artifact (does the file/test/commit exist and match?), gating the Done behind a BACKED/UNBACKED/UNVERIFIABLE verdict plus a bounded repair loop. Distinct from shadow-verify, which RE-DERIVES an investigation finding's correctness — this reconciles a COMPLETION against execution receipts, never re-deriving the claim. Use before any Done/success in implementation, fix, refactor, migration, or multi-file write work. Skip text-terminal sessions (explanation, Q&A) and work that already failed loudly."
+failure_modes:
+  - false completeness
+  - confident fabrication
+  - tool thrash
+---
+
+## Sub-agent contract
+/contract
+
+This skill fires when a session (or a returning sub-agent) is about to declare a state-mutating task **complete** — a Done terminal state, a success summary, or a passing completion verdict. The core invariant: **a completion claim must be backed by execution receipts and a fresh artifact read-back, never by the assertive language of the claim itself.** Claim and evidence must be structurally separated — the base agent fuses them, narrating "done" straight from in-context memory of a tool result it never re-observed. That fusion is exactly how "silent success" propagates a false Done into downstream steps that then compound on a foundation that was never real.
+
+**Phase 1 — Claim decomposition.** Before emitting the Done, decompose the pending completion into a checklist of concrete, receipt-checkable assertions. Each assertion names: (a) the **deliverable** ("feature X implemented", "tests green", "branch pushed"), (b) the **producing action** that must have fired to make it true (an Edit/Write to a specific path, a specific test command, a `git push`), and (c) the **durable location** that would prove it (file path + expected content, test-output line, commit SHA). Add a **goal-substitution assertion**: if the original goal was diagnostic (interrogative — "why does X", "what causes Y") but the deliverables are all implementation, the diagnostic answer is itself a required assertion — its absence is an UNBACKED completion, because the question was silently swapped for a patch.
+
+**Phase 2 — Receipts reconciliation.** Dispatch one read-only reconciliation auditor (`subagent_type: "awa-private:research-agent"` — locked to Read/Grep/Glob; add a Bash-capable type with `isolation: "worktree"` only if a postcondition needs a command rerun, e.g. re-running the test). It receives ONLY the assertion checklist + the user's original goal — never the orchestrator's success narrative. For each assertion it independently establishes: **ledger_match** — did the producing action actually appear in this session's tool-call history? **postcondition** — read the durable artifact from source *now* (file content, fresh test output, `git log`/`git status`) and check it matches the claim. **durable_location** — confirm evidence is a real location, never transcript-only. The orchestrator hands the auditor this session's tool-call history as the ledger; if that history is unavailable or truncated (a hand-off, a compacted context), the auditor marks the assertion `UNVERIFIABLE` rather than assuming the action fired — the gate fails closed, never open. Returns a receipts table: `{assertion, ledger_match: yes|no, postcondition: pass|fail|unverifiable, durable_location, verdict: BACKED|UNBACKED|UNVERIFIABLE}`.
+
+**Gate verdict (merge):**
+- All assertions **BACKED** → `VERIFIED`: emit the Done, attaching the receipts table as the evidence block (durable locations, not prose).
+- Any **UNBACKED** (no producing action in the ledger, or read-back contradicts the claim) → `FALSE-COMPLETION`: do **not** emit Done. Surface the exact unbacked assertion(s) and what the read-back actually showed.
+- Any **UNVERIFIABLE** (external side-effect with no fetchable receipt) → never pass as a confident Done; surface tagged `[needs-human-review]`.
+
+**Phase 3 — Bounded repair.** On `FALSE-COMPLETION`, route only the unbacked assertions to a targeted repair pass — re-execute the missing producing action or fix the failing postcondition — then re-run Phase 2 on just those assertions. Cap at **2 repair cycles**. If an assertion is still UNBACKED after 2 cycles, emit a **Blocked** terminal state naming the exact unbacked assertion and the missing receipt — never a Done. The asymmetry is safe by construction: the gate can only ever downgrade a false Done to an honest Blocked/needs-review; it cannot manufacture a completion that wasn't real.
+
+**When to invoke:** before any Done / success summary / completion verdict in state-mutating work (implementation, bug fix, refactor, migration, multi-file write, deployment) — especially when the belief that it worked rests on in-context memory of a tool result rather than a fresh read-back, or when the run spanned many steps and the early "success" was never re-observed.
+
+**Skip when:** the session is text-terminal (a pure explanation, architecture walkthrough, or Q&A that mutates no artifact — there are no receipts to reconcile); the work already failed loudly (no false-completion risk); or an orchestrator that already verifies its own completion (`ship`, `mint`, `heal`) is driving — invoke once at the outer Done, not per inner step.

package/dist/bundled-plugins/awa-bundled/skills/fix-pr/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: fix-pr
+description: "One-verb pipeline for the operator's highest-frequency manual loop: fetch a PR's unresolved reviewer feedback (inline review comments, review-summary bodies, and issue-level conversation comments) and failing CI checks, fix them in an isolated managed worktree via a budget-bounded subagent, verify with the project's test gates, and push the fix back to the PR branch. Replaces the retyped recipe 'send a subagent in a worktree to fix <PR feedback>, then push.' Use when a PR has review comments or red CI that needs addressing — e.g. 'fix pr 286', 'address the review on #215', 'CI is red on the worktree-sweep PR'. Never force-pushes, never touches main, fails closed on missing gh auth or un-pushable fork PRs."
+argument-hint: "<PR-number-or-URL> [--repo <path>] [--no-push] [--re-review]"
+surface: "afk"
+failure_modes:
+  - push to wrong branch
+  - nested /review max_depth self-collision
+  - silent partial fix (some comments addressed, done claimed for all)
+  - unmanaged worktree leak
+---
+
+## Sub-agent contract
+/contract
+
+`fix-pr` turns "review feedback / red CI on PR N" into a pushed fix commit with test evidence, using worktree isolation so the operator's working tree is never disturbed. It is the composition the operator previously chained by hand: `/resolve`-style feedback interpretation + managed worktree + budget-bounded fix subagent + test gate + push.
+
+**Skip when:** the fix is a one-line suggestion the operator pointed at directly (apply inline); the PR is already green with all threads resolved (report and stop); or the work is local-only and unpushed (use `/ship`).
+
+---
+
+### Phase 0 — Input gate & preflight (inline, fail closed)
+
+Parse `$ARGUMENTS`:
+- **`pr`** — PR number or URL (required). If absent, stop: "fix-pr requires a PR number or URL."
+- **`repo`** — repo path from `--repo`; default: current working directory's git root.
+- **`no_push`** — from `--no-push`: produce the fix in a kept worktree + diff summary, no remote mutation.
+- **`re_review`** — from `--re-review`: after pushing, re-trigger `/review` (top-level only — see Phase 6 guard).
+
+Preflight (all inline bash; any failure → **Blocked**, do not improvise):
+1. `gh auth status` — must be authenticated. Fail closed if not.
+2. `gh pr view <pr> --json state,headRefName,headRepositoryOwner,isCrossRepository,mergeable,url` — PR must be OPEN.
+3. **Fork guard:** if `isCrossRepository` is true and the authenticated account cannot push to the head repo, emit **Blocked** naming the fork and stop. Never attempt workarounds.
+4. Record `head_branch` — this is the ONLY branch this skill will ever push to.
+
+---
+
+### Phase 1 — Feedback harvest (inline)
+
+Reviewer feedback lives in **three distinct GitHub stores** — miss any one and the fix is silently partial. Harvest all three, then the gates:
+
+1. **Inline review comments:** `gh api repos/{owner}/{repo}/pulls/<pr>/comments` — comments anchored to a diff line (each carries `path`/`line`/`diff_hunk`).
+2. **Review summary bodies:** `gh pr view <pr> --json reviews` — the top-level body of each APPROVE / REQUEST_CHANGES / COMMENT review submission.
+3. **Issue-level conversation comments:** `gh pr view <pr> --json comments` (equivalently `gh api repos/{owner}/{repo}/issues/<pr>/comments`). A PR is also an issue, and its plain conversation comments ("also update the docs", "rename this before merge") live on the **issues** endpoint — the `pulls/<pr>/comments` endpoint does NOT return them. Skipping this source is the known gap: reviewers who leave feedback as normal PR comments are otherwise dropped entirely, and a PR can have actionable conversation comments with zero inline review comments.
+
+Then the gates:
+4. **Failing CI checks:** `gh pr checks <pr>` — for each failing check, pull the tail of its log (`gh run view --log-failed` when available).
+5. **PR description acceptance criteria** if present.
+
+**Noise filter (apply to sources 1–3 before building the spec):** drop bot/automation chatter (vercel, github-actions, codecov, dependabot, deploy-preview posts) and non-actionable social comments ("LGTM", "thanks", 👍). Keep only unresolved, actionable requests.
+
+Routing rule:
+- Any actionable reviewer feedback (inline comments, review bodies, or conversation comments) exists → it is the primary spec; failing checks are secondary gates.
+- **No actionable feedback but CI is red → the failing checks ARE the spec** (acceptance criterion 3).
+- Neither → report "PR is green with no unresolved feedback" and stop (Done, no mutation).
+
+Consolidate into a numbered fix spec: each item = source (comment URL or check name), file/line if known, and the requested change. This numbered list is the completeness contract — every item must be addressed or explicitly declared out-of-scope in the terminal report.
+
+---
+
+### Phase 2 — Isolated worktree (inline, managed only)
+
+Create the worktree via the **`worktree` tool** (`action: create`, `name: pr<pr>-fix`, `base: <head_branch>` after `git fetch`). **NEVER raw `git worktree add`** — unmanaged trees lack sweep metadata and leak (the 108-worktree/14GB sprawl was this failure mode).
+
+If a managed worktree for this PR already exists, reuse it only if clean; otherwise create a fresh one with a suffixed name.
+
+---
+
+### Phase 3 — Fix dispatch (one subagent, budget-bounded)
+
+Size the dispatch per `/right-size-delegation` if available; defaults otherwise:
+
+Dispatch ONE implementation subagent (`agent` tool, `cwd: <worktree path>`, `max_turns: 25`, model right-sized to the diff — `sonnet` default, `haiku` never for code fixes):
+- inputs: the numbered fix spec, `head_branch`, repo test/lint commands (inferred from package.json / Makefile / pyproject.toml and passed explicitly).
+- goal: address every numbered item with minimal diffs; run the narrowest relevant tests per item; commit locally with a message referencing the PR (`fix(pr-<pr>): address review feedback`).
+- non_goals: do NOT push, do NOT touch branches other than the checked-out one, do NOT invoke /review or any skill, do NOT expand scope beyond the numbered items.
+- deliverable: per-item status table (`fixed` | `out-of-scope <reason>`), unified diff summary, targeted test output, local commit SHA.
+
+---
+
+### Phase 4 — Verification gate (inline in the worktree)
+
+Run the project's full test/lint gates in the worktree yourself — do not trust the subagent's report alone.
+
+- All green → Phase 5.
+- Failures → iterate: re-dispatch the fix subagent with the failure output as an updated spec (or hand off to `/heal` semantics if that skill is loadable), **≤2 iterations**. Cap reached → keep the worktree, emit **Blocked** naming the branch, the worktree path, the surviving failures, and the per-item status table.
+
+**Completeness check:** every numbered spec item must be `fixed` or explicitly `out-of-scope` with a reason. A partially addressed spec is never reported as Done.
+
+---
+
+### Phase 5 — Push (guarded)
+
+- `no_push` set → `worktree keep` (reason: "fix-pr --no-push review pending"), emit the diff summary + per-item table, stop (Done, no remote mutation).
+- Otherwise: `git push origin <head_branch>` from the worktree. **Plain push only — never `--force`, never `--force-with-lease`, never any other ref.** If push is rejected (non-fast-forward because the PR moved), fetch + rebase the fix commits onto the new head, re-run Phase 4 gates, push again. If still rejected → Blocked.
+
+---
+
+### Phase 6 — Optional re-review (top-level guard)
+
+If `re_review`: invoke `/review` **directly from this top-level session only — NEVER from inside a subagent** (known max_depth self-collision: 100+ `delegation.skipped reason:"max_depth" requested_name:"review"` entries in routing-decisions.jsonl). If the current session is itself a subagent (check `get_runtime_state` depth), skip re-review and note it in the terminal report instead.
+
+---
+
+### Phase 7 — Cleanup & terminal state
+
+- Success: `worktree remove` (branch ref is preserved automatically).
+- Failure/Blocked: keep the worktree, name its path and branch in the report.
+
+**Done** must cite: pushed commit SHA(s), the PR URL, the per-item fix table, and test-gate output location.
+**Blocked** must cite: exact unblock condition (auth, fork perms, surviving test failures), worktree path, and everything already fixed.

package/dist/bundled-plugins/awa-bundled/skills/polish/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: polish
+description: "Iteratively refines any artifact (prose, spec, prompt, API design, SKILL.md, code snippet) by running a decoupled evaluator → generator loop until explicit criteria are met or an iteration cap is reached. Locks criteria in Wave 1, isolates the evaluator from generation history to prevent sycophancy, and emits the best version with any remaining gaps flagged at cap."
+---
+
+## Sub-agent contract
+/contract
+
+`polish` is a three-wave evaluator-optimizer loop that applies to any artifact at any workflow stage. Wave 1 locks concrete, testable criteria. Waves 2 and 3 alternate (evaluator → generator) until all criteria pass or the iteration cap is reached. The evaluator is always spawned stateless — it never sees prior generation history — eliminating the sycophancy failure mode that plagues shared-context review loops.
+
+The orchestrator coordinates but never edits the artifact directly. All revisions are produced by the Wave 3 generator, which receives only the `blocking_gaps` list from the evaluator (not its full reasoning). This constraint prevents scope-creep revisions and keeps each iteration focused on the delta between current state and the locked criteria.
+
+On cap exhaust the orchestrator emits the best-scoring version plus a structured `remaining_gaps` report so the caller can decide whether to extend the cap, escalate to a human, or ship with known gaps documented.
+
+---
+
+## Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `artifact` | yes | The text, spec, prompt, design doc, or code snippet to refine |
+| `goal` | yes | Natural-language quality intent ("make this safe for external stakeholders") |
+| `criteria` | no | Pre-supplied testable criteria — skips Wave 1 extraction if provided |
+| `threshold` | no | `pass_all` (default) or `pass_N` where N is an integer |
+| `cap` | no | Max refinement iterations (default: 4, max: 8) |
+
+---
+
+## Wave 1 — Criteria Extraction
+
+**Trigger:** Always, unless `criteria` were supplied by the caller.
+
+**Agent:** Single subagent. Reads `artifact` + `goal`. Produces:
+
+```json
+{
+  "criteria": [
+    { "id": "C1", "text": "<concrete, binary-testable criterion>" },
+    ...
+  ],
+  "threshold": "pass_all | pass_N",
+  "cap": 4
+}
+```
+
+**Rules:**
+- Criteria must be falsifiable — "no jargon visible to end-users", not "improve clarity".
+- Maximum 8 criteria. If the goal implies more, merge related ones.
+- Criteria are **locked** after Wave 1. The evaluator may not add or modify them.
+
+**Exit:** Emit `criteria.json`. Proceed to Wave 2.
+
+---
+
+## Wave 2 — Evaluation (stateless)
+
+**Agent:** Single subagent, spawned fresh with **no generation history**. Receives:
+- Current artifact (text only)
+- Locked `criteria.json`
+
+**Produces:**
+
+```json
+{
+  "scores": [
+    { "criterion_id": "C1", "pass": true, "gap": "" },
+    { "criterion_id": "C2", "pass": false, "gap": "<specific, actionable description of what is missing or wrong>" }
+  ],
+  "overall": "pass | fail",
+  "blocking_gaps": ["C2: <gap text>", ...]
+}
+```
+
+**Rules:**
+- If `overall: pass` (threshold met) → skip Wave 3, emit final artifact, terminate loop.
+- If iteration count == cap → skip Wave 3, emit best version + `remaining_gaps`, terminate loop.
+- Gap text must be specific enough for Wave 3 to act on without re-reading evaluator reasoning.
+
+---
+
+## Wave 3 — Revision
+
+**Agent:** Single subagent. Receives:
+- Current artifact
+- `blocking_gaps` list (text only — NOT the evaluator's full `scores` object)
+- Original `goal` (for orientation only, not as new criteria)
+
+**Produces:** Revised artifact (full text, not a diff).
+
+**Rules:**
+- Address only the `blocking_gaps`. Do not make unrequested changes.
+- Do not invent new criteria or second-guess passing scores.
+- Output is the next artifact fed into Wave 2.
+
+---
+
+## Loop Control
+
+```
+iteration = 0
+artifact = <input>
+
+Wave 1 → criteria.json
+
+loop:
+  iteration += 1
+  result = Wave 2(artifact, criteria.json)
+  if result.overall == "pass":
+    emit artifact, result.scores, iteration_count
+    DONE
+  if iteration == cap:
+    emit artifact, result.remaining_gaps, "CAP_REACHED"
+    DONE
+  artifact = Wave 3(artifact, result.blocking_gaps)
+```
+
+---
+
+## Outputs
+
+| State | Emitted |
+|---|---|
+| Converged | Final artifact + `{status: "CONVERGED", iterations: N, scores: [...]}` |
+| Cap reached | Best artifact + `{status: "CAP_REACHED", iterations: cap, remaining_gaps: [...]}` |
+
+`CAP_REACHED` is not a failure — it is an explicit signal for the caller to extend, escalate, or ship with documented gaps. The orchestrator never silently discards gap information.
+
+---
+
+## Composition
+
+`polish` is designed to run *after* a generative skill and *before* `ship`:
+
+```
+spec → forge → polish → ship
+research → mint → polish → ship
+<any draft> → polish → ship
+```
+
+It may also be called standalone on an existing artifact with explicit `criteria` supplied.