boxes.py

"""Train Locksmithing on the boxes the hunt brought home:  ;boxes

    ;boxes                  every box in the loot container, then in any other container holding one
    ;boxes source=<bag>     that container alone instead of the profile's `loot_container`
    ;boxes careful          every DISARM and PICK careful, whatever the reading
    ;boxes safe             put back every box reading "longshot" or harder, no exceptions
    ;boxes stand            stay standing (the script sits, which helps)
    ;boxes limit=<n>        stop after n boxes opened
    ;boxes until=<n>        treat that mindstate as the lock instead of 34
    ;boxes once             exit at the lock instead of holding for the drain
    ;boxes tries=<n>        tries at a trap or a lock before the box goes back (5)
    ;boxes return           (typed while it runs) finish the box in hand and end
    ;stop boxes             quit at once

What it does
  - Sits, takes off the `hindering_gear`, and per box: DISARM, PICK, OPEN, empty, DISMANTLE.
  - Puts back a trap reading "longshot" or worse unless it is a nuisance trap;
    a deadly or unknown one always. A sprung toad or mime is waited out (10–15 min).
  - Picks with the `lockpick` or the worn `lockpick_ring`, refilled once a run at
    Ragge's (`lockpick_refill` of `lockpick_kind`; 0 never buys).
  - Coins to the purse, gems to `gem_pouch`, the rest to the loot container.
  - Sits for the work, but stays standing when the load reads Overburdened:
    a sitter that heavy cannot stand again.
  - What `loot_ignore` names (the common metals by default) and a
    `loot_subtractions` noun (never picked up) go in the room's trash;
    with no trash in the room they are kept.
  - At the lock it holds until Locksmithing drains, then goes on.
  - Logs each opened box to history.db (`box_contents`): trap, lock, coins, items,
    and the creature and ground it came from, by the id ;hunt logged at pickup;
    and every IDENTIFY, DISARM, PICK and OPEN sent (`box_attempts`): reading, outcome, rank at the time.

Never a drop
  - An undismantled box goes in the room's bucket only if settings.json's
    `droppable` lists it, else back into the container.
  - A box with no room anywhere is lowered to the feet, and LIFTed again before
    any flight, walk or end, ;stop included.

A room whose guards forbid box work ("Do that somewhere else.", the bank):
it walks to the profile's `home` once and works the boxes there.

When it stops
  - every box tried, the `limit`, or the lock with `once`
  - guards forbid box work here and at `home`, or there is no `home`
  - below `health_floor` or a wound at `wound_floor`, so ;heal can run
  - no lockpick left, death, or hostiles (it flees)
  - ;boxes return; the gear goes back on however it ends

client/game/boxes.py is the model, after dr-scripts' pick.lic and Elanthipedia;
docs/training.md has the profile keys. Report any "boxes: <command> answered ..." line.
"""

import time

from client.engine.scripting import ScriptStopped
from client.game import (
    boxlog,
    discard,
    encumbrance,
    flight,
    gems,
    hands,
    items,
    money,
    probe,
    shop,
    stores,
    trainer,
    travel,
    walker,
)
from client.game import boxes as boxes_model
from client.game.act import ask, missing, said
from client.game.boxes import (
    DISARM_OUTCOMES,
    DISARMED_LOOK,
    already_disarmed,
    LOCK_CAUTION,
    LOCK_READINGS,
    OPEN_OUTCOMES,
    LOCKPICK_CATALOG,
    LOCKPICK_SHOP,
    PICK_OUTCOMES,
    RING_EMPTY,
    RING_REFUSED,
    DISMANTLED,
    TOAD,
    MIME_OVER,
    SKILL,
    TAKE_OUTCOMES,
    TOO_HARD,
    TRAP_CAUTION,
    TRAP_READINGS,
    box_containers,
    boxes_in,
    caution,
    containers,
    held_boxes,
    listed,
    parse_args,
    reading,
)
from client.game.creatures import noun_of, phrase
from client.game.loop import danger, ensure_mindstate, mindstate, wants_stop
from client.game.loot import GEM_NOUNS, ignored, short_name
from client.game.probe import classify
from client.game.wounds import level, parse_health

# The design notes the manual above leaves out: what each rule came
# from, with its issue — read by people, never served as ;help.
_NOTES = """Train Locksmithing on the boxes the hunt brought home:  ;boxes

    ;boxes                      every box in the loot container, then any other container INV LIST shows one in: disarmed, picked, opened, emptied
    ;boxes source=backpack      that container alone instead of the profile's loot_container
    ;boxes careful              every DISARM and PICK careful, whatever the reading says
    ;boxes stand                stay standing (the script sits, which helps)
    ;boxes limit=3              stop after that many boxes opened
    ;boxes until=30             stop at that mindstate instead of 34
    ;boxes once                 exit at mind-lock instead of holding for the drain
    ;boxes safe                 put back every box reading "longshot" or harder, nuisance traps and locks included
    ;boxes tries=15             attempts at a trap or a lock before the box goes back (5 by default)
    ;boxes return               (typed while it runs) finish the box in hand and end

Every DISARM and PICK teaches Locksmithing (Elanthipedia: Locksmithing
skill, Disarm command, Pick command; client/game/boxes.py is the model,
after dr-scripts' pick.lic, which pops boxes the same way). A box
already in hand at the start — ;hunt's, refused by a full loot
container — is PUT into the loot container or any other container
INV LIST shows first, so PICK has its free hand, else LOWERed to the
feet (LOWER <box> TO GROUND, Elanthipedia: Lower command) and worked
first, LIFTed one at a time; a box kept past the reading with no room
in the container goes to the feet too. The at-feet slot is the
character's, not the room's — the janitor never takes it — but no
move is possible while anything lies there (Elanthipedia: Inventory,
At Feet Slot; the operator, 2026-09-26), so before a flight, a walk
to Ragge's and at every end, a `;stop` included, each box is LIFTed
and put into a container with room, else held. Nothing is dropped. A
box at a
time out of the container (GET <box> FROM MY <container>, the next of
its noun by ordinal when one was put back): DISARM MY <box> IDENTIFY
reads the trap's difficulty, and a reading of "longshot" or worse is a
box for a better locksmith, back into the container at once — an
identify of a trap already read comes back with no roundtime and
teaches nothing (2026-09-23: eighty of them in forty seconds left
Locksmithing at 0/34; the 0/34 to 2/34 of the first run was the one
careful DISARM), so the boxes a low rank trains on are boxes it can
read as its own, from lower creatures — unless the trap's look is a
nuisance trap (Elanthipedia: Box traps: frog, laughing gas, mime,
shadowling, sleeper, mana sucker, bouncing box — a toad or a joke,
never a wound), which gets a careful try whatever it reads: at rank 3
every box from the Crossing's grendels read 11 and up (2026-09-25),
so the risk is the only way in. A deadly trap or a look not recognized
goes back; the laughing gas catches the whole room, so it waits for a
room with no other player in it; `safe` puts back every box at or past the
threshold. Else DISARM MY <box> <caution> —
quick, plain or careful by the reading, pick.lic's thresholds — until
the trap is down, up to five tries; then PICK MY <box> IDENTIFY and
PICK MY <box> <caution> the same way — a lock at or past the threshold
tried careful anyway, since a failed pick risks the pick, not the
locksmith — with the profile's `lockpick` in
the free hand (GOT from wherever it is kept, STOWed after) or the
worn `lockpick_ring`, whose top pick the game takes by itself (an
empty ring — its last pick broken, or PICK wanting "a more
appropriate tool" — falls back to the loose `lockpick`, and before
the next box the ring is refilled once a run: the profile's
`lockpick_refill` picks of `lockpick_kind` bought at Ragge's
Locksmithing — ORDER <kind> LOCKPICK, OFFER the quoted price, through
client/game/shop.py (#407) — the teller visited first for a short
purse (shop.afford), each PUT on the ring; `lockpick_refill` 0 never buys); OPEN,
LOOK IN, and every item out — coins to the purse, a gem into the
profile's `gem_pouch`, the rest into the loot container — and the empty
box DISMANTLEd in hand ("...dismantling the oaken crate and tossing the
pieces aside.", 2026-09-26; Elanthipedia: Dismantle command), or, when
that answers otherwise, into the room's bucket through
client/game/discard.py, which only takes a noun settings.json's
`droppable` lists (box, coffer, chest...); a box not on the list goes
back into the container and is said. A frog trap's toad (every command
answering "You're just a simple toad now.") is waited out, ten minutes
at most, before the box is picked up or the gear worn back. It sits
first (the wiki: kneeling or sitting helps) and stands at the end.
Some worn gear hinders every attempt ("Your armor hinders your
attempt." / "Your brass knuckles hinders your attempt.", captured
2026-09-23): the hands, the head and a shield — gauntlets, knuckles, a
leather cowl, a target shield — and not body plate or leg wear, one
piece at a time on 2026-09-26 (docs/training.md). Each noun in the
profile's `hindering_gear` (knuckles, gauntlets, cowl, shield) is REMOVEd and stowed
before the first box — judged by the piece landing in a hand, whatever
the game says — and GOT and worn back when the run ends, however it
ends; a piece that would not come off or go back on is said. Whatever
still hinders after that is said once.

A sprung trap is said with its line; the stun is waited out (up to
five minutes; "You are still stunned." to any step meanwhile is a
wait, not a try — the laughing gas outlasted the old thirty seconds
and the run skipped every box, 2026-09-25), a box knocked to the floor
is picked back up and a prone character sits up again, and a
health below the profile's `health_floor` or a wound at its
`wound_floor` (HEALTH, the hunt's floor) ends the run so ;heal can
run. "You're in no shape to be disarming anything" ends it too. A
broken lockpick is said; with a ring the next pick is the game's to
take, without one the script GETs another and stops when there is none.
The mindstate is the exp window's; at mind-lock the script holds until
Locksmithing drains below 28, then goes on (`once` exits at the lock);
an empty container ends the run. ;train runs it as a task (skills:
["Locksmithing"], script "boxes", return_word "return") after the hunt
and the skins. It stops on death and on hostiles in the room.
The wordings are pick.lic's and the wiki's until captured (2026-09-23):
the first answer of each kind in a run is echoed as
"boxes: <command> answered ..." so they become fixtures — report them.
Stop with:  ;stop boxes, or ;boxes return.

Each opened box is a history.db `box_contents` row (#423, the operator
asked what a ground's boxes are worth, 2026-10-02): its item id off the
hand that holds it, the hardest trap and lock readings, the coins in
copper ("You pick up 5 silver Kronars.", 2026-09-28) and the items,
told to the creature and ground of the `box_drops` row ;hunt wrote at
pickup — by the id, which holds within a login; else the batch of
boxes found since the last run (client/game/boxlog.py).
"""

# A session started before client/game/boxes.py joined RELOADABLE_MODULES
# keeps the copy it first imported (2026-09-23: the loop's first boxes
# task failed on "cannot import name 'HINDERED'" until the relaunch);
# the constants added since are read with a fallback.
HINDERED = getattr(boxes_model, "HINDERED", ("hinders your attempt",))
WORN = getattr(boxes_model, "WORN", ("onto your hands", "you slip", "you slide"))


NUISANCE_TRAPS = getattr(boxes_model, "NUISANCE_TRAPS", ())


def nuisance_trap(answer):
    reader = getattr(boxes_model, "nuisance_trap", None)
    return reader(answer) if reader is not None else None


def hindering_gear(profile):
    reader = getattr(boxes_model, "hindering_gear", None)
    if reader is not None:
        return reader(profile)
    return [str(item).strip().lower() for item in profile.get("hindering_gear") or []]


MIND_LOCK = 34
IDENTIFY_TRIES = 3
WORK_TRIES = 5
MAX_BOXES = 200  # the fuse under the loop
# No SIT at this burden or past it: "You are overburdened and cannot
# manage to stand." (#411, 2026-10-02 — the walk home failed seated).
LOAD_LIMIT = "Overburdened"


def _wordings(*tables):
    """Every wording in the tables given — an outcomes table's rows
    (name, wordings) or a plain tuple of wordings — flattened."""
    found = []
    for table in tables:
        for entry in table:
            if (
                isinstance(entry, tuple)
                and len(entry) == 2
                and isinstance(entry[1], tuple)
            ):
                found.extend(entry[1])
            else:
                found.append(entry)
    return tuple(found)


_NOT_FOUND = ("what were you referring", "could not find")
# The wordings each answer report's kind expects of the game (#410):
# act.said quotes the line holding one, never a bystander's line or
# another script's output that landed first in the window — "look in
# my sack answered 'Name: Lanival ...'" and "get coffer answered
# '<a passer-by> goes out.'" (2026-10-02). The "(unrecognized)" kinds
# have no known wording by definition and keep the first line.
REPORT_NEEDLES = {
    "look in": ("you see", "nothing in", "is empty", "there is nothing", *_NOT_FOUND),
    "look in container": ("you see", "nothing in", "is empty", "there is nothing"),
    "get": ("you get", "you remove", "you pick up", "need a free hand", *_NOT_FOUND),
    "take": _wordings(TAKE_OUTCOMES),
    "open": _wordings(OPEN_OUTCOMES),
    "disarm identify": _wordings(TRAP_READINGS, DISARM_OUTCOMES, DISARMED_LOOK),
    "disarm": _wordings(DISARM_OUTCOMES),
    "pick identify": _wordings(LOCK_READINGS, PICK_OUTCOMES),
    "pick": _wordings(PICK_OUTCOMES),
    "ring": ("you put", "you slide", "onto", "you add", *RING_EMPTY, *RING_REFUSED),
    "wear": WORN,
    "lower": ("you lower", "you set", "lower what", *_NOT_FOUND),
    "lift": ("you lift", "you pick up", "lift what", *_NOT_FOUND),
    "dismantle": (*DISMANTLED, *TOAD, "dismantle what", *_NOT_FOUND),
}
DEFAULT_WOUND_FLOOR = "harmful"


class Run:
    """One run's state: the profile, the container, the boxes put back,
    the answers echoed once."""

    def __init__(self, s, profile, options):
        self.s = s
        self.profile = profile
        self.options = options
        self.container = options["source"] or profile.get("loot_container") or ""
        self.kept = {}  # noun -> boxes put back into the container
        self.moved = False  # walked home once, the guards having forbidden it
        self.kept_elsewhere = 0  # put back into the containers worked before it
        self.kept_from = {}  # creature -> boxes kept this run, by their drop rows (#495)
        self.reported = set()
        self.opened = 0
        self.pick_in_hand = False
        # The worn ring ran out of picks this run: the loose lockpick
        # from here (2026-09-26).
        self.ring_empty = False
        self.refilled = False  # one trip to Ragge's a run at most
        self.doffed = []  # the hindering gear taken off, in order
        self.at_feet = []  # box nouns LOWERed to the feet, not yet lifted
        self.targets = [self.container]  # where a box may go, loot container first
        # The box in hand, for its box_contents row (#423): its item id,
        # the trap and lock readings, the coins and the items out of it.
        self.box = None
        self.started = boxlog.now()  # the run's start: the batch attribution's mark

    def say(self, text):
        self.s.echo(f"boxes: {text}")

    def report(self, kind, command, answer):
        """Echo a run's first answer of each kind, for the fixtures: the
        game's own line, found by the wordings the kind expects
        (REPORT_NEEDLES), never a bystander's that landed first (#410)."""
        if kind in self.reported:
            return
        self.reported.add(kind)
        self.say(f"{command} answered {said(answer, REPORT_NEEDLES.get(kind, ()))!r}")


def hindrance(run, answer):
    """The gear hindering the attempt, said once a run: "Your armor
    hinders your attempt." / "Your brass knuckles hinders your attempt."
    (captured 2026-09-23) — the operator can take it off."""
    if "hindered" in run.reported:
        return
    lines = [
        line.strip()
        for line in answer.splitlines()
        if any(word in line.lower() for word in HINDERED)
    ]
    if lines:
        run.reported.add("hindered")
        run.say(f"{' '.join(lines)} — remove it for better odds")


def doff(run):
    """The profile's hindering gear off and stowed before the first box:
    REMOVE MY <noun>, judged by the piece landing in a hand (REMOVE's
    wordings are uncaptured, 2026-09-23), then STOW; a piece that stays
    on is said with the game's line and left."""
    s = run.s
    for noun in hindering_gear(run.profile):
        free_other_hand(run, "")
        answer = ask(s, f"remove my {noun}")
        s.waitrt()
        if not hands.holding(s, noun):
            run.say(f"the {noun} did not come off — {said(answer)!r}")
            continue
        ask(s, f"stow my {noun}")
        run.doffed.append(noun)
    if run.doffed:
        run.say(f"off and stowed: {', '.join(run.doffed)} — worn back at the end")


def don(run):
    """The gear taken off worn back, last off first: GET MY <noun>, WEAR
    MY <noun>; a piece that will not go on is stowed and said. After a
    `;stop boxes` every read raises, so the rest goes out blind as
    cleanup puts — the gear is never left in the sack; under a trap's
    stun the session holds them until it passes (#318)."""
    s = run.s
    run.donning = None
    try:
        don_reading(run)
    except ScriptStopped:
        # The piece in flight too (2026-09-23: the gauntlets stayed in
        # the backpack after a `;stop` caught the read on their GET).
        pending = ([run.donning] if run.donning else []) + list(reversed(run.doffed))
        for noun in pending:
            s.put(f"get my {noun}", cleanup=True)
            s.put(f"wear my {noun}", cleanup=True)
        run.doffed = []
        raise


def don_reading(run):
    s = run.s
    worn = []
    while run.doffed:
        noun = run.doffed.pop()
        run.donning = noun
        free_other_hand(run, "")
        answer = ask(s, f"get my {noun}")
        if is_toad(answer) and wait_toad(run):
            answer = ask(s, f"get my {noun}")
        if not hands.holding(s, noun):
            run.say(f"the {noun} is nowhere to be worn back — please look for it")
            continue
        answer = ask(s, f"wear my {noun}")
        s.waitrt()
        if hands.holding(s, noun):
            run.say(
                f"the {noun} would not go back on — {said(answer)!r} — stowed instead"
            )
            ask(s, f"stow my {noun}")
            continue
        if not any(word in answer.lower() for word in WORN):
            run.report("wear", f"wear my {noun}", answer)  # a new wording
        worn.append(noun)
    run.donning = None
    if worn:
        run.say(f"worn back: {', '.join(worn)}")


def wound_floor(profile):
    floor = str(profile.get("wound_floor") or "").strip().lower()
    if floor == "off":
        return ""
    return floor or DEFAULT_WOUND_FLOOR


def hurt(run):
    """Why the character should stop after a sprung trap, or None: the
    health below the profile's floor, or HEALTH showing a wound at the
    profile's wound floor."""
    s = run.s
    floor = int(run.profile.get("health_floor") or 0)
    health = getattr(getattr(s, "status", None), "health", None)
    if floor and health is not None and health < floor:
        return f"health {health}% below the floor of {floor}%"
    name = wound_floor(run.profile)
    if not name:
        return None
    try:
        wanted = level(name)
    except ValueError:
        return None
    panel = getattr(s.state, "injuries", None)
    if isinstance(panel, dict) and not panel:
        return None
    health_answer = parse_health(ask(s, "health"))
    hits = health_answer.at_least(wanted)
    if hits:
        area, kind, severity = max(hits, key=lambda hit: hit[2])
        return f"{kind} {area} wound at {severity} — the wound floor is {name}"
    return None


STUN_WAIT = 300  # seconds a sprung trap's stun is waited out at most


def wait_stun(run):
    """A sprung trap's stun waited out, a second at a time — up to five
    minutes: the laughing gas held Lanival past the thirty seconds this
    once waited, and every DISARM after answered "You are still
    stunned." until the boxes were all skipped (2026-09-25)."""
    s = run.s
    for _ in range(STUN_WAIT):
        if not getattr(getattr(s, "status", None), "stunned", False):
            return
        s.sleep(1)


def recover(run, noun):
    """After a sprung trap: the box back in hand if it left it — the
    laughing gas put the skippet on the floor (2026-09-25: "You also see
    a cracked ironwood skippet", and the put-back that followed left it
    there) — and the character back off the floor."""
    s = run.s
    if noun and not hands.holding(s, noun):
        objs = str(getattr(s.state, "room_objs", "") or "").lower()
        if noun.lower() in objs:
            ask(s, f"get {noun}")
            s.waitrt()
            run.say(f"the {noun} was knocked to the floor — picked back up")
    posture = getattr(getattr(s, "status", None), "posture", None)
    if posture == "prone":
        ask(s, "stand" if run.options.get("stand") or too_heavy_to_sit(run) else "sit")
        s.waitrt()


TOAD_WAIT = 600  # seconds the frog trap's toad is waited out at most
TOAD_POLL = 15


def is_toad(answer):
    return any(line in (answer or "").lower() for line in TOAD)


def wait_toad(run):
    """The frog trap's toad waited out: GLANCE (no roundtime) every
    fifteen seconds until it answers as a character again, ten minutes
    at most. On 2026-09-26 the run went on as a toad — the coffer stayed
    on the floor and all four pieces of gear read "nowhere to be worn
    back", every GET answering "You're just a simple toad now." True
    when the toad has worn off."""
    s = run.s
    run.say("turned into a toad by the trap — waiting it out")
    for _ in range(TOAD_WAIT // TOAD_POLL):
        s.sleep(TOAD_POLL)
        if not is_toad(ask(s, "get my nothing-at-all")):
            run.say("a character again")
            return True
    return False


MIME_WAIT = 900  # seconds the mime trap's invisible box is waited out at most
MIME_POLL = 15


def wait_mime(run):
    """The mime trap's invisible box waited out (#497): the stream read
    for the line that ends it ("doing performance art"), MIME_WAIT at
    most — every attempt meanwhile costs a 10 s roundtime and answers
    nothing else (sixteen of them, 2026-10-09). True when it ended."""
    s = run.s
    run.say("caught in the mime trap's invisible box — waiting it out")
    # The cap by the clock: counting only quiet polls let a busy room
    # stretch the wait past it (#497).
    deadline = probe.clock() + MIME_WAIT
    while probe.clock() < deadline:
        line = s.get(timeout=MIME_POLL)
        if line is None:
            continue
        if any(word in line.lower() for word in MIME_OVER):
            run.say("out of the invisible box")
            return True
    run.say(
        f"still in the invisible box after {MIME_WAIT // 60} minutes — trying anyway"
    )
    return False


def sprung(run, answer, noun=""):
    """A trap went off: said, the stun waited out, the roundtime too,
    a toad waited out, the box picked back up; the reason to stop, or
    None."""
    run.say(f"a trap sprung — {said(answer)!r}")
    run.s.waitrt()
    wait_stun(run)
    if is_toad(answer) and not wait_toad(run):
        return "still a toad after ten minutes"
    recover(run, noun)
    return hurt(run)


def too_heavy_to_sit(run):
    """ENCUMBRANCE read: True at LOAD_LIMIT or past it, said once a run
    — a sitter that heavy cannot stand again (#411)."""
    level = encumbrance.parse_level(ask(run.s, "encumbrance"))
    heavy = bool(level) and encumbrance.level_index(level) >= encumbrance.level_index(
        LOAD_LIMIT
    )
    if heavy and "load" not in run.reported:
        run.reported.add("load")
        run.say(f"the load reads {level} — working standing, a sit could not be undone")
    return heavy


def sit(run):
    """SIT for the box work, unless `stand` was asked or the load is too
    heavy to stand up from again."""
    if run.options["stand"]:
        return
    if too_heavy_to_sit(run):
        return
    ask(run.s, "sit")


def stand(run):
    ask(run.s, "stand")


def ready_pick(run):
    """A lockpick in hand when the profile keeps no ring; True when the
    game has one to pick with."""
    profile = run.profile
    if profile.get("lockpick_ring") and not run.ring_empty:
        return True
    if run.pick_in_hand:
        return True
    noun = profile.get("lockpick") or "lockpick"
    answer = ask(run.s, f"get my {noun}")
    lowered = answer.lower()
    if missing(answer) or "get what" in lowered:
        run.say(
            f"no {noun} to pick with — Ragge's Locksmithing in the Crossing sells them"
        )
        return False
    run.pick_in_hand = True
    return True


def ring_ran_out(run):
    """The worn ring is empty — its last pick broke, or PICK found "a
    more appropriate tool" wanting while the ring was the tool (captured
    2026-09-26: the ring's last pick went on a 12/17 crate, and the next
    run read the empty ring as a lock wanting another kind of pick and
    put the crate back). True, said once, the first time; False when
    the ring was already out or none is worn — then the answer is the
    lock's."""
    if not run.profile.get("lockpick_ring") or run.ring_empty:
        return False
    run.ring_empty = True
    run.say(
        "the lockpick ring is empty — the loose lockpick from here "
        "(Ragge's Locksmithing in the Crossing sells picks for the ring)"
    )
    return True


def refill_ring(run):
    """The empty ring refilled (the operator, 2026-09-26): the profile's
    `lockpick_refill` picks of `lockpick_kind` bought at the nearest
    `locksmith` room (Ragge's in the Crossing) — the purse topped up
    at the teller first (shop.afford), each ORDERed and paid through
    shop.buy at up to twice the catalog price — and PUT on the worn
    ring one by one. Once a run. True when the ring holds picks again;
    False, said, otherwise."""
    s, profile = run.s, run.profile
    count = int(profile.get("lockpick_refill") or 0)
    ring = profile.get("lockpick_ring") or ""
    if not ring or count <= 0 or run.refilled:
        return False
    run.refilled = True
    kind = str(profile.get("lockpick_kind") or "ordinary").lower()
    if kind not in LOCKPICK_CATALOG:
        run.say(f"lockpick_kind {kind!r} is not on Ragge's catalog — no refill")
        return False
    price = LOCKPICK_CATALOG[kind]
    mapdb = travel.mapdb()
    if not shop.afford(
        s, ask, "boxes", price * count, "Kronars", db=mapdb, walk=walker.walk
    ):
        run.say("no coins for lockpicks — no refill")
        return False
    store = set(mapdb.rooms_tagged(LOCKPICK_SHOP))
    if not travel.go(s, store, "Ragge's Locksmithing", db=mapdb):
        run.say("could not reach a locksmith — no refill")
        return False
    stacked = 0
    for _ in range(count):
        paid = shop.buy(s, ask, "boxes", f"order {kind} lockpick", max_price=price * 2)
        if paid is None:
            break  # no quote, over twice the price or refused: shop said why
        answer = ask(s, f"put my lockpick on my {ring}")
        if stacked == 0:
            run.report("ring", "put on ring", answer)
        if any(word in answer.lower() for word in RING_REFUSED):
            run.say(
                f"the {ring} refused the pick: {said(answer)!r} — stowed, no more bought"
            )
            ask(s, "stow my lockpick")
            break
        stacked += 1
    if stacked:
        run.ring_empty = False
        run.say(
            f"the {ring} refilled — {stacked} {kind} lockpick(s), "
            f"{money.phrase(stacked * price, 'Kronars')}"
        )
    return bool(stacked)


def put_pick_away(run):
    if run.pick_in_hand:
        ask(run.s, f"stow my {run.profile.get('lockpick') or 'lockpick'}")
        run.pick_in_hand = False


def free_other_hand(run, noun):
    """PICK wants the box in one hand and the other empty (or the pick
    in it): whatever else a hand holds, as the parser knows it, is
    STOWed by its noun (hands.free), the box and the pick kept."""
    pick_noun = run.profile.get("lockpick") or "lockpick"
    keep = tuple(kept for kept in (noun, pick_noun) if kept)
    hands.free(run.s, keep=keep, ask=ask)


def take_box(run, noun):
    """GET the next box of a noun out of the container — past the ones
    put back this run — True when it landed in a hand."""
    which = phrase(noun, run.kept.get(noun, 0) + 1)
    answer = ask(run.s, f"get {which} from my {run.container}")
    run.report("get", f"get {which}", answer)
    lowered = answer.lower()
    return not (
        missing(answer) or any(word in lowered for word in ("get what", "can't"))
    )


FEET = "feet"


def lower_to_feet(run, noun):
    """The box in hand into the at-feet slot — LOWER <item> TO GROUND,
    "You lower the <item> and place it on the ground at your feet."
    (Elanthipedia: Lower command). Not a DROP: the slot stays with the
    character, the janitor never clears it, and it holds fifteen items;
    but no move is possible while anything lies there (Inventory, At
    Feet Slot), so every box lowered is lifted again before the run
    ends or flees (the operator, 2026-09-26). True when it went down."""
    answer = ask(run.s, f"lower {noun} to ground")
    if "at your feet" not in answer.lower():
        run.report("lower", f"lower {noun} to ground", answer)
        return False
    run.at_feet.append(noun)
    return True


def lift(run, noun):
    """LIFT <item>: the box at the feet back into a hand (Elanthipedia:
    Lift command; the answer uncaptured, judged like a GET)."""
    answer = ask(run.s, f"lift {noun}")
    run.report("lift", f"lift {noun}", answer)
    lowered = answer.lower()
    if missing(answer) or any(
        word in lowered for word in ("lift what", "can't", "nothing")
    ):
        return False
    if noun in run.at_feet:
        run.at_feet.remove(noun)
    return True


def into_a_container(run, noun):
    """The box in hand PUT into the first container with room — the loot
    container, then the others INV LIST shows; the container, or None."""
    for container in run.targets:
        answer = ask(run.s, f"put my {noun} in my {container}")
        if "you put" in answer.lower():
            return container
    return None


def clear_feet(run):
    """Nothing left at the feet, before a flight and at every end: each
    box LIFTed and put into a container with room, else held. After a
    `;stop` every read raises, so the LIFTs go out blind as cleanup
    puts — a box left at the feet would hold the character in the room."""
    try:
        for noun in list(run.at_feet):
            if not lift(run, noun):
                run.say(
                    f"the {noun} at your feet would not LIFT — LIFT it before moving"
                )
                continue
            container = into_a_container(run, noun)
            if container:
                run.say(f"the {noun} from your feet goes into the {container}")
            else:
                run.say(
                    f"the {noun} from your feet stays in hand — no container has room"
                )
    except ScriptStopped:
        for noun in run.at_feet:
            run.s.put(f"lift {noun}", cleanup=True)
        run.at_feet = []
        raise


def put_back(run, noun, why):
    """The box in hand back into the container, remembered so the next
    GET passes it; at the feet when the container has no room. False when
    neither took it: the box is still in hand."""
    answer = ask(run.s, f"put my {noun} in my {run.container}")
    if "you put" in answer.lower():
        run.kept[noun] = run.kept.get(noun, 0) + 1
        run.say(f"the {noun} goes back into the {run.container} — {why}")
        return True
    if lower_to_feet(run, noun):
        run.kept_elsewhere += 1
        run.say(
            f"no room in the {run.container}: the {noun} goes down at your feet — {why}"
        )
        return True
    run.say(f"the {noun} does not fit back into the {run.container} — it stays in hand")
    return False


def stash_held(run):
    """Boxes already in hand at the start — ;hunt's, refused by a full
    loot container (2026-09-26: a chest and a casket) — put into the loot
    container, else any container INV LIST shows, else at the feet, so
    both hands are free to pick. Returns ({noun: container or FEET},
    [nouns still in hand]). Nothing is dropped."""
    placed, stuck = {}, []
    for noun in held_boxes(*hands.tags(run.s).values()):
        container = into_a_container(run, noun)
        if container:
            placed[noun] = container
            run.say(f"the {noun} in hand goes into the {container}")
        elif lower_to_feet(run, noun):
            placed[noun] = FEET
            run.say(f"no container has room: the {noun} in hand goes down at your feet")
        else:
            stuck.append(noun)
    return placed, stuck


def risk_trap(run, noun, rank, answer):
    """The caution for a trap past TOO_HARD: "careful" when its look is
    a nuisance trap (a toad, jokes, a nap) and the run takes the risk,
    else None, said — a deadly or unknown trap, `safe`, or a trap that
    hits the whole room while another player stands in it."""
    trap = None if run.options.get("safe") else nuisance_trap(answer)
    if trap is None:
        run.say(f"the {noun}'s trap reads {rank}/17 — {TOO_HARD} or harder, too hard")
        return None
    name, area = trap
    players = list(getattr(run.s.state, "room_players", None) or [])
    if area and players:
        run.say(
            f"the {noun}'s {name} trap would catch {', '.join(players)} too — "
            "left for an empty room"
        )
        return None
    run.say(
        f"the {noun}'s trap reads {rank}/17 — a {name} trap, a nuisance at worst: "
        "trying careful"
    )
    return "careful"


def log_attempt(run, verb, noun, reading, outcome, since):
    """The attempt as a history.db `box_attempts` row (#493): the verb,
    the reading it was made at, the class its answer got, the lockpick
    kind, Locksmithing's rank and mindstate now, and its seconds. Never
    raises."""
    box = run.box or {}
    skills = getattr(run.s.state, "experience", None) or {}
    skill = skills.get(SKILL) if isinstance(skills, dict) else None
    skill = skill if isinstance(skill, dict) else {}
    boxlog.log_attempt(
        run.s,
        run_started=run.started,
        box_id=box.get("box_id"),
        noun=noun,
        verb=verb,
        reading=reading,
        outcome=outcome or "unknown",
        lockpick=str(run.profile.get("lockpick_kind") or "ordinary").lower(),
        rank=skill.get("rank"),
        mindstate=skill.get("mindstate"),
        seconds=round(time.monotonic() - since, 1),
    )


def disarm(run, noun):
    """The traps off a box: "clear", "too hard", "stop:<why>" or
    "lost"."""
    s = run.s
    for _round in range(run.options.get("tries") or WORK_TRIES):
        rank = None
        for _ in range(IDENTIFY_TRIES):
            since = time.monotonic()
            answer = ask(s, f"disarm my {noun} identify")
            s.waitrt()
            run.report("disarm identify", "disarm identify", answer)
            hindrance(run, answer)
            outcome = classify(answer, DISARM_OUTCOMES)
            seen = reading(answer, TRAP_READINGS)
            log_attempt(
                run,
                "identify",
                noun,
                seen,
                outcome
                or ("read" if seen is not None else None)
                or ("already disarmed" if already_disarmed(answer) else None),
                since,
            )
            if outcome == "forbidden":
                return "stop:forbidden"
            if outcome == "sprung":
                why = sprung(run, answer, noun)
                if why:
                    return f"stop:{why}"
                continue
            if outcome == "stunned":
                wait_stun(run)  # nothing was tried: wait, take the step again
                recover(run, noun)
                continue
            if outcome == "boxed":
                wait_mime(run)
                continue
            if outcome == "injured":
                return "stop:too hurt to disarm anything"
            if outcome == "lost":
                return "lost"
            if outcome == "no trap":
                note_reading(run, "trap", 0)
                return "clear"
            if already_disarmed(answer):
                # The look with a roundtime and no reading (#418): the
                # trap is down already — thirty boxes were "would not
                # identify", re-asked and disarmed again for nothing.
                run.say(f"the {noun}'s trap is already down — on to the lock")
                return "clear"
            rank = reading(answer, TRAP_READINGS)
            if rank is not None:
                note_reading(run, "trap", rank)
                break
            if outcome != "identify failed":
                run.report("disarm identify?", "disarm identify (unrecognized)", answer)
        if rank is None:
            run.say(f"the {noun}'s trap would not identify — treating it as careful")
            word = "careful"
        else:
            word = caution(rank, TRAP_CAUTION)
            if word is None:
                word = risk_trap(run, noun, rank, answer)
                if word is None:
                    return "too hard"
        if run.options["careful"]:
            word = "careful"
        command = f"disarm my {noun} {word}".strip()
        since = time.monotonic()
        answer = ask(s, command)
        s.waitrt()
        run.report("disarm", "disarm", answer)
        hindrance(run, answer)
        outcome = classify(answer, DISARM_OUTCOMES)
        log_attempt(run, "disarm", noun, rank, outcome, since)
        if outcome == "forbidden":
            return "stop:forbidden"
        if outcome == "sprung":
            why = sprung(run, answer, noun)
            if why:
                return f"stop:{why}"
            continue
        if outcome == "stunned":
            wait_stun(run)  # nothing was tried: wait, take the step again
            recover(run, noun)
            continue
        if outcome == "boxed":
            wait_mime(run)
            continue
        if outcome == "injured":
            return "stop:too hurt to disarm anything"
        if outcome == "lost":
            return "lost"
        if outcome in ("disarmed", "no trap"):
            run.say(f"the {noun}'s trap is down ({word or 'plain'}, read {rank}/17)")
            continue  # IDENTIFY again: another trap, or none
        if outcome in ("retry", "identify failed"):
            # "identify failed" here is the shift line after a failed
            # attempt ("your manipulation caused something to shift",
            # 2026-09-23) — the trap moved, and the next IDENTIFY reads
            # it again, harder (10/17 to 11/17 that night).
            continue
        run.report("disarm?", "disarm (unrecognized)", answer)
    return "too hard"


def pick(run, noun):
    """The locks off a box: "open", "too hard", "stop:<why>" or
    "lost"."""
    s = run.s
    for _round in range(run.options.get("tries") or WORK_TRIES):
        if not ready_pick(run):
            return "stop:no lockpick"
        rank = None
        for _ in range(IDENTIFY_TRIES):
            since = time.monotonic()
            answer = ask(s, f"pick my {noun} identify")
            s.waitrt()
            run.report("pick identify", "pick identify", answer)
            hindrance(run, answer)
            outcome = classify(answer, PICK_OUTCOMES)
            seen = reading(answer, LOCK_READINGS)
            log_attempt(
                run,
                "identify",
                noun,
                seen,
                outcome or ("read" if seen is not None else None),
                since,
            )
            if outcome == "forbidden":
                return "stop:forbidden"
            if outcome == "sprung":
                why = sprung(run, answer, noun)
                if why:
                    return f"stop:{why}"
                continue
            if outcome == "stunned":
                wait_stun(run)  # nothing was tried: wait, take the step again
                recover(run, noun)
                continue
            if outcome == "boxed":
                wait_mime(run)
                continue
            if outcome == "injured":
                return "stop:too hurt to pick anything"
            if outcome == "lost":
                return "lost"
            if outcome == "not locked":
                note_reading(run, "lock", 0)
                return "open"
            if outcome == "wrong pick":
                if ring_ran_out(run):
                    if not ready_pick(run):
                        return "stop:no lockpick"
                    continue
                run.say(f"the {noun}'s lock wants another kind of lockpick — left")
                return "too hard"
            if outcome == "free hand":
                free_other_hand(run, noun)
                continue
            rank = reading(answer, LOCK_READINGS)
            if rank is not None:
                note_reading(run, "lock", rank)
                break
        if rank is None:
            run.say(f"the {noun}'s lock would not identify — treating it as careful")
            word = "careful"
        else:
            word = caution(rank, LOCK_CAUTION)
            if word is None:
                if run.options.get("safe"):
                    run.say(
                        f"the {noun}'s lock reads {rank}/17 — {TOO_HARD} or harder, too hard"
                    )
                    return "too hard"
                # A lock has no trap: a failed pick costs roundtime and
                # now and then the pick, never a wound.
                run.say(
                    f"the {noun}'s lock reads {rank}/17 — {TOO_HARD} or harder, "
                    "trying careful anyway (a lock only risks the pick)"
                )
                word = "careful"
        if run.options["careful"]:
            word = "careful"
        command = f"pick my {noun} {word}".strip()
        since = time.monotonic()
        answer = ask(s, command)
        s.waitrt()
        run.report("pick", "pick", answer)
        hindrance(run, answer)
        outcome = classify(answer, PICK_OUTCOMES)
        log_attempt(run, "pick", noun, rank, outcome, since)
        if outcome == "forbidden":
            return "stop:forbidden"
        if outcome == "sprung":
            why = sprung(run, answer, noun)
            if why:
                return f"stop:{why}"
            continue
        if outcome == "stunned":
            wait_stun(run)  # nothing was tried: wait, take the step again
            recover(run, noun)
            continue
        if outcome == "boxed":
            wait_mime(run)
            continue
        if outcome == "injured":
            return "stop:too hurt to pick anything"
        if outcome == "lost":
            return "lost"
        if outcome in ("unlocked", "not locked"):
            run.say(f"the {noun} is unlocked ({word or 'plain'}, read {rank}/17)")
            return "open"
        if outcome == "more locks":
            continue
        if outcome == "wrong pick":
            if ring_ran_out(run):
                if not ready_pick(run):
                    return "stop:no lockpick"
                continue
            run.say(f"the {noun}'s lock wants another kind of lockpick — left")
            return "too hard"
        if outcome == "broken pick":
            run.pick_in_hand = False
            run.say("the lockpick broke")
            if any(line in answer.lower() for line in RING_EMPTY):
                ring_ran_out(run)
                if not ready_pick(run):
                    return "stop:no lockpick"
            continue
        if outcome == "no pick":
            run.pick_in_hand = False
            if not ready_pick(run):
                return "stop:no lockpick"
            continue
        if outcome == "retry":
            continue
        run.report("pick?", "pick (unrecognized)", answer)
    return "too hard"


def stow_loot(run, item):
    """An item out of the box into the pouch (a gem) or the container."""
    s = run.s
    noun = noun_of(item)
    pouch = run.profile.get("gem_pouch")
    if pouch and noun in GEM_NOUNS:
        # Into the first pouch with room, by id (#456). Every pouch full
        # (#436: "You've already got a wealth of gems in there!"), the gem
        # goes with the loot, and the gems chore pouches it later (#437).
        ref = items.ref(s, noun) or f"my {noun}"
        if gems.put(s, run.profile, ref, ask)[0]:
            gems.room()
            return
        gems.mark()
    if run.container:
        answer = ask(s, f"put my {noun} in my {run.container}")
        if "room" not in answer.lower() and "can't" not in answer.lower():
            return
    ask(s, f"stow my {noun}")


def empty(run, noun):
    """OPEN the box, LOOK IN it, GET everything out; the count taken."""
    s = run.s
    since = time.monotonic()
    answer = ask(s, f"open my {noun}")
    run.report("open", "open", answer)
    outcome = classify(answer, OPEN_OUTCOMES)
    log_attempt(run, "open", noun, None, outcome, since)  # "open", "locked", "lost"
    if outcome == "locked":
        run.say(f"the {noun} is still locked — left as it is")
        return None
    if outcome == "lost":
        return None
    items = listed(answer)
    if items is None:
        answer = ask(s, f"look in my {noun}")
        run.report("look in", "look in", answer)
        items = listed(answer) or []
    taken = 0
    for item in items:
        thing = noun_of(item)
        if thing in ("stuff",):
            continue
        # An ignored item comes out by its short name, so GET takes it
        # and not a kept one of the same noun (#365). A "never pick up"
        # noun (loot_subtractions, the runestones, #442) comes out too —
        # the box is dismantled empty — and goes the same way.
        never = {
            str(n).strip().lower() for n in run.profile.get("loot_subtractions") or ()
        }
        ignore = (
            "loot_ignore"
            if ignored(item, run.profile.get("loot_ignore") or ())
            else "loot_subtractions"
            if thing in never
            else ""
        )
        if ignore:
            thing = short_name(item)
        answer = ask(s, f"get {thing} from my {noun}")
        run.report("take", "get from box", answer)
        outcome = classify(answer, TAKE_OUTCOMES)
        if outcome == "free hand":
            put_pick_away(run)
            answer = ask(s, f"get {thing} from my {noun}")
            outcome = classify(answer, TAKE_OUTCOMES)
        box = run.box if run.box is not None else {"items": [], "trashed": []}
        if outcome == "coins":
            # "You pick up 5 silver Kronars." (captured 2026-09-28); one
            # box can hold two currencies, each pickup naming its own
            # ("You pick up 4 silver Dokoras.", 2026-10-02, #425).
            currency = (money.currency_of(answer) or "Kronars").lower()
            box[currency] = box.get(currency, 0) + money.to_copper(answer)
            taken += 1
            continue
        if outcome == "taken" and ignore:
            trashed = discard.trash(s, thing, ask)
            if trashed is None:
                run.say(f"no trash here for the {thing} ({ignore}) — kept")
                stow_loot(run, item)
                box["items"].append(item)
            else:
                run.say(f"the {thing} is on {ignore} — in the trash")
                box["trashed"].append(item)
            taken += 1
            continue
        if outcome == "taken":
            stow_loot(run, item)
            box["items"].append(item)
            taken += 1
            continue
        if outcome == "no room":
            run.say(f"no room for the {thing} — it stays in the {noun}")
            ask(s, f"put my {thing} in my {noun}")
            continue
    return taken


def dispose(run, noun):
    """The emptied box DISMANTLEd in hand (the operator, 2026-09-26:
    "You should be able to DISMANTLE the empty boxes"); an answer that is
    not the dismantling goes the old way — the room's bucket through
    discard.drop for a noun on the droppable list — else back into the
    container."""
    s = run.s
    answer = ask(s, f"dismantle my {noun}")
    s.waitrt()
    if any(line in answer.lower() for line in DISMANTLED):
        return True
    run.report("dismantle", f"dismantle my {noun}", answer)
    if discard.droppable(noun):
        answer = discard.drop(s, noun, lambda handle, command: ask(handle, command))
        if answer is not None:
            return True
    put_back(run, noun, "empty, but not on settings.json's droppable list")
    return False


def kept(run, noun):
    """A box past the reading, back into the container: "kept". No
    practising on it — an identify of a trap already read is free of
    roundtime and of experience (2026-09-23: eighty in forty seconds,
    Locksmithing unmoved), and a DISARM past the reading is the trap
    sprung, not the skill trained. A container with no room for it ends
    the run: PICK wants the other hand free."""
    box = run.box or {}
    found = boxlog.origin(run.s, box.get("box_id"), noun, run.started)
    creature = (found or {}).get("creature") or "an unknown creature"
    run.kept_from[creature] = run.kept_from.get(creature, 0) + 1
    if not put_back(run, noun, "for a better locksmith"):
        return f"stop:the {noun} is in hand with nowhere to go"
    return "kept"


def move_home(run):
    """The guards forbid box work here: walk to the profile's `home` (a
    ;go2 target) once, anything at the feet LIFTed first, and sit again.
    False, said, when the run has moved already, names no home, or the
    walk fails. ;hunt's last chore is ;skins bank, so a ;train box task
    after a box farm starts in the bank (2026-09-29, #391)."""
    if run.moved:
        return False
    run.moved = True
    home = str(run.profile.get("home") or "").strip()
    if not home:
        run.say("the guards here forbid box work, and the profile names no home")
        return False
    run.say(f"the guards here forbid box work — walking home ({home})")
    clear_feet(run)
    stand(run)
    if not travel.go(run.s, home, "home"):
        run.say("could not reach home")
        return False
    sit(run)
    return True


def one_box(run, noun, source="container"):
    """One box out, worked and away: "done", "kept", "lost" or
    "stop:<why>". `source`: "container" (GET it), "feet" (LIFT it) or
    "hand" (in hand already)."""
    if source == FEET:
        if not lift(run, noun):
            return "lost"
    elif source != "hand" and not take_box(run, noun):
        return "lost"
    run.box = new_box(run, noun)
    outcome = disarm(run, noun)
    if outcome.startswith("stop:"):
        put_back(run, noun, "the run ends")
        return outcome
    if outcome == "lost":
        return "lost"
    if outcome == "too hard":
        log_attempt(
            run, "disarm", noun, run.box.get("trap"), "too hard", time.monotonic()
        )
        return kept(run, noun)
    outcome = pick(run, noun)
    if outcome.startswith("stop:"):
        put_back(run, noun, "the run ends")
        return outcome
    if outcome == "lost":
        return "lost"
    if outcome == "too hard":
        log_attempt(
            run, "pick", noun, run.box.get("lock"), "too hard", time.monotonic()
        )
        return kept(run, noun)
    put_pick_away(run)
    taken = empty(run, noun)
    if taken is None:
        put_back(run, noun, "it would not open")
        return "kept"
    run.opened += 1
    run.say(f"the {noun} opened — {taken} item(s) out ({run.opened} box(es) so far)")
    record_box(run)
    dispose(run, noun)
    return "done"


def new_box(run, noun):
    """The record of the box now in hand (#423): its item id off the
    hand tag, the readings and the contents filled in as it is worked."""
    tag = hands.tag_of(run.s, noun) or {}
    return {
        "box_id": tag.get("exist"),
        "noun": noun,
        "trap": None,
        "lock": None,
        "kronars": 0,  # copper per currency: boxlog sums their worth (#425)
        "lirums": 0,
        "dokoras": 0,
        "items": [],
        "trashed": [],
    }


def note_reading(run, key, rank):
    """The hardest trap or lock reading of the box in hand: rank 1-17,
    0 for none found."""
    if run.box is not None and rank is not None:
        run.box[key] = max(run.box[key] or 0, rank)


def record_box(run):
    """The opened box as a history.db `box_contents` row, told to the
    creature and ground that dropped it (boxlog, #423); said when it
    could be."""
    box, run.box = run.box, None
    if box is None:
        return
    origin = boxlog.log_opened(run.s, run_started=run.started, **box)
    if origin and origin.get("ground"):
        what = origin.get("creature") or "a creature"
        how = (
            "by its id"
            if origin["source"] == "id"
            else "by the batch since the last run"
        )
        run.say(f"the {box['noun']} came from {what} at {origin['ground']} ({how})")


def run_loop(s, profile, options):
    run = Run(s, profile, options)
    if not run.container:
        run.say("no container — source=<container>, or the profile's loot_container")
        return
    value = ensure_mindstate(s, SKILL, lambda handle, command: ask(handle, command))
    if value is None:
        run.say(f"EXP shows no {SKILL} — nothing to train")
        return
    primary = run.container
    possessions = getattr(s.state, "possessions", None) or []
    run.targets = [primary] + [c for c in containers(possessions) if c != primary]
    placed, stuck = stash_held(run)
    if len(stuck) > 1:
        run.say(
            f"the {stuck[0]} and the {stuck[1]} are in hand and neither a container "
            "nor your feet took them — PICK wants a free hand; nothing is dropped, "
            "make room and start again"
        )
        clear_feet(run)
        return
    answer = ask(s, f"look in my {primary}")
    run.report("look in container", f"look in my {primary}", answer)
    nouns = boxes_in(answer)
    if nouns is None:
        run.say(f"cannot read the {primary} — is it worn or held, and open?")
        clear_feet(run)
        return
    sources = [(primary, nouns)] if nouns else []
    # Boxes that landed elsewhere — a full sack's STOW, a hand's put-away
    # — are worked after the loot container's, unless source= named one
    # (#323). INV LIST (the parser's possessions) says where they are.
    if not options["source"]:
        possessions = getattr(s.state, "possessions", None) or []
        # A box just put away from a hand is there whatever the login's
        # INV LIST says.
        extra = box_containers(possessions, primary)
        extra += [
            c for c in placed.values() if c not in (primary, FEET) and c not in extra
        ]
        # Where STOW BOX put the boxes since that listing: the STORE
        # container ;hunt last set, which can differ from the loot
        # container the profile names now (#432: three boxes in the sack
        # after the profile moved to the tote mid-farm).
        stored = stores.boxes_container(getattr(s.state, "name", None))
        if stored and stored != primary and stored not in extra:
            extra.append(stored)
        for container in extra:
            found = boxes_in(ask(s, f"look in my {container}")) or []
            if found:
                sources.append((container, found))
    feet = list(run.at_feet)
    if not sources and not stuck and not feet:
        run.say(f"no boxes in the {primary} — nothing to pick")
        return
    if stuck:
        run.say(f"the {stuck[0]} in hand fits nowhere — it is worked first")
    if feet:
        run.say(
            f"{len(feet)} box(es) at your feet — worked first, LIFTed one at a time"
        )
    for container, found in sources:
        run.say(f"{len(found)} box(es) in the {container} — {SKILL} {value}/34")
    try:
        doff(run)
        sit(run)
        work = (
            [(primary, noun, "hand") for noun in stuck]
            + [(primary, noun, FEET) for noun in feet]
            + [
                (container, noun, "container")
                for container, found in sources
                for noun in found
            ]
        )
        for container, noun, source in work[:MAX_BOXES]:
            if container != run.container:
                run.kept_elsewhere += sum(run.kept.values())
                run.container, run.kept = container, {}
            reason = danger(s)
            if reason:
                run.say(f"{reason} — stopping")
                if "hostiles" in reason:
                    clear_feet(run)  # no move is possible with a box there
                    stand(run)
                    flight.react(s, "boxes")
                return
            if wants_stop(s):
                run.say("stopping as asked")
                return
            value = mindstate(s, SKILL)
            if value is not None and value >= options["until"]:
                if options["once"]:
                    run.say(f"{SKILL} at {value}/34 — done")
                    return
                if not trainer.hold_at_lock(
                    s, "boxes", SKILL, options["until"], again="picking again"
                ):
                    run.say("stopping")
                    return
            if run.ring_empty and not run.refilled:
                # Between boxes, the loose pick put away: the trip to
                # Ragge's for the ring (the operator, 2026-09-26).
                put_pick_away(run)
                clear_feet(run)  # the walk to Ragge's
                refill_ring(run)
            outcome = one_box(run, noun, source)
            if outcome == "stop:forbidden" and move_home(run):
                # Put back for "the run ends" — not kept: the same box again.
                run.kept[noun] = max(0, run.kept.get(noun, 0) - 1)
                outcome = one_box(run, noun)
            if outcome == "stop:forbidden":
                outcome = "stop:guards forbid box work here"
            if outcome == "stop:no lockpick":
                clear_feet(run)  # the walk to Ragge's
            if outcome == "stop:no lockpick" and refill_ring(run):
                # Nothing to pick with at all: the ring refilled, the
                # same box again (put back for "the run ends" — not kept).
                run.kept[noun] = max(0, run.kept.get(noun, 0) - 1)
                outcome = one_box(run, noun)
            if outcome.startswith("stop:"):
                why = outcome[5:]
                run.say(f"{why} — stopping")
                if "hostiles" in why:
                    clear_feet(run)
                    stand(run)
                    flight.react(s, "boxes")
                return
            if outcome == "lost":
                run.say(f"the {noun} is nowhere — on to the next")
            if options["limit"] and run.opened >= options["limit"]:
                run.say(f"{run.opened} box(es) opened — the limit")
                return
        run.say(
            f"every box tried — {run.opened} opened, "
            f"{run.kept_elsewhere + sum(run.kept.values())} kept for a better locksmith"
        )
        if run.kept_from:
            # Whose boxes beat the character this run (#495): ;hunt leaves
            # a creature's boxes once three in a row went back unopened.
            whose = ", ".join(f"{n} from {c}" for c, n in sorted(run.kept_from.items()))
            run.say(f"kept: {whose} — past your Locksmithing; ;hunt leaves theirs now")
    finally:
        try:
            put_pick_away(run)
            don(run)
        finally:
            # After the gear is back on, both hands free: nothing is left
            # at the feet to hold the character in the room.
            clear_feet(run)
        stand(run)


def main(s):
    name = getattr(s.state, "name", None)
    from client.game.profile import load_profile

    profile = load_profile(name) if name else {}
    run_loop(s, profile, parse_args(s.args or []))