Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt

Use this file to discover all available pages before exploring further.

force_unlock removes a file lock held by another agent without the holder’s cooperation. It exists for one specific scenario: an agent crashed mid-task while holding a lock, and waiting for the 30-minute auto-expiry would block work. Every call is logged to the audit trail, which is why the reason parameter is required — the audit entry is how you justify to the team that the unlock was legitimate.
force_unlock on an active agent’s lock will cause them to get a CONFLICT error on their next verify_file_lock or guarded_write. Only use this when you are certain the locking agent is crashed — not just slow.

​
Parameters

​
filePath
string
required
Path of the locked file to force-unlock, relative to the repo root or absolute. Must match the path recorded in the lock (check with list_locks).
​
reason
string
required
Why you are force-unlocking. This is logged to the audit trail and to the project notepad. Be specific — “agent crashed 28 minutes ago” is useful; “needed the file” is not.
​
agentId
string
The admin agent performing the unlock. Recorded in the audit log.
​
projectName
string
The Axis project scope. Defaults to the auto-detected project name.

​
Return value

{
  "status": "unlocked",
  "filePath": "src/auth.ts",
  "previousHolder": "dana-claude-code"
}
FieldDescription
status"unlocked" on success.
filePathThe file that was unlocked.
previousHolderThe agentId that held the lock before the force-unlock.

​
Force-unlock policy

force_unlock is a last resort, not a convenience. The conditions that justify its use are narrow:

Required conditions

  • Lock is older than 25 minutes (visible in list_locks via acquiredAt)
  • Locking agent is clearly crashed — not responding, process gone
  • You have checked that the agent is not just slow or in a long operation

Never acceptable

  • Lock is recent and the holder is active
  • You want the file sooner than the holder will finish
  • You disagree with the holder’s approach
  • Any reason other than a genuine crash
With AXIS_ENFORCE_LOCKS=1 enabled, a crash can leave a file physically chmod’d read-only on disk. force_unlock restores the original file permissions in addition to removing the lock record — so the file becomes writable again for whoever claims it next.

​
Alternatives to force-unlock

Before reaching for force_unlock, work through these options in order:
1

Coordinate via update_shared_context

If the lock is recent, the holder may still be active. Post a message to the shared notepad explaining you need the file. Another agent on the same session may see it.
2

Wait for auto-expiry

All locks auto-expire 30 minutes after grant. If the lock is less than 25 minutes old, waiting is usually faster than the coordination overhead of a forced unlock.
3

Work on something else

list_jobs to find a job that doesn’t touch this file. Come back after the lock expires naturally.
4

Local crash recovery: delete the state file

If the local stdio server itself crashed and left locks in an unrecoverable state, delete history/nerve-center-state.json. This discards all local jobs and locks and resets the coordination board to empty. Use only when no other agent is actively using the local server.
5

force_unlock (last resort)

Only after confirming the locking agent is crashed, the lock is older than 25 minutes, and you have provided a specific reason for the audit log.

​
Example

// 1. Check who holds the lock and when they took it
const locks = await list_locks({ projectName: "acme-app" });
// [{ filePath: "src/auth.ts", agentId: "dana-claude-code",
//    acquiredAt: "2025-01-15T14:30:00Z", expiresAt: "2025-01-15T15:00:00Z" }]

// Current time: 2025-01-15T14:58:00Z — lock is 28 minutes old
// dana-claude-code has not posted to the shared context in 30 minutes

// 2. Force-unlock with a specific, auditable reason
const result = await force_unlock({
  filePath: "src/auth.ts",
  agentId: "sam-cursor",
  reason: "dana-claude-code locked src/auth.ts 28 minutes ago and its process is no longer running. Lock is 2 minutes from natural expiry but blocking critical hotfix.",
  projectName: "acme-app"
});
// { status: "unlocked", filePath: "src/auth.ts", previousHolder: "dana-claude-code" }

// 3. Now acquire the lock normally before editing
await propose_file_access({
  filePath: "src/auth.ts",
  agentId: "sam-cursor",
  intent: "Apply security hotfix for auth bypass — CVE-2025-1234"
});

​
Audit trail

Every force_unlock call is recorded in two places:
  1. Lock events log — a FORCE_UNLOCKED event with the file path, the admin agent, and the reason. Visible in the Axis dashboard under your project’s audit history.
  2. Project notepad — a [FORCE UNLOCK] entry appended to the live notepad, visible to all agents via get_shared_context.
The audit trail is the accountability mechanism. When a force-unlock causes a CONFLICT for an active agent, the reason field is what distinguishes a legitimate crash recovery from a coordination failure.

Build docs developers (and LLMs) love

Get started for freeTalk to us