pinbox resolve

pinbox resolve closes a pin — one by id, or every open pin linked to a tracker item with --link. Run it once the change is made and verified. Resolving by id is once-only: a second pinbox resolve <id> of the same pin is a conflict, not a no-op. --link only selects open pins, so a repeated run resolves nothing and exits clean. There is no separate “won’t fix” state. A pin you decided not to change is resolved with a note saying so.

Usage

$ pinbox resolve --help
Usage: pinbox resolve [options] [id]

Mark a pin resolved — one by id, or every open pin linked to a tracker item.

Arguments:
  id                      pin id (pin_xxxxxxxxxx); omit with --link

Options:
  --link <connector#ref>  resolve every open pin linked to this item, e.g. github#58
  --note <text>           resolution note (e.g. what changed, or why it won't)
  --as <role>             resolver: human or agent (default: "human")
  --json                  machine output
  -h, --help              display help for command

Arguments

string

Pin id (pin_xxxxxxxxxx). Ids are exact — prefixes do not match. Required unless --link is given.

Options

connector#ref

Resolve every open pin linked to this tracker item instead of one by id — the label pinbox link prints, e.g. github#58. The default note is shipped in github#58. Pins already resolved are left alone, so a second run finds nothing and resolves nothing.

string

Resolution note (e.g. what changed, or why it won’t). Optional, but it is the thing the next reader wants.

string

default:"human"

Resolver: human or agent.

boolean

Machine output: the {"ok":true,"data":…} envelope.

Examples

$ pinbox resolve pin_6dzjtpax70 --note "flex-shrink on the CTA; verified at 1024 and 1280" --as agent
pin_6dzjtpax70 resolved
by agent — flex-shrink on the CTA; verified at 1024 and 1280

The note then shows up on the pin, next to who wrote it:

$ pinbox show pin_6dzjtpax70
pin_6dzjtpax70  resolved  note
text      button is cut off
target    main > button.cta  <button>
url       http://localhost:3000/
rect      120,480 200x48
nearby    "Get started free"
env       1440x900@2x  Chrome 130  macOS  light
git       main @ 40a4130
author    ada
created   2026-08-06T21:20:59.733Z (just now)
resolved  by agent, just now — flex-shrink on the CTA; verified at 1024 and 1280

human  just now  does this also happen at 1024px?
agent  just now  Yes — same overflow at 1024. One fix covers both.

JSON

data is the full updated pin: status flipped, resolution present.

$ pinbox resolve pin_jxf6qu4hpg --note "routed /terms to the new legal page" --as agent --json
{
  "ok": true,
  "data": {
    "text": "terms link 404s",
    "kind": "note",
    "target": {
      "url": "http://localhost:3000/",
      "selector": "footer a.terms",
      "tag": "a",
      "rect": {
        "x": 310,
        "y": 2044,
        "width": 64,
        "height": 18
      },
      "fixed": false
    },
    "env": {
      "viewport": {
        "w": 1440,
        "h": 900,
        "dpr": 2
      },
      "browser": "Chrome 130",
      "os": "macOS",
      "colorScheme": "light",
      "branch": "main",
      "commit": "40a41305d1d1f73aff9884493cfe72474b4c5cee"
    },
    "author": {
      "userId": "ada"
    },
    "id": "pin_jxf6qu4hpg",
    "schemaVersion": 1,
    "status": "resolved",
    "createdAt": "2026-08-06T21:20:59.776Z",
    "resolution": {
      "by": "agent",
      "note": "routed /terms to the new legal page",
      "at": "2026-08-06T21:21:01.816Z"
    }
  }
}

Every pin on a PR

When a branch ships, clear its pins in one call. data is the array of pins resolved — empty when none were still open.

$ pinbox resolve --link github#58 --as agent
pin_6dzjtpax70 resolved
pin_kgoksic8rz resolved
2 pin(s) resolved for github#58

Reviewers have the same action in the toolbar’s inbox, where pins linked to one item are grouped under its header.

Resolving from a commit message

The post-commit hook that pinbox init installs looks for Fixes, Resolves, or Closes followed by a pin id — with or without a colon, case-insensitive — and resolves those pins with the commit SHA attached.

$ git commit -m "widen the CTA hit area

Fixes pin_prpwsggh5r"
resolved pin_prpwsggh5r (1ca3bbe)
[main 1ca3bbe] widen the CTA hit area
 1 file changed, 1 insertion(+), 2 deletions(-)

The resolution records the commit instead of a note:

$ pinbox show pin_prpwsggh5r --json | jq .data.pin.resolution
{
  "by": "agent",
  "commit": "1ca3bbe6b0baa1757fb8ebe5adeb906d29748c8f",
  "at": "2026-08-06T21:24:53.435Z"
}

The hook never blocks a commit. Unknown ids, already-resolved pins, and an unreachable hub all leave the commit alone.

Today the trailer path only resolves pins that carry a full browser target — the ones placed with the toolbar. A pin created with pinbox pin is left open and the hook prints an error next to your commit output. Resolve those with pinbox resolve.

Errors

Exit	Code	When
2	`E_INVALID_INPUT`	neither `id` nor `--link` given; `--link` is not `connector#ref`; or `--as` is outside `human`/`agent`
3	`E_NOT_FOUND`	no pin has that id
4	`E_CONFLICT`	the pin is already resolved
5	`E_HUB_UNREACHABLE`	the hub is absent and could not be started

A second resolve is a conflict, not a no-op — an agent has to notice it raced another resolver.

$ pinbox resolve pin_6dzjtpax70
pinbox: pin_6dzjtpax70 is already resolved
run `pinbox show pin_6dzjtpax70` to see who resolved it and why
$ echo $?
4

$ pinbox resolve pin_kgoksic8rz --as bot
pinbox: invalid --as: "bot" (expected human or agent)
run `pinbox resolve --help` for usage
$ echo $?
2

Next: confirm it with pinbox show, or see what is still open with pinbox summary.

Getting started

CLI

Concepts

Integrations

Self-hosting

Contributing

pinbox resolve

Usage

Arguments

Options

Examples

JSON

Every pin on a PR

Resolving from a commit message

Errors

​Usage

​Arguments

​Options

​Examples

​JSON

​Every pin on a PR

​Resolving from a commit message

​Errors

Usage

Arguments

Options

Examples

JSON

Every pin on a PR

Resolving from a commit message

Errors