DEV Community: Raknaos

My HTTP timing tool could not even start on Python 3.11

Raknaos — Sat, 19 Sep 2026 09:07:25 +0000

The first version of a small HTTP timing tool failed before it could measure a request.

That sounds like an ordinary syntax mistake, but it exposed exactly why I run a tool locally before I write about it. The README showed a useful command and a self-test. The repository looked like a tiny, dependency-free utility. On this machine, the advertised self-test did not reach the local HTTP server at all: Python stopped while parsing the file.

The failure was in the renderer, not in DNS, TCP, TLS, or HTTP. One f-string used a backslash escape inside an expression:

lines.append(f"  {'total':>10s}  {'\\u2588' * width}  {total*1000:7.1f}ms")

Python 3.11 reports SyntaxError: f-string expression part cannot include a backslash. The README says the project requires Python 3.7+, so this is not a theoretical compatibility edge case. It is a startup failure on a supported interpreter.

That was the problem I wanted to solve in the first place: when an HTTP request is slow, “the server is slow” is not a diagnosis. The delay may be name resolution, the TCP handshake, TLS, waiting for the first response byte, or downloading the response. I wanted a small command that made those phases visible without installing a package or remembering a larger profiling stack.

The design is deliberately small

httpstat-lite is a standalone Python script. The repository contains httpstat_lite.py, and its implementation uses the standard library: argparse, socket, ssl, time, and urllib.parse, with the self-test importing http.server and threading when needed.

The core measurement function records a wall-clock start, resolves the host with socket.getaddrinfo, opens an IPv4 TCP socket, optionally wraps it with the default TLS context, sends a minimal HTTP/1.1 GET request, and measures the first received byte as TTFB. It then reads until the socket closes and records the download and total durations.

That decomposition is useful because each number answers a different question. DNS tells me whether resolving the host is expensive. Connect tells me whether reaching the address is expensive. TLS separates the secure handshake from the TCP connection. TTFB includes the wait after sending the request until the first byte arrives. Download measures the remaining read. Total is the complete elapsed time recorded by the script.

The request itself is intentionally direct:

req = f"GET {path} HTTP/1.1\\r\\nHost: {host}\\r\\nConnection: close\\r\\n\\r\\n"
sock.sendall(req.encode())
sock.recv(1)  # first byte

There is no HTTP client dependency and no attempt to become a general-purpose HTTP implementation. The script is a timing probe, not a browser and not a response validator.

The output is an ASCII chart. Each phase receives a bar proportional to its share of the measured total, followed by milliseconds. A successful run is intended to look like this:

         dns  ████   12.3ms
     connect  ██████   25.1ms
         tls  ████   15.0ms
        ttfb  ██████████████████   80.2ms
    download  ███   10.5ms
       total  ████████████████████████████████████████  143.1ms

The normal command is one line:

python3 httpstat_lite.py https://example.com

The repository also defines an offline self-test. It starts a local http.server, measures a loopback URL, checks that DNS, connect, TTFB, download, and total timings exist, renders the chart, and prints self-test: PASS when those assertions succeed. Running that command is part of my verification routine, not a claim I can replace with a README reading.

On the checked-out source, however, the self-test currently fails earlier with the Python 3.11 syntax error shown above. That is the honest state of this revision. The measurement approach is easy to inspect, but the advertised compatibility claim and the executable source disagree until the f-string is rewritten.

The fix is smaller than the diagnosis

The problematic expression does not need to build the bar inside the f-string. The renderer already does this correctly for every other phase:

bar = "\\u2588" * bar_len
lines.append(f"  {phase:>10s}  {bar}  {ms:7.1f}ms")

The total line should follow the same rule: create the bar before formatting the string, or use a literal character outside the expression. That keeps the code compatible with the stated Python 3.7+ requirement and makes the line easier to read.

This is also why I prefer a local self-test over a green-looking interface. A small CLI can have a simple design and still fail at the first byte of execution. In this case, the failure is not hidden in a rare network path; it is visible to the parser before any socket is opened.

What it does not do

This tool does not measure every possible HTTP detail. It uses IPv4 address resolution and the first address returned by getaddrinfo. It sends a GET request and reads until the connection closes. It does not expose response headers, status-code validation, redirects, HTTP/2, HTTP/3, proxy configuration, or a full response body report. Its TTFB number is the elapsed time until one byte is received, not a server-side processing measurement.

It also cannot tell me why a phase is slow. It shows where the time was observed. I still need logs, repeated samples, and knowledge of the network path to explain the cause.

The cost is the standard library already present in Python. There is no package installation and no network dependency for the self-test once the syntax issue is fixed. The normal URL measurement, of course, contacts the URL I provide.

Try it

The source, MIT license, usage example, and self-test are in the repository:

https://github.com/Raknaos/httpstat-lite

Download the script and run:

python3 httpstat_lite.py --self-test
python3 httpstat_lite.py https://example.com

Run the first command on the exact revision you intend to use. That one habit caught this bug before the timing chart could pretend to be evidence.

My CSV diff tool reported a new row as removed, and its self-test cannot run

Raknaos — Tue, 15 Sep 2026 09:12:34 +0000

Last week I compared two CSV snapshots of a price table, one export from staging, one from production, with a tool from my lab: csv-key-diff. It takes two CSVs, a key column, and returns a JSON object with added, removed and changed arrays. It is 76 lines of Python, stdlib-only, nothing to install.

The production export had a row that staging did not have. That is an addition. The tool reported it under removed.

I only caught it because the row counts did not line up between the two exports, and the JSON said "added": [] while naming exactly one row in removed. One of those two statements had to be about my new row, and the array claiming "nothing appeared" was the wrong one.

What the code actually says

The whole comparison is three lines:

def compute_diff(data1, data2, key):
    added = [data1[k] for k in data1 if k not in data2]
    removed = [data2[k] for k in data2 if k not in data1]
    changed = [data1[k] for k in data1 if k in data2 and data1[k] != data2[k]]
    return {'added': added, 'removed': removed, 'changed': changed}

added iterates over data1, the first file argument. removed iterates over data2, the second. Read as an operation it is coherent: "what the first file holds that the second lost". Read as English, it is backwards. Every diff I use daily, diff old new, git diff a b, is oriented forward: what the new file brought.

Here is what that costs me on real files:

$ python3 csv_key_diff.py a.csv b.csv --key id
{"added": [], "removed": [{"id": "3", "name": "qux"}], "changed": [{"id": "2", "name": "bar"}]}

b.csv is the file where id 3 appeared and where id 2's name became BAZ. The tool calls the arrival a removal and reports the row it replaced.

That second part is a separate decision hiding in the same line: changed yields data1[k], the old row. A changed entry tells you which key moved and where it came from, never where it went. For a review workflow, the value you actually need is the half that is missing.

The README line for the tool is python csv_key_diff.py path/to/file1.csv path/to/file2.csv --key id. file1, file2. Nothing in the text says which one is the baseline, so the only way to learn the orientation is to be surprised by it once.

Two failures, one silent exit code

I fed it a file with a duplicated key to see what would happen. It exited 2 and printed nothing at all:

for row in reader:
    k = row[key]
    if k in data:
        sys.exit(2)

The same code 2 covers a missing key column:

if key not in reader.fieldnames:
    sys.exit(2)

Distinct causes, identical exit status, no message. Exit 2 is a fine signal for "halt the pipeline" and a useless one for "why did it halt at 2am". The other tool in this family I wrote, jsonl-cli, prints the line number of every broken record to stderr before it fails; that is the bar.

Everything is a string, compared as such

csv.DictReader hands back strings and the comparison is plain !=. Same key, quantity 2 against 2.0:

{"added": [], "removed": [], "changed": [{"id": "1", "qty": "2"}]}

A numeric no-op becomes a change. A row with fewer columns than the header comes back with a JSON null:

{"added": [], "removed": [], "changed": [{"id": "2", "name": "bar", "note": null}]}

So null means "this cell was empty" and also "this row never had that column" — the tool cannot tell those apart, and neither can the reader. An empty input file crashes outright, because fieldnames is None and key not in None raises a TypeError: exit 1, traceback, no explanation.

The self-test does not test the diff

The README advertises:

python csv_key_diff.py --self-test

That command has never worked. --key is declared required=True and both paths are positional, so argparse rejects it before test_self() is ever reached:

usage: csv_key_diff.py [-h] --key KEY [--self-test] csv1 csv2
csv_key_diff.py: error: the following arguments are required: csv1, csv2, --key

I had documented a command I never typed. So I typed it with the positional arguments filled in, and looked at what the harness does:

def run_test(a, b, expected_exit):
    result = subprocess.run(
        [sys.executable, __file__, a, b, '--key', 'id', '--self-test'],
        capture_output=True,
        text=True
    )
    if result.returncode != expected_exit:
        sys.exit(1)

The child process is launched with --self-test. It does not run the comparison it is supposed to be checking; it calls test_self() again, which spawns four children, each spawning four more. I ran it in a sandbox capped at 400 processes and a 6-second timeout: it never returned, the timeout killed it with 124.

Which means the four run_test calls in the file assert an exit code about a self-invocation, never about added, removed or changed. The happy path and the two error paths I describe above are all untested, and the recursion is what hid that from me: a suite that cannot finish looks like a suite that works if you never wait for it.

The repo ships tests/identical.csv and tests/missing.csv, 19 bytes each, and they are the same git blob — identical contents, despite the names. Neither filename appears anywhere in csv_key_diff.py. The CI workflow auto-detects checks by globbing test_*.py and *_test.py; this repo has neither, so what runs green is python3 -m py_compile over the one Python file. Single commit, f7348e1, 2026-09-14, MIT, zero dependencies.

I am not hiding that. A green CI, a self-test section in the README, and no behavioural coverage at all can absolutely coexist, because each of those signals is checked independently and none of them asks whether the tool answers the question you built it for.

What I would change, and what I left alone

Flipping two variable names would fix the orientation, and I would do it, because "forward like every other diff" is what readers assume. Printing one line to stderr before sys.exit(2) would make the failure diagnosable. Dropping --self-test from the child arguments would turn the harness into tests that actually reach compute_diff.

What I would not fix is the string comparison. Once you start coercing numbers you own a type guesser, and csv-inspect already exists for profiling a column's inferred type. This tool's job is the shape of the difference, not the meaning of the cell — but that boundary is worth stating on the tin, and right now it is not stated.

Repo: https://github.com/Raknaos/csv-key-diff

curl -sO https://raw.githubusercontent.com/Raknaos/csv-key-diff/main/csv_key_diff.py
python3 csv_key_diff.py old.csv new.csv --key id

Run it on two files whose answer you already know. If added lists rows that only exist in your second file, you have found the orientation on your own, and from then on you will read every output from this tool with the argument order in your head — which is the only defence that works when a tool's naming disagrees with its behaviour.

My wait-for-it wrapper reported success for a port that never opened

Raknaos — Mon, 14 Sep 2026 09:13:55 +0000

I had the usual line in an entrypoint script:

./wait-for-it.sh db:5432 -- python app.py

The container exited 0. Then the application died three seconds later with
connection refused, and I spent an afternoon blaming the database image.

The database never came up. wait-for-it.sh knew that. It printed its timeout
warning, and then it ran my command anyway, and the exit code I checked was the
exit code of python app.py starting up successfully — which it did, for about
three seconds.

I want to be precise about what is a bug and what is a design decision. This one
is a design decision, it is documented, and it bit me anyway because the
documented behaviour is the opposite of what the name of the tool promises.

What the script actually does at the end

The repo is https://github.com/Raknaos/wait-for-it — a revived copy of
vishnubob's original, MIT licensed, upstream history preserved. The whole tool is
one file of 182 lines of bash. Here is its final block, verbatim:

if [[ $WAITFORIT_CLI != "" ]]; then
    if [[ $WAITFORIT_RESULT -ne 0 && $WAITFORIT_STRICT -eq 1 ]]; then
        echoerr "$WAITFORIT_cmdname: strict mode, refusing to execute subprocess"
        exit $WAITFORIT_RESULT
    fi
    exec "${WAITFORIT_CLI[@]}"
else
    exit $WAITFORIT_RESULT
fi

Read the condition again. Refusing to run the command requires both a failed
wait and -s. Without -s, a failed wait falls through to exec. And
because it is exec, the script's own exit status is replaced by the child's, so
the timeout leaves no trace in the return code at all.

I ran it on my machine today to have the numbers instead of my memory:

$ ./wait-for-it.sh 127.0.0.1:1 -t 5
wait-for-it.sh: waiting 5 seconds for 127.0.0.1:1
wait-for-it.sh: timeout occurred after waiting 5 seconds for 127.0.0.1:1
$ echo $?
124

$ ./wait-for-it.sh 127.0.0.1:1 -t 2 -- echo "RAN ANYWAY"
wait-for-it.sh: waiting 2 seconds for 127.0.0.1:1
wait-for-it.sh: timeout occurred after waiting 2 seconds for 127.0.0.1:1
RAN ANYWAY
$ echo $?
0

That second run is the entire story. Nothing opened on port 1, the script said so
out loud, and the process still reported success. Exit 124 is the coreutils
timeout status leaking through — the script re-invokes itself under timeout
so that Ctrl-C works during a wait, which is a genuinely clever piece of bash and
is why you see 124 rather than 1.

So the rule is: wait-for-it.sh without -s is not a check. It is a delay with
a ceiling. If you want a gate, the flag is not optional.

Why I picked up the repo instead of rewriting it

Because the probe itself is the interesting part and a rewrite would have lost it:

if [[ $WAITFORIT_ISBUSY -eq 1 ]]; then
    nc -z $WAITFORIT_HOST $WAITFORIT_PORT
    WAITFORIT_result=$?
else
    (echo -n > /dev/tcp/$WAITFORIT_HOST/$WAITFORIT_PORT) >/dev/null 2>&1
    WAITFORIT_result=$?
fi

/dev/tcp is a bash pseudo-device, not a file. It opens a TCP connection with no
binary to install, which is why this works in a scratch container that has bash
and nothing else — no netcat, no curl, no Python. The ISBUSY branch exists
because Alpine ships busybox, whose timeout does not always accept the same
flags, so the script resolves its own timeout through realpath and checks the
path for the string busybox. Two environment differences, handled with four
lines. That is the whole argument for pure bash here.

What the revival changes is the test situation. Upstream ships a test/
directory: wait-for-it.py, container-runners.py and a requirements.txt
pinning docker>=4.0.0 and parameterized>=0.7.0. The runners spin up four base
images — two Debian-python tags and two Alpine/busybox combinations — to exercise
the busybox branch. In a repo whose whole point is "no dependencies outside the
shell", a test suite that needs Docker and two pip packages is a strange fit. The
revived repo drops that directory and replaces it with test_wait_for_it.py at
the root: 47 lines, stdlib only, two tests. The first binds an ephemeral loopback
port, runs wait-for-it.sh against it and asserts exit 0 plus the child
command's output. The second opens a socket to reserve a port, closes it, and
asserts a non-zero exit — under --strict.

The script itself is untouched: wait-for-it.sh in this repo is byte-identical to
upstream's, all 182 lines. That is deliberate.

And that last detail about the suite is the one I keep turning over. The only
failure case it asserts is the strict one. The default, non-strict,
run-the-command-anywhere path is untested — not because someone forgot, but
because as far as the script is concerned it is not a failure path. I left it
that way. Covering it would mean asserting that a timed-out wait still runs your
command, which freezes the behaviour that surprised me into a contract.

What it costs, and what it will not tell you

Being honest about the sharp edges I hit while measuring:

One second, minimum. The loop ends in sleep 1. A service that is ready 200 ms
after a probe still waits 800 ms. On a laptop, fine. In front of a docker-compose up that gates a whole dependency graph, you pay it once per dependency.

A name that cannot resolve looks exactly like a port that is closed. I pointed
it at no-such-host-raknaos-test.invalid:80 with -t 3. Output:
timeout occurred after waiting 3 seconds. Exit 124. No hint that DNS was the
problem. The probe discards bash's error text into /dev/null, so a typo in your
service name and a database still booting are the same event.

Service names in the port field do not work. 127.0.0.1:http — where /etc/services
says port 80 — also just times out. The port goes into /dev/tcp as written.

IPv6 literals are mangled, silently. This is the one I would call a defect:

$ ./wait-for-it.sh ::1:80 -t 2
wait-for-it.sh: waiting 2 seconds for 1:80

Argument parsing matches *:* and splits on :, so ::1:80 does not survive the
trip: the host became 1. The script then waits for a host named 1 for as long
as you let it. On a dual-stack network where your database only has an AAAA
record, this fails in the least helpful way available.

The default timeout is 15 seconds and it is not announced until it fires.
WAITFORIT_TIMEOUT=${WAITFORIT_TIMEOUT:-15}. Run without -t on a closed port and
you wait a quarter of a minute, which is short enough to look like the script
succeeded and long enough to hide inside a slow build.

Use it, with the flag

git clone https://github.com/Raknaos/wait-for-it
cd wait-for-it && python3 test_wait_for_it.py

ALL TESTS PASSED on my machine, no dependencies beyond Python and bash. Then put
-s in your entrypoint and decide what you want to happen when the dependency
loses the race:

./wait-for-it.sh db:5432 --strict -t 60 -- python app.py

Now a dead database stops the container at the gate with exit 124 instead of
starting an application that has nothing to talk to. If your orchestrator treats
a non-zero exit as "restart me", the restart loop is what you wanted in the first
place. The tool is 182 lines of bash, and the whole lesson fits in one flag, which
is why it took me a wasted afternoon to learn it.

My JSONL tool printed null for a broken line and nothing in my pipeline noticed

Raknaos — Sun, 13 Sep 2026 09:13:17 +0000

I put a JSON Lines parser in front of a pipeline that reads export dumps from other people's
services. Some of those dumps are not clean. Records get truncated by a proxy, a log shipper
writes half a line and dies, someone opens the file in a spreadsheet app and saves it back with
a stray tab. The failure I cared about was not "the file has one broken line" - it was "the file
has one broken line and my pipeline finished with exit code 0".

That is the exact behaviour the first version of jsonl-cli had, and I did not catch it in review.
I caught it because I ran the tool on a real export instead of on the fixture.

What the tool is

jsonl-cli is a single-file, stdlib-only Python 3 CLI for
JSON Lines (.jsonl) streams: validate, count, get, pretty. All four take a path or -
for stdin, and get resolves a dotted path into nested structures - user.profile.id for
objects, numeric steps for arrays, so user.roles.0 works. It is the first tool in the Raknaos
Tools Lab collection, published 08-09-2026, MIT, no third-party imports. The whole point of the
lab is tools you can drop onto a machine with curl and nothing else.

Here is the pipeline shape that broke the illusion, run against a four-record file with one
corrupt line:

$ python3 jsonl_cli.py get user.email data.jsonl
"a@x.io"
null
null
"b@x.io"
$ echo $?
0

Four valid emails would have printed four quoted strings. I got two quoted strings and two
nulls and a clean exit. Reading that output as a human, I have no idea which of the two null
lines were records that genuinely had no email and which were records that never parsed at all.
Reading it as a shell, the situation is worse: exit 0 means "nothing to see", so the job that
wraps this command reports success and the count quietly drops.

The two errors are not the same error

The root cause was the shape of the loop: the parse, the field lookup and the print all sat
inside one try, and the handler printed a null.

# first release
def cmd_get(args):
    with _open_input(args.file) as f:
        for line in f:
            line_str = line.strip()
            if not line_str:
                continue
            try:
                obj = json.loads(line_str)
                val = _resolve_dotted_key(obj, args.key)
                print(json.dumps(val))
            except Exception:
                print("null")
    return 0

return 0 is unconditional, so the function cannot report a problem even if it wanted to. And
print("null") conflates two completely different facts:

The line parsed fine and the path is absent in it. That is data. The answer to "what is user.email in this record" genuinely is null, and the pipeline should carry on.
The line is not JSON. That is an input error. Silently turning it into the same null as case one destroys the only signal that anything went wrong.

A null on stdout is a value. A corrupt line is not a value, it is a reason to distrust the rest
of the output. The second commit fixes exactly that separation.

What it does now

Invalid lines go to stderr with their line number, the offending line is skipped rather than
faked into a value, and the exit code flips to 1. A missing key still prints null and still
exits 0, because that is a legitimate answer:

# current
def cmd_get(args):
    had_invalid = False
    with _open_input(args.file) as f:
        for line_no, line in enumerate(f, start=1):
            line_str = line.strip()
            if not line_str:
                continue
            try:
                obj = json.loads(line_str)
            except Exception as e:
                # an invalid JSON line is an input error, NOT a null value:
                # report it on stderr and flip the exit code so pipelines notice
                sys.stderr.write(f"Line {line_no}: invalid JSON - {e}\n")
                had_invalid = True
                continue
            val = _resolve_dotted_key(obj, args.key)
            print(json.dumps(val))
    return 1 if had_invalid else 0

Same file as before, same command:

$ python3 jsonl_cli.py get user.email data.jsonl
Line 3: invalid JSON - Expecting value: line 1 column 1 (char 0)
"a@x.io"
null
"b@x.io"
$ echo $?
1

Three values on stdout instead of four, which is the honest answer: one of those four lines is
not a record. pretty got the same treatment, and count picked up a guard on
--valid-only --invalid-only - the first release accepted both flags and quietly let one win,
which is a 2 (usage error), not a 0. The exit-code contract is now written in the module
docstring: 0 clean, 1 at least one invalid input line, 2 usage error.

What it does not do

Honesty about the edge, because it will bite you:

Exit 1 is not a per-line contract. It says "at least one input line was bad somewhere in this stream". It does not tell you how many, and it is the same code whether one line out of a million failed or every line failed. If your pipeline needs the distinction, use count --invalid-only and branch on the number, not on the status.
A missing key is silent by design. get user.profile.id on a record without a profile prints null and exits 0. There is no flag that turns absent-path into an error, so a typo in your key path looks exactly like a record that lacks the field. validate will not help you either - it only checks that each line parses, never that a key exists.
Nothing is type-checked. get returns whatever is at the path, JSON-encoded: a string, an object, an array, a number. If you need the value usable downstream you parse it again.
Blank lines are skipped, not reported, in every subcommand. A file that lost half its records to a grep -v accident is not something this tool looks for.
stdin is read as text, one line at a time. There is no buffering of the whole stream, which is what makes it usable on a growing log, and there is no encoding auto-detection beyond open(path, "r", encoding="utf-8").
The BrokenPipeError in main() maps to sys.exit(0). That is deliberate - jsonl get k f | head -1 should not report failure because head stopped reading - but it does mean the exit code of a truncated pipeline is not meaningful. Check the status of the command you actually care about.

Trying it

curl -sSL https://raw.githubusercontent.com/Raknaos/jsonl-cli/main/jsonl_cli.py > jsonl
chmod +x jsonl
./jsonl get user.email - < data.jsonl

Repo: https://github.com/Raknaos/jsonl-cli - jsonl_cli.py, test_jsonl_cli.py, MIT, Python 3.8
and up, standard library only. The unit tests run under python3 -m unittest discover with no
install step, and the CI job for the repo is that one line.

A Pidfile Lock Is Only as Good as Its Stale Check

Raknaos — Sat, 12 Sep 2026 09:08:03 +0000

Every backup script eventually tells the same story. A cron job ran long, the
machine rebooted mid-run, and some morning I noticed the nightly job had quietly
stopped firing for three days. Nothing had crashed — the opposite. The lock file
the wrapper creates on startup was still sitting in /tmp, holding a PID from a
boot that no longer existed, and every subsequent run politely refused to start.

That's the trap with pidfile locking: the lock protects you from overlap, but a
dead lock protects you from everything, including the job itself. I wrote
pidlock (https://github.com/Raknaos/pidlock), a zero-dependency Python CLI that
wraps a command in a pidfile and handles this case, and the interesting part
isn't the wrapper — it's what "is this process actually alive?" really means when
you answer it once per run for a year.

The mechanism

Acquisition is a single atomic create. No lock daemon, no flock, no parsing:

def acquire(path):
    """Try to create the pidfile atomically. Returns True on success."""
    fd = None
    try:
        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
        os.write(fd, ("%d\n" % os.getpid()).encode())
        return True
    except FileExistsError:
        return False
    except OSError as e:
        if e.errno == errno.EEXIST:
            return False
        raise
    finally:
        if fd is not None:
            os.close(fd)

O_CREAT | O_EXCL guarantees two racing processes never both succeed — the
kernel picks one, the other gets EEXIST. That half is easy. The hard half is
what you do after the EEXIST, because that's where every stale-lock bug lives.

When acquisition fails, pidlock reads the file, checks the PID, and only
removes it if it's confirmed dead — a corrupt or unreadable pidfile counts as
dead, a live one never does:

def pid_alive(pid):
    if pid <= 0:
        return False
    try:
        os.kill(pid, 0)
        return True
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    except OSError:
        return False

def acquire_with_stale_retry(path):
    if acquire(path):
        return True
    if is_stale(path):
        try:
            os.unlink(path)
        except OSError:
            pass
        if acquire(path):
            return True
    return False

Two details in there that I'd have gotten wrong the first time I needed them.

PermissionError returns True. On Linux, a signal probe on a process owned
by another user fails with EPERM, not ESRCH. pid 4231 is alive is the
correct answer even though the probe failed — deleting that pidfile would kill
another user's job's lock. The asymmetry is deliberate: never delete a lock
unless you're sure the owner is gone.

Release verifies ownership before unlinking. If your lock was evicted as
stale while your process ran (see below), and a new instance already wrote its
own PID into the same path, an unconditional os.unlink at exit deletes the
wrong lock. So release_if_ours re-reads the file and unlinks only if it still
contains its own os.getpid(). Seven lines, invisible when it works, load-bearing
when it doesn't.

What a live PID doesn't prove

Here's the part I had to state out loud once the reboot incident was explained:
os.kill(pid, 0) proves some process owns that number. It does not prove it's
the process that wrote the file.

PIDs are recycled. After a reboot, the counter restarts from the top — a fresh
rsyslogd can inherit the exact number your stale backup wrote yesterday. The
pid_alive check says "alive", the stale-lock logic says "not my problem", and
your backup stays locked out indefinitely by a process that has nothing to do
with it. The textbook fix is to store a signature alongside the PID — the
process starttime field from /proc/<pid>/stat, or a hash of cmdline — and
verify it matches before trusting liveness.

pidlock does not do this. The pidfile contains one number, full stop. That's a
decision, not an oversight, and it comes with the rest of what the tool refuses
to be:

Advisory only. A job that never calls pidlock doesn't see the lock. The README says so in one line: only processes that use pidlock respect it.
No flock. A kernel flock dies with its holder — no stale state is even possible across a reboot — but it doesn't play well with NFS, and flock(2) availability varies enough across platforms that the CLI stays portable. The README lists this under "What it does NOT do" rather than pretending.
TOCTOU between the staleness check and the unlink is real and documented. Two processes can both observe a stale lock at once and both race to evict it; the O_EXCL re-acquire still lets only one win, but the losing side has already deleted a file it thought was stale. --wait N (retry acquisition for N seconds) shrinks the practical blast radius for cron-style collisions.

The PID-recycle false-positive needs a reboot plus an unlucky PID collision on
a busy-enough box to matter — rare in practice, and rarer still for short-lived
backup jobs whose stale window is hours, not weeks. On machines where the
consequence justifies the coupling, flock or a systemd PathExists= guard is
the honest recommendation, and I'd rather say that in the README than have you
discover it during an outage. Same discipline for the check against the
--check flag: it reports the state it can observe, and where the staleness
signal is ambiguous on a recycled PID it stays conservative rather than
destructive.

Trying it

Wrap any command; the exit code propagates, and signals clean up after
themselves (130 on SIGINT, 143 on SIGTERM):

pidlock --pidfile /tmp/backup.pid -- /home/me/backup.sh
pidlock --pidfile /tmp/backup.pid --wait 60 -- ./backup.sh   # wait instead of fail
pidlock --pidfile /tmp/backup.pid --check                     # 0 free, 1 held

No dependencies, Python 3.6+, 201 lines in the single pidlock.py, and
--self-test proves the semantics hermetically (live pid blocks, dead pid is
evicted and retried) without touching your real cron.

Repo: https://github.com/Raknaos/pidlock

Headless browser cookies are scoped to the CDP connection, not the browser

Raknaos — Sat, 12 Sep 2026 06:07:46 +0000

I sync my logged-in sessions from my desktop browser into a headless browser on a VPS, so that automation agents running there stay authenticated. The sync reported success: four cookies injected, matching names and domains. Then the headless browser opened the target site and it said logged-out.

The cookies were in the jar. The page just could not see them.

The actual rule

The headless browser I use is Lightpanda, a headless browser written from scratch in Zig (V8 for JavaScript, libcurl for networking), driven over the Chrome DevTools Protocol. Its cookie jar is scoped per CDP connection, not per browser process. Inject cookies over connection A, navigate and read the page over connection B, and B sees an empty jar. Nothing is wrong with the cookies; they simply live in the jar that belongs to A.

This bit me for real on dev.to. My first architecture had every automation process open its own WebSocket to the browser and run its own Network.setCookies followed by navigation. Each process saw its own injected session fine, and every other process saw nothing. Worse, two agents sharing one WebSocket would interleave commands, so a navigate from one could land between another's inject and evaluate.

The fix that stuck

The relay I built now owns the only CDP connection for its whole lifetime. Agents talk to it over plain HTTP on loopback:

POST /v1/cdp proxies a CDP command onto that one connection, so every command — inject, navigate, evaluate — executes against the jar that actually holds the sessions.
Processes never touch the WebSocket, so there is nothing to interleave; the relay serializes on its side.
If the browser restarts, the connection dies and so would the jar. The relay keeps the last synced session in memory and replays it (Network.setCookies again) on the fresh connection as soon as it is back.

That last part matters more than it sounds: a headless browser crashing mid-day should not log out every session it held. Since the jar is per-connection, "persist sessions" really means "re-inject on every new connection", and it is the component that owns connections that has to do it.

The second trap: `expires`

While fixing this I hit a smaller one worth passing on. Injecting a cookie with an expires attribute was silently discarded — not rejected, just dropped. The call returned success, the cookie never existed. Session cookies without expires went through fine. The workaround is to strip expires on injection and let the runtime jar treat them as session cookies; whatever persistence you need lives in your own snapshot of the sessions, which you re-import anyway for the reason above. Setting an explicit Domain, Secure, and httpOnly with path / also avoided a second class of silent mismatches.

The takeaway

I had been thinking about browser state at the wrong granularity. "The browser has the cookies" is the wrong mental model for CDP-driven browsers — the connection has the cookies, and anything that does not route through the connection that holds them is operating on an empty jar. If your automation stack has more than one component talking to the browser, decide once who owns the single connection and make everyone else go through it. It collapses a whole category of "works in process A, logged-out in process B" bugs, and it gives you one place to do session replay after a crash.

The relay is about 1,200 lines of Python and lives with the rest of the project at Raknaos/lightpanda-session-bridge. If you have ever lost an afternoon to a session that was injected but not visible, this is probably why.

My local repos were full of zombie branches and git never told me which ones were safe to delete

Raknaos — Fri, 11 Sep 2026 11:03:15 +0000

Last week I ran git branch in one of my older working trees and got back forty-some local branches. Forty. I work on maybe three things at a time. The rest were residue: half of them were merged into main months ago, a few tracked remote branches that someone had already deleted on the server, and the rest I genuinely did not recognize anymore.

The problem with this pile is not disk space. A local branch ref is tiny. The problem is that it makes every other git command worse. git log --all gets noisy. Tab completion for branch names becomes useless. And the moment you want to prune, you freeze, because deleting a branch you think is dead is exactly the kind of operation that bites you six weeks later when you need a commit that only existed there.

I tried the usual tricks. git branch --merged main gives you a real signal, but it also happily lists your current branch, and if you pipe that straight into a delete you can shoot yourself in the foot. git branch -vv shows [gone] for branches whose upstream vanished, but you have to eyeball it across dozens of lines. And neither tool says anything at all about the branch you touched last in March and never came back to. There was no single command that gave me a reason per branch. So I wrote one.

What I built

git-stale is a single Python file. The published tool.py is 5,092 bytes and imports four things, all from the standard library: argparse, subprocess, sys, and datetime. No pip installs, no virtualenv, no version-pinning argument with a dependency that no longer exists. If you have Python 3.8 and git on your PATH, it runs. That was a deliberate constraint, not laziness: a cleanup tool that itself requires an install step is a tool I will not actually run, and a supply chain of one file has nothing to rot.

The core idea is that a branch is stale if it matches any of three independent checks, and the tool reports which checks fired rather than a bare list:

it is fully merged into the default branch (main or master),
its upstream remote branch no longer exists ([gone]),
its last commit is older than a threshold (30 days by default).

The detection is thin wrapper-over-git on purpose. I did not reimplement merge-base logic or parse the index. I ask git itself, because git already knows the truth and I would only introduce a divergence bug by trying to agree with it:

def merged_branches(base, cwd=None):
    out = run_git("branch", "--merged", base, cwd=cwd)
    return {line.strip().lstrip("* ") for line in out.splitlines() if line.strip()}

def remote_gone_branches(cwd=None):
    gone = set()
    out = run_git("branch", "-vv", cwd=cwd)
    for line in out.splitlines():
        if "[gone]" in line:
            gone.add(line.strip().lstrip("* ").split()[0])
    return gone

def commit_date(branch, cwd=None):
    out = run_git("log", "-1", "--format=%ct", branch, cwd=cwd)
    return datetime.fromtimestamp(int(out), tz=timezone.utc)

find_stale stitches the three together, and this is where the safety actually lives: the current branch and the default branch are skipped before a reason is ever attached. You will never see the branch you are standing on in the output.

def find_stale(days, cwd=None):
    base = default_branch(cwd=cwd)
    cur = current_branch(cwd=cwd)
    merged = merged_branches(base, cwd=cwd)
    gone = remote_gone_branches(cwd=cwd)
    cutoff = datetime.now(timezone.utc).timestamp() - days * 86400
    stale = {}
    out = run_git("branch", "--format=%(refname:short)", cwd=cwd)
    for branch in out.splitlines():
        branch = branch.strip()
        if not branch or branch == cur or branch == base:
            continue
        reasons = []
        if branch in merged:
            reasons.append("merged into " + base)
        if branch in gone:
            reasons.append("upstream gone")
        if commit_date(branch, cwd=cwd).timestamp() < cutoff:
            reasons.append(f"untouched > {days}d")
        if reasons:
            stale[branch] = reasons
    return stale

The default branch is not hard-coded. default_branch() probes refs/heads/main, falls back to refs/heads/master, and the whole repo works the same on either name. Output is one line per branch with the reasons joined:

feature/auth-redo: merged into main
wip/scraper-v2: upstream gone; untouched > 30d

Running it with no flags is read-only. You see the list, you decide, nothing changes. Deletion is opt-in and, by default, asks you to confirm each branch one by one:

python3 tool.py            # just list
python3 tool.py --days 90  # a looser age threshold
python3 tool.py --delete   # confirm per branch

The reason --delete is separate from listing is behavioral, not technical. A tool that cleans up after you and a tool that cleans up without asking are different products, and the second one you only appreciate after it deletes the wrong thing once.

What it does not do

Being straight about the boundaries matters more than the feature list here.

Deletion uses git branch -D, the force flag. That means it does not re-verify that a branch is merged at the moment of deletion. It trusts the reasons it printed and trusts you to have read them. I made that choice so the tool can delete [gone] and untouched branches that are legitimately unmerged but clearly abandoned, but the cost is real: read the reasons before you answer y. The README says this explicitly rather than burying it.

The age check keys off the branch tip's commit date. If you have a three-week-old branch you only push to once a quarter, it will show up at the default 30 days. That is a listing, not a deletion, and --days is there for exactly that case.

It reads local branch refs against your last-known view of the remote. If your remote-tracking refs are stale because you have not fetched, [gone] detection is only as good as your last fetch. There is no silent git fetch behind the scenes; the tool does not touch the network.

It has no idea what your team's workflow is. A long-lived release/* branch will happily be flagged as untouched. The tool surfaces candidates with reasons; the judgment call stays with you on purpose.

And there is a self-test, because I did not want to ship a thing whose whole job is deleting refs based on my own confidence. It creates a throwaway repo in a TemporaryDirectory, builds a known branch topology, and asserts that merged-into-main shows up, that a fresh unmerged branch does not, and that main and the checked-out branch never appear:

python3 tool.py --self-test
# self-test OK

That runs in the CI alongside a fresh clone. If a future edit makes the tool report the branch you are standing on, the test fails and nothing gets published. I would rather catch that on a temporary directory than in someone's real working tree.

Try it

If your git branch output has drifted into archaeology, run it read-only first and just look at the reasons. It is one file you can read top to bottom before you let it near your repo.

git clone https://github.com/Raknaos/git-stale
cd git-stale
python3 tool.py --self-test   # prove it to yourself first
python3 tool.py               # in any repo you want to inspect

The source is at https://github.com/Raknaos/git-stale (MIT). The whole thing lives in that single tool.py; open it before you run it, and if the age default is wrong for how you work, change the number. The tool will not touch a branch you did not explicitly tell it to.

Securing a loopback CDP relay with extension-ID pinning

Raknaos — Thu, 10 Sep 2026 18:03:55 +0000

My local relay (127.0.0.1:8765) proxies Chrome DevTools Protocol commands to a headless browser whose cookie jar holds my logged-in sessions. A shared secret in a header was never enough: any web page I visit can fire fetch at loopback. Same-origin policy stops the response from being read, but the request still reaches the server, and a preflight is a request too. So the relay had to answer one question on every call: which extension is actually talking to me?

Last week suleyman416 opened PR #1 on the Lightpanda Session Bridge with exactly that hardening. I merged it on the 9th after running the tests locally. Here is what landed and the one subtlety that made it interesting.

The mechanism

The caller's Origin header looks like chrome-extension://<id>/.... The ID is 32 characters from the alphabet a-p (it is derived from the extension's public key). Validation is a regex fullmatch, not a prefix check:

EXTENSION_ID_RE = re.compile(r"^[a-p]{32}$")
OFFICIAL_EXTENSION_ID = "fcigkjkchglchhohedljlenopbkgnino"

The relay keeps a pinned ID, checked on every token-delivering or CDP-executing path (/v1/bootstrap, /v1/sessions, /v1/cdp) plus CORS preflights. Default policy: pin the official published ID. If your origin does not match, you get a 403 and the endpoint never runs.

The trap: unpacked extensions have path-derived IDs

During development you load the extension unpacked (chrome://extensions -> Load unpacked), and Chrome derives the extension ID from a hash of the installation path, not a public key. Every checkout on every machine gets a different ID. A strict default pin would have broken the exact people the project needs: anyone running a custom build.

The PR solved it with three explicit modes instead of one clever guess:

Default: official ID pinned. Safest for users installing the packaged extension.
TOFU (LP_BRIDGE_TOFU=1): first caller pins its ID to ~/.config/lightpanda-bridge/pinned_extension_id (written 0600), everyone else is then checked against it. Trust on first use, like SSH known_hosts.
Allowlist (LP_BRIDGE_ALLOWED_EXTENSION_IDS): comma-separated IDs for CI or multi-machine setups.

What TOFU costs you

Trust on first use trusts the first caller. If anything can race your extension to the relay on a cold start, it pins the attacker's ID and you never notice. That is why TOFU is opt-in and off by default: the failure mode is quiet, and quiet failure modes should require an environment variable, not a code path.

The practical lesson I take from this PR: when you secure a loopback service, "who is allowed to call me" cannot be answered by the absence of an Origin (that is how curl looks) nor by a token alone (tokens leak into logs and shell history). Bind the secret and the identity together, make the strict mode the default, and make the permissive mode loud.

The relay is ~1,200 lines of Python and the whole pinning layer is under 100. If you run an agent with a CDP endpoint on localhost, this is a cheap afternoon of work.",

Your headless browser has as many cookie jars as it has CDP connections

Raknaos — Wed, 09 Sep 2026 22:47:52 +0000

Your headless browser has as many cookie jars as it has CDP connections

I learned this the expensive way while running an authenticated headless agent in production.

The setup was simple on paper: a Chrome extension exports the cookies of a site you are logged into on your desktop, a local relay injects them into Lightpanda, and an agent drives that Lightpanda instance through the Chrome DevTools Protocol. Real logins, no password storage, no OTP babysitting.

It worked. Then it randomly stopped working on dev.to specifically.

The extension synced. The relay reported the cookies as injected. Network.getCookies on the socket I was using returned the expected jar. And yet every navigation came back as logged out. No error, no redirect to a login page worth debugging — just an anonymous session staring back at me.

The jar is scoped to the connection, not to the browser

Here is the part the docs did not tell me: Lightpanda scopes its cookie jar per CDP connection, not per browser instance.

Which means:

Connection A (the relay) imports the session.
Connection A's getCookies confirms the cookies are there. True.
Connection B (my agent, a fresh WebSocket to the same :9222) navigates.
Connection B sees an empty jar. Also true.

Both statements are correct simultaneously. There is no corruption, no expiry problem, no SameSite mystery. The two sockets were looking at two different jars that happened to live in the same process. I spent a while suspecting cookie attributes before noticing that the verification call and the navigation call were made on different connections — I was confirming the state of a jar I was never reading from.

In a normal Chrome this is invisible, because there is effectively one browser-wide jar and CDP is a debugging surface on top of it. In an agent-oriented headless browser, the CDP connection is the primary control plane, and connection-scoped state becomes a first-class architectural property, not a detail.

The fix: one connection to rule them all

The version that ships today has the relay own the only CDP connection, permanently. Agents never open a socket to the browser. They POST their CDP commands to the relay, which replays them on the connection that holds the sessions:

from bridge_agent import AuthenticatedSession

s = AuthenticatedSession()          # talks to the relay, not to :9222
s.open("https://dev.to", wait=8)
s.js("document.body.getAttribute('data-user-status')")  # 'logged-in'

Three consequences worth calling out:

Verification has to happen on the acting connection. getCookies from a side socket tells you nothing about what your navigation will see. If you are debugging an auth problem in a headless setup, the very first question is: same connection? Not same browser, not same process. Same connection.

Restart semantics become explicit. When the browser restarts, the jar is gone because the connection is gone. There is no browser state to fall back to. We now replay the last imported session automatically on reconnect and keep on-disk snapshots of each origin's cookie list so a relay restart is a re-import, not a manual re-sync from the desktop.

Security posture changes for the better. If agents can open their own CDP socket, they can create a new jar at will, and "who is allowed to read the session" becomes unenforceable. Serialising every command through one relay with a token and strict origin checks (chrome-extension:// only on the endpoints that deliver the secret) turns an implicit trust boundary into an explicit one. The anti-replay win was a side effect of fixing the jar bug.

What I'd check first, if this is your bug

Print location.href after every navigation from the same connection you navigated on. A target that silently fell back to about:blank looks exactly like a cookie problem — the page you render isn't the page you think you're authenticating.
Never verify state on a different socket than the one you act on.
If your browser exposes /json/list, check how many live targets and connections you actually have. Two WebSockets attached is the smoking gun.
Before blaming SameSite, Secure, Domain, or expiry, prove the reading and writing side share a jar. Attribute problems are real, but they are down the list from "you are literally in another browser context".

Take it with a grain of salt

This is one browser's implementation, not a CDP specification guarantee. What generalises is the lesson: when a headless browser is designed for automation, the CDP connection is a security and state boundary, and you should assume it holds state until proven otherwise. If your stack was built assuming one browser equals one session store, that assumption will fail quietly, and it will fail in the direction that looks like an authentication bug.

If you've hit an equivalent in Playwright storage states, Puppeteer's incognito contexts, or another headless engine, I'd genuinely like to know how you handled the "which connection am I actually reading?" problem. That question cost me a day and it should not have.

The bridge this came out of is open source: https://github.com/Raknaos/lightpanda-session-bridge

Handing Real Logins to Headless AI Agents: Building the Lightpanda Session Bridge

Raknaos — Mon, 07 Sep 2026 22:00:10 +0000

TL;DR: When autonomous AI agents need to interact with modern web dashboards, handing them passwords or session tokens in prompts is a security disaster. I built Lightpanda Session Bridge — an open-source MV3 Chrome extension and a hardened loopback relay that safely replicates your live browser session into a local Lightpanda headless runtime via CDP. Zero credentials typed, zero secrets exposed to LLMs.

If you build AI agents that do real work on the modern web, you know the exact wall every developer hits: authentication.

The moment your agent needs to check an AWS billing console, inspect private logs on a SaaS dashboard, or pull data from an internal portal, the demo breaks down. Modern apps don’t live on basic auth; they sit behind Google OAuth, SSO federations, hardware passkeys, and biometric 2FA prompts.

A headless browser cannot tap your security key, answer your phone's authenticator app, or blink at a FaceID prompt.

Faced with this, most builders resort to terrible compromises:

Hardcoding passwords into agent prompts or .env files (which leak into LLM context logs, chat histories, and traces).
Copy-pasting session cookies manually into configs (which expire quickly and offer zero scoping or SSRF protection).
Driving the user’s primary browser via raw CDP (which disrupts real work, risks hijacking other tabs, and introduces scary blast radiuses).

The Lightpanda Session Bridge is built on a different philosophy: keep the authentication ritual with the human, and hand the agent an isolated, authenticated runtime.

+-----------------------------------------------------------------------+
|  HUMAN BROWSER (Chrome / Edge / Comet)                                |
|  User logs in via Passkey / Google OAuth / 2FA                        |
|                                                                       |
|  [ 🐼 Sync Tab ] ---> Extension MV3 extracts strictly scoped cookies   |
+---------------------------------------+-------------------------------+
                                        | POST 127.0.0.1:8765
                                        | (with X-Bridge-Token + CORS check)
                                        v
+-----------------------------------------------------------------------+
|  LOCAL BRIDGE RELAY (relay/server.py)                                 |
|  - Loopback-only (127.0.0.1)                                          |
|  - IdP & Private IP blocking (anti-SSRF + DNS cache)                  |
|  - Cookie normalization (__Host-, __Secure-, RFC 6265bis)             |
+---------------------------------------+-------------------------------+
                                        | WebSocket CDP Protocol
                                        v
+-----------------------------------------------------------------------+
|  HEADLESS RUNTIME (Lightpanda in WSL2 @ :9222)                        |
|  - Isolated V8 / Zig engine                                           |
|  - Instant DOM / JS evaluation                                        |
|                                                                       |
|  AI Agent reads data via SDK (lightpanda_client.py)                   |
+-----------------------------------------------------------------------+

Why Session Transfer Beats Credential Sharing

Passwords and API tokens are the wrong unit of trust for agents. They grant permanent, unrestricted access. Once an LLM agent has your password, you have zero guarantee where that string will travel — subagent handoffs, external telemetry, debug dumps, or third-party inference providers.

A session cookie is fundamentally safer:

It is ephemeral and expires automatically.
It can be instantly revoked from your main browser simply by logging out.
It is strictly scoped to a single target origin.

With the bridge, you authenticate once in your familiar browser. When you click Sync, the extension packages only the cookies relevant to that specific origin and pushes them into an isolated headless browser instance.

The LLM never sees your credentials. The relay never logs a cookie value. The machine gets straight to work.

Architecture: The Three Layers

The architecture is purposely minimal, robust, and audit-friendly:

1. The Chrome Extension (Manifest V3)

Designed with a clean, dark Quota Glass interface. It requires only standard scoped permissions (activeTab, cookies, storage). When clicked, it captures cookies for the active domain, normalizes them, and prepares a transfer envelope.

On first launch, it executes an auto-pairing handshake (/v1/bootstrap) with the local relay, storing a shared cryptographic token in local isolated storage without requiring manual copy-pasting.

2. The Hardened Loopback Relay (`relay/server.py`)

Listening exclusively on 127.0.0.1:8765, the relay is the security gateway. It:

Enforces strict origin matching.
Translates browser cookie structures into Lightpanda-compliant DevTools protocol messages (including converting lowercase sameSite tags like lax to Lightpanda's PascalCase Lax to avoid -31998 InvalidEnumTag CDP crashes).
Normalizes __Host- and __Secure- cookie prefixes per RFC 6265bis.
Forwards cookies over CDP WebSockets to the headless engine.

3. Lightpanda Headless Engine

Lightpanda is an ultra-fast, open-source headless browser built in Zig with V8, purpose-built for AI automation. Running Lightpanda in WSL2 isolates it from your Windows host environment while keeping execution blindingly fast with tiny memory footprints compared to full Chromium.

The Security Checklist: Defending Against SSRF & Local Leaks

Treating a local HTTP relay as a trusted boundary is how local privilege escalation happens. Because the relay accepts cookies, I designed it as an adversarial SSRF surface from day one:

🛡️ Zero Logging: Cookie names and values are never printed to stdout, logged to disk, or saved in history.
🔒 Loopback Only: Hardcoded binding to 127.0.0.1. No routable network interfaces exposed.
🚫 Strict Identity-Provider (IdP) Blacklisting: The relay automatically rejects transfers intended for identity roots — accounts.google.com, login.microsoftonline.com, appleid.apple.com, github.com, and auth0.com cannot be targeted.
🛑 SSRF IP & DNS Verification: Target domains must resolve to valid public IPv4/IPv6 addresses. Localhost aliases, 127.0.0.0/8, private subnets (10.0.0.0/8, 192.168.0.0/16), and wildcard DNS tools like nip.io are categorically dropped. DNS lookups are pinned with a 60-second cache to prevent time-of-check to time-of-use (TOCTOU) rebinding.
🔑 Origin-Restricted Handshake: Web pages or rogue local CLI scripts attempting to query /v1/bootstrap receive an immediate 403 Forbidden. Only callers presenting a legitimate chrome-extension:// Origin header can receive the pairing secret.
🧪 Live Verified: Backed by 9 automated security test suites, validating private IP rejections, CDP payload structures, and token enforcement.

How AI Agents Interact With The Session

Once the session is synced into Lightpanda, your agent script uses the bundled lightweight Python SDK (lightpanda_client.py):

from lightpanda_client import LightpandaClient

# 1. Connect to Lightpanda CDP runtime
client = LightpandaClient(cdp_ws="ws://127.0.0.1:9222/")
client.connect()

# 2. Attach to or spawn the target page (already carrying the synced session)
client.attach_or_create("https://app.example.com/dashboard")

# 3. Evaluate JavaScript inside the authenticated session context
dashboard_data = client.evaluate("""(() => {
    return {
        user: document.querySelector('.user-profile')?.textContent?.trim(),
        quotaRemaining: document.querySelector('.quota-display')?.textContent?.trim(),
        csrfToken: document.querySelector('meta[name="csrf-token"]')?.content
    };
})()""")

print(f"Agent operating as: {dashboard_data['user']}")
print(f"Remaining quota: {dashboard_data['quotaRemaining']}")

client.close()

The agent never asked for a password. The user never risked account takeover.

Quickstart (Under 3 Minutes)

1. Clone & Install Dependencies

git clone https://github.com/Raknaos/lightpanda-session-bridge.git
cd lightpanda-session-bridge
pip install -r requirements.txt

2. Launch Lightpanda & The Bridge Relay

In two PowerShell terminals:

./scripts/start-lightpanda.ps1   # Runs Lightpanda CDP on 127.0.0.1:9222 (WSL2)
./scripts/start-relay.ps1        # Starts relay on 127.0.0.1:8765

3. Load the Extension

Open chrome://extensions in Chrome, Comet, or Edge.
Toggle Developer Mode on.
Click Load unpacked and select the repository's extension/ folder.
Open the popup once while the relay runs — it auto-pairs instantly.
Navigate to any authenticated site, click the 🐼 icon, and hit Sync Session.

Honest Limitations

Human-in-the-loop: You must click Sync once per session. This is an intentional security design choice, but it means this is built for supervised agent workflows, not headless server farms starting from scratch.
Local machine only: The relay strictly refuses remote connections. Your agent script and your browser must reside on the same workstation or dev environment.
Zig / WSL2 dependency: Lightpanda currently runs most smoothly on Linux/WSL2; the PowerShell scripts manage this automatically for Windows setups.

Try It Out & Contribute

The project is fully open-source under the MIT license:

📦 GitHub Repository: Raknaos/lightpanda-session-bridge
🌐 Project Landing Page: raknaos.github.io/lightpanda-session-bridge
🏷️ Release v0.3.4 (Zip Packaged): GitHub Releases

If you're building autonomous agents that need to navigate authenticated environments safely, take it for a spin and star the repo! Feedback, issues, and PRs are warmly welcome.

DEV Community: Raknaos

My HTTP timing tool could not even start on Python 3.11

The design is deliberately small

The fix is smaller than the diagnosis

What it does not do

Try it

My CSV diff tool reported a new row as removed, and its self-test cannot run

What the code actually says

Two failures, one silent exit code

Everything is a string, compared as such

The self-test does not test the diff

What I would change, and what I left alone

My wait-for-it wrapper reported success for a port that never opened

What the script actually does at the end

Why I picked up the repo instead of rewriting it

What it costs, and what it will not tell you

Use it, with the flag

My JSONL tool printed null for a broken line and nothing in my pipeline noticed

What the tool is

The two errors are not the same error

What it does now

What it does not do

Trying it

A Pidfile Lock Is Only as Good as Its Stale Check

The mechanism

What a live PID doesn't prove

Trying it

Headless browser cookies are scoped to the CDP connection, not the browser

The actual rule

The fix that stuck

The second trap: expires

The takeaway

My local repos were full of zombie branches and git never told me which ones were safe to delete

What I built

What it does not do

Try it

Securing a loopback CDP relay with extension-ID pinning

The mechanism

The trap: unpacked extensions have path-derived IDs

What TOFU costs you

Your headless browser has as many cookie jars as it has CDP connections

Your headless browser has as many cookie jars as it has CDP connections

The jar is scoped to the connection, not to the browser

The fix: one connection to rule them all

What I'd check first, if this is your bug

Take it with a grain of salt

Handing Real Logins to Headless AI Agents: Building the Lightpanda Session Bridge

Why Session Transfer Beats Credential Sharing

Architecture: The Three Layers

1. The Chrome Extension (Manifest V3)

2. The Hardened Loopback Relay (relay/server.py)

3. Lightpanda Headless Engine

The Security Checklist: Defending Against SSRF & Local Leaks

How AI Agents Interact With The Session

Quickstart (Under 3 Minutes)

1. Clone & Install Dependencies

2. Launch Lightpanda & The Bridge Relay

3. Load the Extension

Honest Limitations

Try It Out & Contribute

The second trap: `expires`

2. The Hardened Loopback Relay (`relay/server.py`)