/ 
App-karr-0.500
/ App::karr::Cmd::Unlock

NAME

App::karr::Cmd::Unlock - Show and break task pick locks

VERSION

version 0.500

SYNOPSIS

karr unlock
karr unlock 12
karr unlock 12,14 --json
karr unlock --all

DESCRIPTION

Shows the karr pick locks currently held on the board, and breaks them on request.

Run with no arguments it only reports: one line per lock with the task it covers, the identity holding it, how long it has been held, and whether that is past the board's lock_timeout. Nothing is destroyed unless a task id or --all is given.

WHY THIS EXISTS

karr pick takes a lock ref, claims a card, and gives the lock back inside one command, so under normal use there is nothing here to see. An agent that dies in between -- killed mid-run, or a push that failed and aborted the command -- left one behind, and before #45 that ref was permanent: no command could clear it, karr delete could not reach it, and every other agent skipped that task forever. Digging the board out took a git update-ref -d by hand.

Locks now expire on their own (lock_timeout, default 5m), which is what an unattended agent needs. This command is the other half: the way a human sees what is stuck and clears it now instead of waiting, and the only way out at all on a board that has set lock_timeout to 0s.

STRAY LOCKS

Locks used to live inside refs/karr/*, so a sync while one was held published it and every other clone pulled it (#93). They are outside the board namespace now, but the ones already published do not disappear on their own: an older karr, or a pull from a remote that still carries them, leaves refs at the old address.

Nothing acts on those any more -- a lock taken in another clone says nothing about this process -- but they are listed here, marked [stray: pushed by an older karr, safe to break], and breaking a lock clears the old address along with the current one. That is how a board that was published with locks in it gets clean again.

Breaking a lock is safe by construction: it is not what makes a pick exclusive. The claim is written under a compare-and-swap on the card itself ("EXCLUSIVITY" in App::karr::Cmd::Pick), so an agent whose lock is broken out from under it mid-pick either completes its claim untouched or loses that swap to whoever got there first. It can never overwrite somebody else's claim.

OPTIONS

  • --all

    Break every lock on the board instead of named ones.

  • --json

    Emit the locks, or the results of breaking them, as JSON.

SEE ALSO

karr, App::karr, App::karr::Cmd::Pick, App::karr::Lock, App::karr::Cmd::Config

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.