# auth token expired mid remediation commit run failed - how to fix it

## TL;DR

Refresh auth before committing, and make commits resumable: the agent should check credential expiry before the commit phase and refresh proactively, and if a commit fails on auth, refresh once and retry the commit rather than dropping the patches. One line of why: remediation runs are long, commit credentials expire, and losing finished patches to a 401 is pure waste.

## The error, verbatim

```text
RemediationAgentError: auth expired during commit phase (401)
    patches_ready: 23, committed: 0
    credential: oauth token, ttl 60m, run time 3h

```

## Fix it step by step

### Step 1: Reproduce the commit 401

```bash
node agent/remediate.js --commit | rg -i '401|auth|expired' | head -5
```

Expected: The commit phase dies on expired credentials.

### Step 2: Check the credential lifetime

```bash
node -e "console.log('token ttl 60m, remediation run 3h, refresh: none')"
```

Expected: The math guarantees expiry before commit.

### Step 3: Add pre-commit refresh

```bash
rg -n 'auth|refresh|commit' agent/remediate.js | head -10
```

Expected: Add: refresh credentials before the commit phase; retry once on 401 after refresh.

### Step 4: Re-run remediation

```bash
node agent/remediate.js --commit | tail -4
```

Expected: Patches commit cleanly with fresh credentials.

### Step 5: Add a regression probe

```bash
node agent/run-audit.js --smoke | tail -3
```

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

## When to use this skill

- You run an agent that scans UIs for accessibility and it hits this breakdown
- The agent's scan loop stalls, crashes, or loops on this exact failure
- You are hardening an audit agent's error handling for production scans

## When NOT to use this skill

- A human runs the scan manually and it works, this is agent-harness failure handling
- The scan completes and only reports violations, use the rule-specific skills

## Compatibility

Remediation agent with commit credentials (git remote, API tokens). Refresh depends on the credential type. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent commit 401

Same failure, same refresh.

### remediation auth expired before push

Practitioner phrasing.

### the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

## Why it happens

Remediation runs spend hours scanning and patching, then commit at the end, by which time the OAuth token or session from run start has expired. Agents that authenticate once die at the commit phase with all patches uncommitted. The fix is refreshing before the commit phase (not just at startup) and treating a commit-time 401 as refresh-and-retry-once. Patches should also persist to disk before commit, so even a failed commit loses nothing. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

## Edge cases

- Persist patches to disk before committing, the commit phase should be replayable.
- Never print credential values in logs, log expiry times and refresh events only.
- Short-lived credentials are a feature, the agent adapts with refresh, not with longer-lived secrets.
- Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1HsTMtAMBNXhVdDsVgQwow