@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/workflows/recovery.ts

@@ -16,7 +16,12 @@ import type { WorkflowRunStep } from "../types";
 import { shapeApprovalResolution } from "./approval-resolution";
 import { loadCompletedStepRouting } from "./completed-step-routing";
 import { FAILED_TASK_OUTPUT_PREFIX } from "./constants";
-import { findReadyNodes, isWorkflowRunActive, walkGraph } from "./engine";
+import {
+  failRunOnUnreadableReplay,
+  findReadyNodes,
+  isWorkflowRunActive,
+  walkGraph,
+} from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
 import { getSecretInputKeys } from "./input";
 import { finalizeOrWait, resumeWaitState } from "./resume";
@@ -113,6 +118,7 @@ async function recoverRunningRuns(registry: ExecutorRegistry): Promise<number> {
       }
       recovered++;
     } catch (err) {
+      if (await failRunOnUnreadableReplay(runId, err)) continue;
       console.error(`[workflows] Failed to recover running run ${runId}:`, err);
     }
   }
@@ -248,6 +254,7 @@ async function recoverWaitingRuns(registry: ExecutorRegistry): Promise<number> {
       }
       recovered++;
     } catch (err) {
+      if (await failRunOnUnreadableReplay(stuck.runId, err)) continue;
       console.error(`[workflows] Failed to recover waiting run ${stuck.runId}:`, err);
     }
   }
@@ -349,6 +356,7 @@ async function recoverApprovalWaitingRuns(registry: ExecutorRegistry): Promise<n
       }
       recovered++;
     } catch (err) {
+      if (await failRunOnUnreadableReplay(stuck.runId, err)) continue;
       console.error(`[workflows] Failed to recover approval-waiting run ${stuck.runId}:`, err);
     }
   }
@@ -391,6 +399,7 @@ async function recoverWaitStates(registry: ExecutorRegistry): Promise<number> {
       await resumeWaitState(stuck.waitId, resumeStatus, payload, registry);
       recovered++;
     } catch (err) {
+      if (await failRunOnUnreadableReplay(stuck.runId, err)) continue;
       console.error(`[workflows] Failed to recover wait-state ${stuck.waitId}:`, err);
     }
   }

package/src/workflows/resume.ts

@@ -17,6 +17,7 @@ import {
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
+import type { WaitStateRow } from "../types";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import {
   type ApprovalSlackClient,
@@ -26,7 +27,7 @@ import { shapeApprovalResolution } from "./approval-resolution";
 import { loadCompletedStepRouting } from "./completed-step-routing";
 import { FAILED_TASK_OUTPUT_PREFIX } from "./constants";
 import { getNextTargets } from "./definition";
-import { findReadyNodes, hasRunningStep, walkGraph } from "./engine";
+import { failRunOnUnreadableReplay, findReadyNodes, hasRunningStep, walkGraph } from "./engine";
 import type { WorkflowEventBus } from "./event-bus";
 import { workflowEventBus } from "./event-bus";
 import type { ExecutorRegistry } from "./executors/registry";
@@ -127,6 +128,23 @@ export function setupWorkflowResumeListener(
   };
 }
 
+/**
+ * Run one live resume of a waiting step. A sealed replay copy that cannot be
+ * opened fails the step and its run now, instead of logging and leaving the
+ * run `waiting` until a recovery sweep. Any other error rethrows.
+ */
+async function failClosedOnUnreadableReplay(
+  runId: string,
+  stepId: string,
+  resume: () => Promise<void>,
+): Promise<void> {
+  try {
+    await resume();
+  } catch (err) {
+    if (!(await failRunOnUnreadableReplay(runId, err, stepId))) throw err;
+  }
+}
+
 /**
  * Resume a workflow after a linked task completes.
  *
@@ -138,6 +156,15 @@ export function setupWorkflowResumeListener(
 async function resumeFromTaskCompletion(
   event: TaskEvent,
   registry: ExecutorRegistry,
+): Promise<void> {
+  await failClosedOnUnreadableReplay(event.workflowRunId!, event.workflowRunStepId!, () =>
+    resumeFromTaskCompletionUnguarded(event, registry),
+  );
+}
+
+async function resumeFromTaskCompletionUnguarded(
+  event: TaskEvent,
+  registry: ExecutorRegistry,
 ): Promise<void> {
   const run = await getWorkflowRun(event.workflowRunId!);
   if (!run || (run.status !== "waiting" && run.status !== "running")) return;
@@ -245,6 +272,17 @@ async function handleTaskFailure(
   reason: string,
   registry: ExecutorRegistry,
   options: { retryable: boolean },
+): Promise<void> {
+  await failClosedOnUnreadableReplay(event.workflowRunId!, event.workflowRunStepId!, () =>
+    handleTaskFailureUnguarded(event, reason, registry, options),
+  );
+}
+
+async function handleTaskFailureUnguarded(
+  event: TaskEvent,
+  reason: string,
+  registry: ExecutorRegistry,
+  options: { retryable: boolean },
 ): Promise<void> {
   const run = await getWorkflowRun(event.workflowRunId!);
   if (!run || (run.status !== "waiting" && run.status !== "running")) return;
@@ -541,6 +579,15 @@ export async function cancelWorkflowRunStep(
 async function resumeFromApprovalResolution(
   event: ApprovalEvent,
   registry: ExecutorRegistry,
+): Promise<void> {
+  await failClosedOnUnreadableReplay(event.workflowRunId!, event.workflowRunStepId!, () =>
+    resumeFromApprovalResolutionUnguarded(event, registry),
+  );
+}
+
+async function resumeFromApprovalResolutionUnguarded(
+  event: ApprovalEvent,
+  registry: ExecutorRegistry,
 ): Promise<void> {
   const run = await getWorkflowRun(event.workflowRunId!);
   if (!run || (run.status !== "waiting" && run.status !== "running")) return;
@@ -551,8 +598,6 @@ async function resumeFromApprovalResolution(
   const workflow = await getWorkflow(run.workflowId);
   if (!workflow) return;
 
-  const ctx = (run.context ?? {}) as Record<string, unknown>;
-
   if (event.status === "cancelled") {
     console.warn(
       `[workflows] approval ${event.requestId} is cancelled; step ${event.workflowRunStepId} stays waiting for the run cancel path`,
@@ -560,6 +605,10 @@ async function resumeFromApprovalResolution(
     return;
   }
 
+  // Opens the sealed replay context: after the cancelled bail-out, which leaves
+  // the step to the run cancel path.
+  const ctx = (run.context ?? {}) as Record<string, unknown>;
+
   // Output and port for the approval status. A step parked by an executor other
   // than human-in-the-loop shapes its own (see shapeApprovalResolution).
   const { output: stepOutput, nextPort } = shapeApprovalResolution(
@@ -643,7 +692,17 @@ export async function resumeWaitState(
   if (!result.updated || !result.row) return;
 
   const waitRow = result.row;
+  await failClosedOnUnreadableReplay(waitRow.workflowRunId, waitRow.workflowRunStepId, () =>
+    resumeClaimedWait(waitRow, status, cappedPayload, registry),
+  );
+}
 
+async function resumeClaimedWait(
+  waitRow: WaitStateRow,
+  status: "fired" | "timeout",
+  cappedPayload: unknown,
+  registry: ExecutorRegistry,
+): Promise<void> {
   // 2. Load the surrounding run + step. If anything has moved on (cancelled,
   // failed, retried, etc.), stay quiet.
   const run = await getWorkflowRun(waitRow.workflowRunId);

package/src/workflows/retry-poller.ts

@@ -11,6 +11,7 @@ import { checkpointStep, checkpointStepFailure, checkpointStepWaiting } from "./
 import { getSuccessors, resolveValidationPort } from "./definition";
 import {
   buildNodeInterpolationCtx,
+  failRunOnUnreadableReplay,
   holdWorkflowRun,
   interpolateNodeConfig,
   rehydrateCompletedStepOutputs,
@@ -200,11 +201,13 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
             }
           } catch (err) {
             // Execution threw — treat as failure
+            if (await failRunOnUnreadableReplay(run.id, err, step.id)) continue;
             const errorMsg = err instanceof Error ? err.message : String(err);
             const retryPolicy = node.retry || executor.retryPolicy;
             await checkpointStepFailure(run.id, step.id, errorMsg, step.retryCount, retryPolicy);
           }
         } catch (err) {
+          if (await failRunOnUnreadableReplay(step.runId, err, step.id)) continue;
           console.error(`[workflows] Retry failed for step ${step.id}:`, err);
         } finally {
           release?.();

package/templates/ai-toolbox.manifest.json

@@ -1,5 +1,5 @@
 {
-  "commit": "9748aabf7252c258378302240d73f7516d113777",
+  "commit": "77abe63716623f28177ebe29679c37b5859ef40e",
   "excludedSkills": [
     "feedback"
   ],
@@ -38,7 +38,7 @@
     "templates/skills/planning/content.md": "543476e4dbb5c352acd686c3929c45cc992d7d033d06f7e9a30f78009b50785c",
     "templates/skills/planning/files/template.md": "c0d5ca63c07934546172322bbd1180e2901dc45e27b5d12ce3dc5c30f5e7a98b",
     "templates/skills/qa/config.json": "c53b01558a691c0343b6270a548e6172af86600a429b789eedb518849f7ea741",
-    "templates/skills/qa/content.md": "93ad6b0fdfffaca5f04874e52fcefc46ab3ca2890cda74ebf0705ab5aedbe52a",
+    "templates/skills/qa/content.md": "c885095ea814b4c410dbc7aac1e2fde09b94b735d818b6f06153901311a232a0",
     "templates/skills/qa/files/template.md": "1902e4bb65b19ab58c54ab5b63693ad09adecee69079c2c70f58d7d6c6597896",
     "templates/skills/questioning/config.json": "da2d5fe6dfdac1915a0476a7063e62ebeb996b84caff07cc7527a55477656a80",
     "templates/skills/questioning/content.md": "66f826a191e96d0041adca00a7c197a458de8e6fe164c1599b8708098d4109ab",

package/templates/skills/agent-browser/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-browser
-description: "Drive a real browser with the agent-browser CLI (headless Chromium over CDP). Use for any browser task: verifying a UI change, taking a screenshot, walking a web page, filling a form, extracting page text, reproducing a frontend bug, or attaching UI evidence to a PR, issue, Linear comment, or Slack thread. Starts with a `command -v agent-browser` check and falls back to manual QA on the slim worker image. Screenshots are shared through agent-fs signed URLs. This is the only browser automation tool; do not use qa-use."
+description: "Drive a real browser with the agent-browser CLI (headless Chromium over CDP). Use for any browser task: verifying a UI change, taking a screenshot, walking a web page, filling a form, extracting page text, reproducing a frontend bug, or attaching UI evidence to a PR, issue, Linear comment, or Slack thread. Starts with a `command -v agent-browser` check and falls back to manual QA on the slim worker image. Screenshots are kept on agent-fs and embedded in GitHub as user attachments. This is the only browser automation tool; do not use qa-use."
 ---
 
 # agent-browser
@@ -64,21 +64,21 @@ ffmpeg -y -i in.mp4 -filter:v "setpts=PTS/1.5,fps=30" -an \
 
 Speed-up is a post-process step: `record start` has no speed or human flag. Keep `fps=30` to preserve a steady 30 fps output rather than uneven frame drops at an inferred rate. `-an` disables audio because agent-browser recordings carry no audio track. The worker ships only `ffmpeg`, not `ffprobe`; inspect duration with `ffmpeg -i out-1.5x.mp4 2>&1 | grep Duration`.
 
-Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path as screenshots below, and link it in the PR body.
+Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Keep the 1.5x file on the same agent-fs QA path as screenshots below. In a PR, upload it as a GitHub user attachment and put the URL on its own line, so GitHub plays it inline.
 
 ## Step 3: share the screenshot through agent-fs
 
-Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention. Use `share-create` when a person needs to open the file, and `signed-url` for raw embeds such as an image in GitHub PR markdown. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. Use `share-create` when a person needs to open the file. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
 
 ```bash
 agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
   --file /tmp/<name>.png -m "<what it shows>"
 agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
 agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json
-agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # raw URL for embeds; 24h default, --expires-in up to 7d
 ```
 
-- Embed the signed URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
+- **GitHub PR body or comment**: upload the PNG, GIF or mp4 as a GitHub user attachment with the `github-attach` skill and embed `![caption](https://github.com/user-attachments/assets/<uuid>)`. Attachments never expire and mp4s play inline. A UI PR puts a before (main) and after pair in the `## Before / after` table. Fallback for images only, when the GitHub token is an App token (`ghu_`/`ghs_`): `agent-fs signed-url <path> --inline --json` (expires in 7 days). Never a presigned URL for an mp4 or a doc: it downloads.
+- **Linear comment or Slack message**: paste the `share-create` link.
 - In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 

package/templates/skills/agent-browser/config.json

@@ -1,6 +1,6 @@
 {
   "category": "skills",
-  "description": "Drive a real browser with the agent-browser CLI (headless Chromium over CDP). Use for any browser task: verifying a UI change, taking a screenshot, walking a web page, filling a form, extracting page text, reproducing a frontend bug, or attaching UI evidence to a PR, issue, Linear comment, or Slack thread. Starts with a `command -v agent-browser` check and falls back to manual QA on the slim worker image. Screenshots are shared through agent-fs signed URLs. This is the only browser automation tool; do not use qa-use.",
+  "description": "Drive a real browser with the agent-browser CLI (headless Chromium over CDP). Use for any browser task: verifying a UI change, taking a screenshot, walking a web page, filling a form, extracting page text, reproducing a frontend bug, or attaching UI evidence to a PR, issue, Linear comment, or Slack thread. Starts with a `command -v agent-browser` check and falls back to manual QA on the slim worker image. Screenshots are kept on agent-fs and embedded in GitHub as user attachments. This is the only browser automation tool; do not use qa-use.",
   "displayName": "Agent Browser",
   "kind": "skill",
   "name": "agent-browser",

package/templates/skills/agent-browser/content.md

@@ -59,21 +59,21 @@ ffmpeg -y -i in.mp4 -filter:v "setpts=PTS/1.5,fps=30" -an \
 
 Speed-up is a post-process step: `record start` has no speed or human flag. Keep `fps=30` to preserve a steady 30 fps output rather than uneven frame drops at an inferred rate. `-an` disables audio because agent-browser recordings carry no audio track. The worker ships only `ffmpeg`, not `ffprobe`; inspect duration with `ffmpeg -i out-1.5x.mp4 2>&1 | grep Duration`.
 
-Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Upload the 1.5x file through the same agent-fs QA path as screenshots below, and link it in the PR body.
+Add `--contact-sheet` to the start command for a timestamped PNG summary of visual changes. Recording needs `ffmpeg` on PATH; check `agent-browser doctor` before starting. Stop the recording before closing the browser so the video is saved. Keep the 1.5x file on the same agent-fs QA path as screenshots below. In a PR, upload it as a GitHub user attachment and put the URL on its own line, so GitHub plays it inline.
 
 ## Step 3: share the screenshot through agent-fs
 
-Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention. Use `share-create` when a person needs to open the file, and `signed-url` for raw embeds such as an image in GitHub PR markdown. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. Use `share-create` when a person needs to open the file. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
 
 ```bash
 agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
   --file /tmp/<name>.png -m "<what it shows>"
 agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
 agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json
-agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json  # raw URL for embeds; 24h default, --expires-in up to 7d
 ```
 
-- Embed the signed URL as `![caption](<url>)` in the PR body, review comment, Linear comment, or Slack message.
+- **GitHub PR body or comment**: upload the PNG, GIF or mp4 as a GitHub user attachment with the `github-attach` skill and embed `![caption](https://github.com/user-attachments/assets/<uuid>)`. Attachments never expire and mp4s play inline. A UI PR puts a before (main) and after pair in the `## Before / after` table. Fallback for images only, when the GitHub token is an App token (`ghu_`/`ghs_`): `agent-fs signed-url <path> --inline --json` (expires in 7 days). Never a presigned URL for an mp4 or a doc: it downloads.
+- **Linear comment or Slack message**: paste the `share-create` link.
 - In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 

package/templates/skills/artifacts/content.md

@@ -99,12 +99,19 @@ agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/login.png --json | jq '
 ```
 
 Capture with `agent-browser screenshot <path>` when it is installed, otherwise
-Playwright, ffmpeg, or a system screenshot tool. For an image that must render
-inside a PR body or a Slack message without a login, use a presigned URL
-instead of the viewer link:
+Playwright, ffmpeg, or a system screenshot tool. The agent-fs copy is the
+durable original. Where each kind of content goes:
+
+| Content | Use | Why |
+|---|---|---|
+| Image or GIF in GitHub | GitHub user attachment (`github-attach` skill) | Permanent, renders inline, short URL |
+| Video (mp4) in GitHub | GitHub user attachment, else an `agent-fs share-create` link | GitHub plays it inline. A presigned link downloads it |
+| Doc (plan, research, report) | `agent-fs share-create <path> --expires-in 604800` | Preview page, no download |
+| Durable pointer | `live.agent-fs.dev` path, in a PR only under `## Swarm provenance` | Share links die after 7 days, this one does not (needs login) |
+| Presigned `signed-url` | Image fallback only, with `--inline` | Downloads and expires after 7 days. Never for docs or mp4s |
 
 ```bash
-agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/login.png --json   # 24h default, --expires-in up to 7d
+agent-fs signed-url thoughts/<agent-id>/qa/<topic>-screenshots/login.png --inline --json   # fallback only; 24h default, --expires-in up to 7d
 ```
 
 ## Naming conventions
@@ -120,9 +127,12 @@ misc/<agent-id>/<task-id>-<description>.ext
 
 ## Attaching artifacts
 
-- **PR body** — embed `![caption](<resolved-share-url>)` after resolving and
-  printing the concrete URL as shown above.
-- **Slack** — link the agent-fs URL (team members only, the live viewer needs a login). Use a signed URL (`agent-fs signed-url`, up to 7 days) for anyone else.
+- **PR body** — embed images and mp4s as GitHub user attachments
+  (`![caption](https://github.com/user-attachments/assets/<uuid>)`), and link docs
+  with `share-create`. Never embed a `share-create` link as an image: it is an
+  HTML preview page. Swarm task links and durable agent-fs paths go only under
+  `## Swarm provenance`.
+- **Slack** — link the agent-fs URL (team members only, the live viewer needs a login). Use a `share-create` link (up to 7 days) for anyone else.
 - **`store-progress`** — use the `attachments` field with `kind: "agent-fs"` and the path.
 - **Linear comments** — paste the live URL in the comment body.
 

package/templates/skills/jira-interaction/config.json

@@ -5,7 +5,7 @@
   "slug": "jira-interaction",
   "title": "Jira Interaction",
   "description": "Generic Jira update discipline for issue comments, transitions, and triage.",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "category": "skills",
   "placeholders": ["JIRA_PROJECT_KEY"],
   "runAllSeedersCandidate": false,

package/templates/skills/jira-interaction/content.md

@@ -1,183 +1,67 @@
 # Jira Interaction (Read + Outbound Push)
 
-The swarm has Jira OAuth connected but **no inbound sync** (unlike Linear). Every read or write is a direct API call against the Atlassian REST API v3.
+The swarm has Jira OAuth support but no inbound sync. Use Atlassian REST API v3 through script credential bindings.
 
-## TL;DR — minimum knowledge
+## Authentication: script credential binding
 
-1. Pull the access token from `oauth_tokens` (provider = `jira`).
-2. Hit `https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3/...` — not your site hostname directly. 3LO bearer tokens only work via the `api.atlassian.com` proxy.
-3. Bodies for descriptions/comments must be in **ADF** (Atlassian Document Format), not plain text or markdown.
+Use the `swarm-scripts` skill and `script-run` (`args` first, `ctx` second) for every authenticated request. The API server resolves an OAuth authorization, refreshes it when needed, and substitutes `[REDACTED:JIRA_OAUTH_ACCESS_TOKEN]` in the request header only for the binding's allowed hosts. Never read credential tables, request a raw token from Lead, or copy a token into source, arguments, environment variables, logs, or task output.
 
-## Deployment constants
+Try the conventional binding key `JIRA_OAUTH_ACCESS_TOKEN` first, using `Authorization: Bearer [REDACTED:JIRA_OAUTH_ACCESS_TOKEN]` for `api.atlassian.com`. Do not ask Lead before the first try. `credential-bindings` is lead-only; workers cannot list bindings.
 
-- Site: `<your-site>.atlassian.net`
-- Cloud ID: `<cloud-id>`
-- Default project: `<PROJECT>`
-- Scopes on the stored token: confirm from `oauth_tokens.scope` before write operations
+On HTTP 401 with the conventional key, report the missing binding or authorization to Lead as a blocker. The fetch wrapper in `src/scripts-runtime/credential-broker/fetch-patch.ts` drops any header with an unresolved `[REDACTED:` placeholder, so a missing binding sends an unauthenticated request that yields 401, never a credential leak.
 
-If the cloudId ever changes, rediscover it:
-```bash
-curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  https://api.atlassian.com/oauth/token/accessible-resources | jq '.'
-```
-
-## Authentication
-
-The OAuth token is in the swarm DB (`oauth_tokens`, provider = `jira`).
+Lead uses `credential-bindings` action `list` to check the binding. If missing, Lead registers/authorizes the provider and creates a binding visible to the agent with `configKey: "JIRA_OAUTH_ACCESS_TOKEN"`, `authKind: "oauth"`, `oauthAuthorizationId`, `allowedHosts: ["api.atlassian.com"]`, and `headerTemplate: "Authorization: Bearer [REDACTED:JIRA_OAUTH_ACCESS_TOKEN]"`.
 
-```sql
--- via the db-query MCP tool
-SELECT accessToken, expiresAt, scope FROM oauth_tokens WHERE provider = 'jira';
-```
-
-**Always check `expiresAt` first.** Atlassian access tokens are short-lived (~1h). If expired, do NOT keep retrying — report it. Re-auth path:
+An expiring authorization is refreshed server-side; a refresh failure, revoked/missing authorization, or persistent 401 needs Lead/user re-authorization through `credential-bindings` action `oauth-authorize-url`. Do not query expiry/token columns or loop on 401s.
 
-```
-<SWARM_API_BASE_URL>/api/trackers/jira/authorize
-```
-(User may need to remove the app and re-auth.)
+Supported implementation: `src/be/script-credential-broker.ts` loads scoped relational bindings and calls `resolveOAuthBindingToken` from `src/be/oauth-credential-bindings.ts`. The scripts runtime substitutes placeholders at egress for allowed hosts.
 
 ## Calling pattern
 
-Every endpoint below is relative to:
-```
-https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3
-```
-
-Standard header set:
-```bash
--H "Authorization: Bearer $TOKEN"
--H "Accept: application/json"
--H "Content-Type: application/json"   # only on POST/PUT
-```
-
-## Common operations
-
-### 1. List projects
-
-```bash
-curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/project/search" \
-  | jq '.values[] | {key, name, id, projectTypeKey}'
-```
-
-### 2. Get a project (with issue types + lead)
-
-```bash
-curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/project/$PROJECT_KEY" \
-  | jq '{key, name, lead: .lead.displayName, issueTypes: [.issueTypes[] | {id, name, subtask}]}'
-```
-
-### 3. Search issues with JQL
-
-Use the **`/search/jql`** endpoint (the older `/search` is deprecated for cloud).
-
-```bash
-curl -s -G \
-  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  --data-urlencode 'jql=project = <PROJECT> AND statusCategory != Done' \
-  --data-urlencode 'fields=summary,status,assignee,priority' \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/search/jql" \
-  | jq '[.issues[] | {key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName}]'
-```
-
-### 4. Create an issue
-
-Description must be ADF. Minimal valid ADF:
-
-```bash
-curl -s -X POST \
-  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue" \
-  -d '{
-    "fields": {
-      "project": { "key": "<PROJECT>" },
-      "summary": "Short title",
-      "issuetype": { "name": "Task" },
-      "description": {
-        "type": "doc",
-        "version": 1,
-        "content": [
-          { "type": "paragraph", "content": [ { "type": "text", "text": "Body goes here." } ] }
-        ]
-      }
-    }
-  }'
-```
-
-Returns `{ id, key, self }` on success (HTTP 201). The `key` (e.g. `<PROJECT>-7`) is what humans use; URL is `https://<your-site>.atlassian.net/browse/<KEY>`.
-
-Available issue types are project-specific; list the project before creating issues.
-
-### 5. Transition issue status (e.g. → Done)
-
-Transitions are project- and workflow-specific. Always discover them first:
-
-```bash
-curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/transitions" \
-  | jq '.transitions[] | {id, name, to: .to.name}'
-```
-
-Transition IDs are project-specific. Do not copy IDs between Jira projects; discover them for the issue you are about to update.
-
-Transition (returns HTTP 204 on success, no body):
-
-```bash
-curl -s -X POST \
-  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/transitions" \
-  -d '{"transition":{"id":"<TRANSITION_ID>"}}'
-```
-
-### 6. Comment on an issue
+Allowed host: `api.atlassian.com`. Use the 3LO proxy `https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3`, rather than the site hostname. Keep the site, cloud ID, and default project as deployment-specific values.
 
-ADF body again:
+Run this source with `script-run`, supplying non-secret `args`: `cloudId`, `path`, optional `method`, `query`, and `body`.
 
-```bash
-curl -s -X POST \
-  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/comment" \
-  -d '{
-    "body": {
-      "type": "doc", "version": 1,
-      "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Update from the swarm." } ] } ]
-    }
-  }'
+```typescript
+export default async function (args, ctx) {
+  const url = new URL(`https://api.atlassian.com/ex/jira/${encodeURIComponent(args.cloudId)}/rest/api/3/${args.path}`);
+  for (const [key, value] of Object.entries(args.query ?? {})) {
+    url.searchParams.set(key, String(value));
+  }
+  const response = await fetch(url, {
+    method: args.method ?? "GET",
+    headers: {
+      Authorization: "Bearer [REDACTED:JIRA_OAUTH_ACCESS_TOKEN]",
+      Accept: "application/json",
+      ...(args.body ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(args.body ? { body: JSON.stringify(args.body) } : {}),
+  });
+  if (!response.ok) throw new Error(`Jira HTTP ${response.status}: ${await response.text()}`);
+  return response.status === 204 ? { success: true } : await response.json();
+}
 ```
 
-### 7. Assign an issue
+Return only the issue/project fields needed for the task, never headers or credentials. To discover the cloud ID, use the same script header in a GET to `https://api.atlassian.com/oauth/token/accessible-resources`; select the authorized site's resource ID and confirm its scopes permit the intended operation.
 
-Atlassian Cloud uses **accountId**, not username. Find one via:
-
-```bash
-curl -s -G -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  --data-urlencode 'query=<name-or-email>' \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/user/search" \
-  | jq '.[] | {accountId, displayName, emailAddress}'
-```
-
-Assign:
-```bash
-curl -s -X PUT \
-  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/assignee" \
-  -d '{"accountId":"<ACCOUNT_ID>"}'
-```
-
-To unassign: `{"accountId": null}`.
-
-### 8. Edit fields on an existing issue
+## Common operations
 
-```bash
-curl -s -X PUT \
-  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>" \
-  -d '{ "fields": { "summary": "New summary", "labels": ["swarm","auto"] } }'
-```
+Pass these paths and payloads to the script above. GET is the default.
 
-Returns HTTP 204.
+| Operation | Method and path | Query or body |
+|---|---|---|
+| List projects | GET `project/search` | Read `values` for keys, names, IDs |
+| Get project and issue types | GET `project/<PROJECT_KEY>` | Read `issueTypes` before creating issues |
+| Search issues | GET `search/jql` | `query: { jql: "project = <PROJECT> AND statusCategory != Done", fields: "summary,status,assignee,priority" }` |
+| Create issue | POST `issue` | `body: { fields: { project: { key: "<PROJECT>" }, summary: "Short title", issuetype: { name: "Task" }, description: <ADF_DOC> } }` |
+| Discover transitions | GET `issue/<KEY>/transitions` | Read `transitions` for the target status |
+| Transition issue | POST `issue/<KEY>/transitions` | `body: { transition: { id: "<TRANSITION_ID>" } }` |
+| Comment | POST `issue/<KEY>/comment` | `body: { body: <ADF_DOC> }` |
+| Find account | GET `user/search` | `query: { query: "<name-or-email>" }` |
+| Assign | PUT `issue/<KEY>/assignee` | `body: { accountId: "<ACCOUNT_ID>" }`; null unassigns |
+| Edit fields | PUT `issue/<KEY>` | `body: { fields: { summary: "New summary", labels: ["swarm"] } }` |
+
+Issue creation returns `{ id, key, self }` (201). The human URL is `https://<your-site>.atlassian.net/browse/<KEY>`. Transitions, assignment, and edits return 204 without a body.
 
 ## ADF cheat-sheet
 
@@ -195,50 +79,17 @@ If you need rich content, build it in a script — don't try to write deep ADF i
 
 ## Operational rules
 
-- **Token-expiry first.** Always check `expiresAt`. Don't loop on 401s.
-- **Use the proxy.** All authenticated calls go through `api.atlassian.com/ex/jira/<cloudId>/...`. Hitting `<your-site>.atlassian.net/rest/api/3/...` with a 3LO bearer token will fail.
-- **Discover transitions per issue** before transitioning — different projects/workflows have different IDs.
-- **Use `/search/jql`**, not the legacy `/search` (which is deprecated and may be removed).
-- **ADF is mandatory** for `description`, `comment`, and rich text fields. Plain strings will be rejected.
-- **Account IDs, not usernames** for assignment, mentions, and filters.
-- **Rate limits:** Atlassian rate-limits per app and per user. For bulk transitions/comments, sleep ~200–500 ms between calls.
-- **Don't leak tokens.** Never echo the access token to logs or Slack. Read it into an env var only.
+- Discover transitions per issue; IDs vary by project and workflow.
+- Use `/search/jql` for cloud searches.
+- Descriptions, comments, and rich text fields require ADF documents.
+- Assignment uses account IDs rather than usernames.
+- For bulk work use the `swarm-scripts` skill, handle pagination, and back off on 429 using `Retry-After`.
+- Check every response before reporting success. On 400 inspect `errorMessages`/`errors`; on 403 confirm scopes and issue permissions with Lead; on 404 verify the cloud ID, project, and issue key. On refresh failure or persistent 401 request re-authorization.
 
-## Error handling
-
-| Status | Likely cause | Action |
-|---|---|---|
-| 401 | Token expired/invalid | Check `expiresAt`. Notify user to re-auth. Don't retry. |
-| 403 | Missing scope, or restricted issue | Check the `scope` column. For `write:jira-work` operations, confirm scope is present. |
-| 404 | Wrong key, wrong cloudId, wrong project | Re-verify with a project list call. |
-| 400 | Body shape wrong (often ADF or required field) | Inspect `errorMessages` / `errors` in the response JSON. |
-| 429 | Rate-limited | Back off, retry after `Retry-After` seconds. |
-
-## Complete worked example: clean a project
-
-```bash
-TOKEN=$(db-query "SELECT accessToken FROM oauth_tokens WHERE provider='jira'")
-CLOUD_ID="<cloud-id>"
-PROJECT_KEY="<PROJECT>"
-
-# 1. List open issues in KAN
-curl -s -G -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-  --data-urlencode "jql=project = $PROJECT_KEY AND statusCategory != Done" \
-  --data-urlencode 'fields=summary,status' \
-  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/search/jql" \
-  | jq -r '.issues[].key' > /tmp/keys.txt
-
-# 2. Transition each to Done using the transition ID discovered for this workflow
-for KEY in $(cat /tmp/keys.txt); do
-  curl -s -X POST \
-    -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-    "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/$KEY/transitions" \
-    -d '{"transition":{"id":"<DONE_TRANSITION_ID>"}}'
-  sleep 0.3
-done
-```
+## Worked workflow: close an issue
 
-## Notes for swarm sync (future)
+1. Run GET `issue/<KEY>/transitions` through the script and select the intended transition from the returned workflow.
+2. Run POST `issue/<KEY>/transitions` with the discovered transition ID.
+3. Confirm the 204 success before reporting the issue transitioned. For multiple issues, discover transitions for each issue and process pagination rather than assuming all workflows match.
 
-- The MCP tracker tools (`tracker-link-task`, `tracker-sync-status`, etc.) are designed for two-way sync mappings. Jira tracker support exists at the schema level but is not currently wired up to inbound webhooks. Until it is, all Jira interaction must go through this skill.
-- If/when inbound Jira webhooks land, this skill should add a "When to transition" section mirroring the Linear one.
+The MCP tracker tools manage sync mappings; they do not replace this authenticated Jira request path.