DEV Community: Alkis Yuv

The queue drains itself now, and the morning note fits in a minute

Alkis Yuv — Sat, 05 Sep 2026 21:11:55 +0000

One directory is the task manager my agents share was the most-read thing I have published, and it left out the part that matters most: who works the queue. For the first month the honest answer was mostly me. The nightly run drained a few entries, and every mechanical finding, a drifted git hook, a dependency advisory, a stale path, still waited for me to notice it and route it. I counted one day's commits: 68 across eight repos, about 48 of them the fleet maintaining itself with me as the router. The queue routed work. Nothing routed time.

So the fleet maintains itself now, in four moves.

Detection files its own work. Every night the deterministic lenses sweep every repo and file an allowlisted set of finding classes straight into the queue, through the same atomic door a session uses. The allowlist is the whole design: a stale gate, a test that runs only in CI, a dead path, a tool behind its pack. Judgment classes stay out. A file over budget is an editorial call, a missing contract gets authored, anything the sweep marks as risk is a ruling. A wrong work order costs more than a report line.

Progress is measured on the contract, never on commits. The first version of the night loop counted a round as productive when the child committed. The benchmark night showed why that is the wrong delta: eleven of fifteen spawns committed, six of them the same appended paragraph, while the entry each was spawned for never moved. A round is fruitless per entry now: workable at child start, still pending and workable at child exit. An entry that takes fruitless rounds on three distinct nights is parked as needing me, with a note, through the door's own verb. A lease a dead child left behind is reaped at the start of the next run. The night converges on queue state instead of spinning on it.

 night 1   pending ──child──▶ pending    fruitless: 1
 night 2   pending ──child──▶ pending    fruitless: 2
 night 3   pending ──child──▶ pending    fruitless: 3 ──▶ needs: owner
                                        one line in the brief,
                                        one batched decision

The morning report is a PA's note. Every report I used to get was accurate and none was ever actionable: fifteen lines of "Started work" in time order, the same errors again and again. I wrote the spec in one sentence, a PA reporting to their boss the next morning, read on a phone, before coffee. The brief is compiled from the run's one fact stream, a JSON-lines trace every producer writes into, so there is one account of the night rather than three reconciled by nobody. It leads with the shape of the night, keeps four states apart (fixed itself, handled, needs you, still stuck), links merge requests by URL, and counts recurrence in nights from the entries' own attempt lines. The voice test governs everything: if it cannot be read aloud in under a minute, it is wrong. The benchmark night's 4.6 KB message became 680 characters.

Morning. The night worked 4 projects; 3 merge requests are ready
for your review.

Needs you:
* tooling: merge request ready to review (link)
* site: merge request ready to review (link)
* 3 decisions waiting in the queue (oldest 14 days); your next
  sitting presents them in one batch.
* 6 entries have sat "in progress" for over a week, likely
  orphaned by closed sessions; the board lists them.

Full detail: the dated report, one step down.

That is a real one, names changed. No model writes it. A model on the one surface whose truthfulness is the product is a new way to be wrong, and the brief's own framing is that models are an optimisation, not the topic.

The fourth move came from a failure this week. The drain filed a proposal, escalated it to me when it stalled, and the commit gate refused the whole night's batch, because a proposal has no business being parked on me: its only door is a rank on the board. Sixteen status flips sat staged, and the brief said nothing, because the commit's output went to /dev/null. Now any write a job makes that the gate refuses is a line under "needs you", with the gate's reason, and the escalate verb refuses proposals at the door.

- A refused write is a morning line, never a silent stage.

One rule for the humans, from the same week. Before a session files a queue entry for another project, it checks whether that project has a live session and sends the request there directly, with the acceptance test, asking for a reply. The queue exists for collision safety and durability, not latency, and a live session already holds the target's claim. Silence by the end of the task turns into an entry, so nothing is lost to a message nobody read. The first time it ran, a direct message settled a superseded merge request in minutes where the queue would have waited for the night.

The numbers, three weeks in: 54 entries were parked as needing me. 29 of them were repeat classes I had resolved the same way every time. That number is the next thing I am building against.

The queue still has no database. It just stopped needing me to be one.

My agents run without permission prompts, so the brake moved into the hook

Alkis Yuv — Sat, 05 Sep 2026 21:11:19 +0000

The permission prompt was the last brake on my fleet, and it was in the wrong place. A prompt fires when a human is sitting there to read it. My agents do most of their work when nobody is: the nightly drain, the noon pass, the headless jobs that read the open web. Those run with prompts skipped, by design, because a prompt nobody answers is a stalled job. So the protection was strongest exactly where I was already watching, and absent where the unattended work runs.

What replaced it is a hook. The harness runs a small shell script before every tool call, in every session, in every permission mode, bypass and headless included. The script reads the call as JSON and either lets it through or exits with the code that feeds its message back to the model. Until last week it covered one class: the moves an injected instruction would need, reading a credential file, dumping the keychain, piping a download into a shell. It now covers the class I had left to the prompt: force pushes, a hard reset or a branch swap in the one working tree several live sessions share, a recursive delete aimed at a home or project root, a package release.

The hook exists because of where the old rules lived. One of my contract rules was written in four documents and enforced in one place: a deny list that loads only for a session rooted in a particular directory. Both sessions that broke the rule were rooted somewhere else, so they met no rule at all, while the doctor that checks the setup went green, because it grepped the deny list's text. A rule enforced one directory wide is enforced in the one place the violation was never going to come from. A hook loads everywhere, so it is where a rule that binds every session has to live.

The rule for adding a rule is a throughput rule, not a caution rule. A rule earns its place only if it fires almost never, or if it prevents the kind of cross-session destruction that forces other sessions to redo their work. Anything frequent and recoverable stays out: a plain push, a new branch, a dry-run clean, deleting build output. The test suite has as many passing cases as blocking ones, and the passing ones matter more, because each is a move that happens dozens of times a day, and a false block on any of them costs more than the rule saves.

 move                                     verdict
 git push --force / -f / +ref             refuse, redirect
 git reset --hard, in the shared tree     refuse, redirect
 git checkout main, in the shared tree    refuse, redirect
 rm -rf ~/projects/<repo>                 refuse, redirect
 npm publish                              refuse, owner only
 git push origin main                     pass
 git checkout -b fix/thing                pass
 git reset --hard, in a solo repo         pass
 rm -rf node_modules                      pass
 rm -rf <repo>/dist/assets                pass

Two shapes of refusal, and the difference is my time. A block ends with "the owner runs it", which serialises a parallel session onto the scarcest resource on the machine, so it is reserved for the things only I can do: a credential, a release. A redirect refuses the move and names the sanctioned one in the same breath, so the session corrects itself and keeps going, no human in the loop, no wall-clock lost. Every rule in the destructive class is a redirect.

REFUSED (guard): git push --force rewrites history other sessions
may have built on. Push to a new branch and open a merge request;
gate-only ones merge on their own.
This is not an owner-permission question: take the sanctioned path
above and carry on.

That message is what the model reads. It never reaches me, and it does not need to.

- A refusal that stops a session and waits for me is the most expensive event on the machine. One that redirects it is free.

The guard has a doctor. It feeds 59 synthetic tool calls through itself and checks every verdict, because the harness that calls it has renamed its fields before. If a field the guard reads changes name, the known-bad cases stop blocking, and the doctor fails loudly instead of the guard silently permitting everything. The false-positive half of that suite caught three bugs before the rules landed: a repetition operator from the wrong regex dialect, a separator consumed twice so the recursive clean never matched, and a commit message scanned as command text, which made the guard refuse its own landing commit because the message contained a table of the moves it refuses. Heredoc bodies are prose now.

One more thing learned the hard way. The guard is parsed before every tool call in every session on the machine, so a syntax error in it blocks every tool, including the one that would fix it. A stray quote did exactly that two days before the new rules, and I restored the file by hand. Its header now says: write the new version to scratch, syntax-check it, run its doctor, and only then copy it over.

With the brake in the hook, the prompt became optional, so I turned it off. Bypass is now the default permission mode in every interactive session, and the two headless jobs declare that mode explicitly instead of inheriting whatever the ambient setting happens to be. I had refused the same change earlier that day, on the ground that it removed a brake nothing replaced. The order matters: cover the class first, then drop the prompt.

There is one escape, and it is not a grant. A guard exists to stop a session acting on its own judgment, not to stand between me and my machine. So the escape is me typing the command in my own terminal, where no hook runs. A spoken go-ahead in the conversation does not unblock the tool call, and must never be treated as a reason to retry or reword one. Any signal a session could write to grant itself passage turns the refusal back into a reminder, and a reminder is exactly what failed twice before the hook existed.

The prompt used to ask whether I was sure. The hook doesn't ask. It already knows which moves I was never sure about.

No card ships until a blind judge passes it

Alkis Yuv — Sat, 05 Sep 2026 21:10:43 +0000

My puzzle app, Keyhole, carries 296 dark stories, each with an illustrated card. A dark story is a situation that looks impossible until you drop one false assumption you did not know you were making, and the illustration must show the situation and never the reveal. Draw the aeroplane over the desert and story one is over before the player has read it. In August I ruled that the app does not ship while any card is still flagged by the judge. "End of story," I wrote in the decision, and then spent two days learning what that sentence cost.

Two things get judged, the text and the art, and one design is shared by both. The judge is a model, run blind: it sees the finished card and the story the player sees, and neither the finding that triggered the redraw nor the old card. That is the whole trick. A judge that knows what was wrong last time grades the fix. A judge that knows nothing grades the card. Blindness is what makes a pass mean something, and it is why the judge is a separate call from the writer and from the illustrator, never the same conversation.

The text pass first. A rubric written for the genre, with one test at its centre, "name the one assumption the solver will make that is false", and four semantic questions after it: does the reveal explain everything the situation promised, does the situation give the reveal away, is there a contradiction, can the answer be reached by yes/no questions without knowledge nobody has. Over all 296 stories it flagged 27: five unanswered, nine spoilers, ten sense breaks, three unsolvable. The fix lane rewrites only what a finding names, the deterministic gate must still pass, and the blind judge reads the result cold before it is written back. A fact-check over the rewrites then cleared them, or left a truth note where no honest fix existed.

The art pass is where the numbers live. Each open card was redrawn from a scene brief and judged blind, in waves. The judge wrote a note on every failure, and the lever changed from wave to wave:

  wave   in   adopted  what moved
  1      140  69       the paused run's draws re-judged, free
  2      71   17       the judge's notes fed back to the drawer
  3      54   6        notes alone stopped moving the tail
  4      48   27       briefs rewritten against the notes
  5      21   11       a second brief pass
  6      10   1        briefs hand-written; the traps found
  7      10   4        hand briefs, leak-checked before drawing
  8      5    3        a stronger engine on three cards
  9      2    1        a camera angle the model can hold
  10-11  1    1        the last card, as a banded composition

Three lessons from the table. Re-rolling is not a lever: by wave three, drawing again with notes alone moved six cards out of 54. The brief is the lever: when the brief writer was shown what the judge had rejected, the next wave adopted 27. And the tail is a different problem from the body. The last ten cards needed hand-written briefs, and what the hand found were traps: a brief that used a reveal word, a brief that staged the reveal's concept without the word, and scenes the model cannot hold from prose alone, a face-down figure, a half-submerged building. It obeys camera angles and banded compositions where it ignores adjectives.

The spoiler defence is structural, not a guideline. The function that builds the scene prompt does not take the reveal or the hinge as parameters, so no version of it can leak them. A second lock takes the words the reveal introduces that the front never used, which is the hidden information per story for free, and fails if any of them reached the prompt. That lock taught me two things. Tags are not safe to show an illustrator: a story tagged "aviation" is solved by its tag. And the check must look at the scene, not the whole prompt, because the fixed style clause collided with any reveal containing the word "light", and a warning that cries wolf gets waved through.

- A judge that knows what was wrong last time grades the fix. A judge that knows nothing grades the card.

Cost, since people ask. A draw is about four cents. The hard set on the old image engine had eaten around 1,600 credit units per fixed card before I stopped paying per symptom; the new engine's house style is built from eight of my own clean cards with no training, and follows the brief where the old one kept volunteering foliage. The judge runs on my subscription's weekly cap, and the one pause in the two days was credits and cap running low at once.

The gate is met, 296 of 296. What I have is not proof that the cards are good. It is proof that a reader who had never seen the brief, the finding or the previous attempt looked at every card beside its story and found nothing that gives the game away. For a product whose whole value is the moment before the reveal, that is the only proof there is.

The judge never learned what it was supposed to be looking for. That is why I trust it.

My past rulings decide the repeat cases

Alkis Yuv — Sat, 05 Sep 2026 21:10:07 +0000

Every decision I make for my fleet is written down: a numbered entry with the ruling, the why, what it binds and how to verify it, in a ledger every session reads before it acts. After three and a half months that ledger had 185 entries and a strange property. I kept being asked things it already answered. In three weeks, 54 queue entries were parked as needing me. I sorted them by class: canary drift, nine; machine drift, eight; dependency advisories, five; a push that needed my hands, three; two more classes with two each. 29 of the 54 were repeats I had resolved the same way every time, and about 40 of them carried no line saying why I was needed, which the queue's own protocol already forbids.

So the office I am building for the fleet has a one-line job description: take the simple-to-hard decisions from my past rulings, leave me the exceptional ones. It is not a hosted agent. None of the products I looked at reads a decisions ledger as policy or reaches a work queue, a scheduler, a claims door or a git gate, and the nightly drain they would replace already exists. It is three flows over one board, built from what the fleet's own tools already produce.

The inbound flow decides from precedent. A small tool takes a queue entry and the ledger and derives the entry's class: the title's stem plus its source line, with dates, versions and parentheticals normalised away, so recurrences collapse onto one class. Then it looks for prior rulings in two tiers. A resolved entry of the same class, whose done line is a paste-ready resolution, matches at high confidence; a ledger entry whose title or scope covers the class matches at medium. It is read-only by construction, and any entry whose text trips a rail keyword, a credential, a release, a registry edit, a machine surface, an outward action, reports no match with the rail named, whatever the history says.

$ npx peirad precedent --entry queue/031-canary-drift.md \
    --ledger DECISIONS.md --resolved queue/resolved
class:       canary-drift (from: doctor-canary)
matched:     yes, high
precedent:   queue/resolved/022-canary-drift.md
resolution:  regenerated the canary from the pack; no ruling needed

An alarm whose class matches a precedent is resolved by the steward with that precedent's resolution and a receipt in the morning brief: decided by precedent, entry 22. The entry carries an expiry window in which I can overrule, and an overrule becomes the new precedent for the class. Classes without a precedent stay advisory, exactly as before. The absolute rails, releases, registry edits, credentials, anything outward, never auto-resolve.

- Silence resolves nothing. A precedent resolves it, and says which one.

The outbound flow proposes. Every finding the nightly sweep produces already carries an action, an effort and a confidence, and the sweep names the classes open in two or more projects. Those improvements used to die in a gitignored report. Now a scorer reads them against a rubric my fleet authors, because what is worth doing is my call, not the tool's:

severity     risk 3 · gap 2 · polish 1
economy      S 3 · M 2 · L 1
confidence   high 3 · medium 2 · low 1
breadth      projects carrying it, capped at 3

A proposal that clears the rubric is filed into the queue as a proposal, with an implications section, and a proposal never executes until I rank it. Two exceptions run by precedent, each with a receipt: a standardisation whose fix is small and whose class I already applied once by rank is applied fleet-wide; a class closure at two named rungs of my closure scale, a default or a gate, is prepared as a merge request. A first-of-class application never runs unattended.

The third flow plans by rank. An initiative exists when it has a row on the fleet board, a link to the asset it serves, and a rank I set. The inspector may propose rows; only I rank them. Nothing works an unranked row, not the drain, not the steward, not the worker. A rank is never machine-set. That one sentence is what keeps the office from becoming self-serving. The machinery can find work forever; it cannot decide that its work matters.

The cadence is an office's: a daily brief, weekly planning folded into the Monday sweep, a monthly look at whether the period's focus actually got the hours and the dollars. I meet the office at those three moments and am interrupted only by exceptions.

What I have given up is the feeling of deciding. What I have kept is every decision that was ever mine, in the only form a machine can apply.

The ledger was written so future sessions would obey it. It turns out the sessions can also read it back to me.

I banned the em dash from my AI's voice

Alkis Yuv — Sat, 05 Sep 2026 21:09:32 +0000

At the end of August I was reviewing a weekly digest my pipeline had drafted, and there it was again: the em dash, thirteen times in one issue. I have never written one in my life, and I had been striking them out of the machine's drafts by hand for weeks. That evening I banned it, and not just from the digest. Anything published as my voice, essays, digests and their titles, the manual and its excerpts, bios, replies. Part of the reason is that I hate the thing. The rest is that the em dash is the most recognised tell of machine prose in 2026, and I run a voice engine whose entire job is to make text sound like me rather than like the model. A tell the engine lets through is a bug in the engine.

The rule is one line. The enforcement is where the work went, into three places that cannot drift apart.

The engine carries the ban. hyphos, the open-source tool I wrote to rewrite drafts in my own voice, already had a banned-words rule. Its built-in list ships empty, because which words a writer avoids is personal, not a model-ism; the personal overlay carries the list. An em dash cannot be a banned word though. The rule matched on word boundaries, and a dash is not a word, so it could never fire. The rule class gained a token mode: literal marks matched without boundaries, flagged and never rewritten, because the replacement is a decision per instance.

{
  "id": "banned-words",
  "kind": "banned",
  "words": [],
  "tokens": ["\u2014", "\u2013"],
  "tests": [
    { "in": "a \u2014 b", "flags": 1 },
    { "in": "a \u2014 b \u2013 c", "flags": 2 }
  ]
}

Shown escaped, because not even the rule's own example gets to print the glyph on this site.

Building that surfaced a second bug worth telling. A rule whose compiled pattern can match the empty string, a missing field, an empty word entry, a zero-width regex, fired at every position in the text and reported the text's length plus one as the hit count. My model-ism score had equalled the character count for a day, and I had read it as "very bad" instead of "broken". Such rules are inert now, and the self-test pins the class.

The site refuses the character. One shell script is the single place the check lives. The build gate runs it over all content before anything uploads, the digest tooling runs it over a draft, and the voice step runs it over whatever the engine hands back. Fenced code is exempt, because a fence depicts another text's format rather than speaking for the site; the one essay that quotes a decision-record heading keeps the dash the record actually carries. Everything outside a fence is scanned, front matter included, because titles and descriptions are published text too.

$ bin/no-dash-check.sh src/content
src/content/patterns/claims-and-locks.md:3: description: "..."
no-dash-check: 1 line(s) carry an em-dash (banned on this site)
$ echo $?
1

The drafting rule changed too. The weekly digest is written by a model on a headless rail, and its prompt now forbids the character outright. The first issue drafted under the new prompt came back clean.

Then the replacement itself. The ban says per instance, never a blanket swap, and that turned out to be the real editorial work: 72 rewrites across the six manual chapters, 24 across two excerpts, 13 in the digest issue that started it, 8 on the site. A colon where the dash introduced an expansion, a comma for a parenthetical, a semicolon for a turn, a new sentence where the dash was hiding two thoughts. The dash had been doing four jobs at once, and the prose got better when each job got its own mark.

- The em dash was doing four jobs. The writing improved when each job got its own mark.

The gate proved itself within a day, and against me. On the first of September a description line on one page carried a single dash, and every deploy for the next twenty-four hours refused: eight runs, three hours apart, each naming the same file and line. Nothing shipped, which is the point of a gate. And the refusal named the file, the line and the fix, which is the difference between a gate and a trap. I replaced one character and the next run went out.

Why does a punctuation mark deserve a build gate? Because the alternative is a note to remember, and a note to remember is enforced by nobody at 03:00, when the pipeline drafts and deploys without me. Style rulings target the engine. The engine ships tests. The site holds the line. I get to have taste without having to remember it.

I never used the em dash. Now nothing with my name on it can either.

Every automated job names the model it runs on

Alkis Yuv — Sat, 05 Sep 2026 21:08:55 +0000

Two subscriptions kept running dry while a third sat at one percent. That was the whole finding, and it took an inventory to see it. My fleet runs about sixteen scheduled jobs: a nightly drain of the work queue, a noon pass, a disclosure gate that votes on every commit, a memory router at every session end, sweeps of the open web, a weekly digest draft, four triage jobs each morning. Every one of them calls a model. Nobody had written down which one, and the answer in most cases was: whichever the launcher inherited.

The inventory was done by a read-only agent from primary sources, launcher paths, environment variable names, scheduler plists and the meter log, and its most useful column was "bills to today". The drain children and the memory router ran through the cheap provider's launcher with no model flag, so they resolved my interactive sessions' model pin, an explicit id from the premium provider. The launcher's slot remap does not catch an explicit id, so the request went to the cheap provider carrying a name it does not serve, and the provider served whatever it maps that name to. One probe confirmed it: the usage report named the wrong model, the wrong provider, and a cost of 29 cents that nobody was paying. Every nightly child and every memory-router run for days had run on an undeclared model with a lying cost column.

 job              flag        resolved to           billed to
 drain children   (none)      interactive pin       cheap, mislabelled
 memory router    (none)      interactive pin       cheap, mislabelled
 disclosure gate  small slot  remapped small model  cheap, correct
 radar digest     explicit    premium + web search  premium, correct
 morning triage   (none)      premium default       premium, unmetered

That is the failure class a table kills, so I wrote the table. One deliberate rail per automated job, decided once, recorded in a document with a machine-readable twin, and asserted by the machine doctor every morning.

The rails are the accounts I actually pay for. The premium subscription my interactive sessions use. The same account reached by the worker's containers through a vault, so the containers spend what my sessions spend and follow an account switch. The cheap provider's coding plan, reached through a launcher that now carries a model id on every call. And a third provider's plan, which had zero automated calls before this. The rule that followed the probe is one line: every caller of the cheap launcher names its model. The rule that followed the inventory is one column: why this rail.

The choices are not about saving money. Quality over cost; nothing moved to a weaker model to save quota. What moved is work no human reads. Nightly code work in worktrees, the memory router's per-session summaries and the bulk web sweeps went to the cheap rail with an explicit large model. The gate stayed on the cheap rail's small slot: it makes over a hundred calls a day, each a one-word verdict. Whatever is owner-facing and needs web search stayed premium. Morning triage, four reports a day, went to the third provider so that plan carries something. The premium account was left to the sessions where I am sitting, plus the voice assistant that only runs when I am present.

The meter came first, and it is why I trust the table. Every rail call is wrapped by a script that re-emits the exact output and appends one row per call: model, input, cached and output tokens, cost, duration, exit code. It never changes a rail's outcome; a parse failure emits the raw bytes and a note row, and the child's exit code survives. Its first week said things I would not have guessed. A tool-less one-word judge call sent 13,723 input tokens, because every call carries the operating files, and the follow-up read 13,504 of them from the provider's cache. The gate was 654 of the 694 rows ever logged. And the lint that checks every call site is metered caught an unmetered probe on its first run over the tree.

- A convention nobody checks decays. A table the doctor reads every morning does not.

The doctor closes the loop. For each rail it asserts three things: the launcher still carries its model line, the last meter row names the declared model, and, for the containers, the vault entry belongs to the account currently active and is granted to the worker's agent. A drifted launcher, a mismatched row or a wrong-account vault becomes a finding in the morning brief, filed as a queue entry with the fix named. The grant leg exists because of one night: a fresh vault entry had been registered and granted to nobody, and every container task until morning failed with "this agent does not have access".

The models were never the problem. Not knowing which one was talking was.

What my agents do while I sleep

Alkis Yuv — Sun, 23 Aug 2026 21:59:19 +0000

Every night a scheduled job wakes up, reads a queue of pending work across my projects, and spawns one headless agent session per target to drain it. In the morning I read a report over coffee. That's the pitch, and scheduling it is genuinely the easy part, any cron line can do that. What took actual design is the policy around it, because an unattended agent with write access is a very fast way to wake up to a mess. Five laws came out of that design.

1. The runner owns the envelope, the child owns the work

A headless session cannot mind its manners, it won't maintain a lock, it won't notice a sibling, it dies without cleaning up. So the runner does all of that on its behalf. It takes the claim on the target before spawning the child, refreshes the heartbeat on a timer while the child runs, and releases it always, crash included. Manners stop being the child's job, which means they stop being a hope.

runner: take the claim on the target
  │
  ├─▶ spawn the child, headless, in its own worktree
  │       │  heartbeat renewed on a timer while it runs
  │       ▼
  │   child commits, or finds nothing, or dies, or hits the watchdog
  │       │
  └───────┴─▶ release the claim, always: exit, crash and kill alike

2. Skip, never fight

Five conditions make the runner walk away from a target, every one with a logged reason:

a live interactive session on it
a dirty tree
someone else's claim
an entry marked as needing me
two failed attempts already tonight

The night never contends with the day. Contention is what mornings are for.

3. Nothing touches main

Children commit to their own trees, and where pushing is enabled at all, the runner pushes the night's work to an isolated per-night branch and restores whatever branch was checked out before. I review drained work the way I'd review a colleague's branch, not by discovering it merged.

4. Ceilings, set before the first run

Underneath it all, ceilings. A cap on children per night, a cap on retry rounds, a watchdog per child. I set them before the first unattended run, not after the first runaway, which I recommend as an ordering.

5. The report is unconditional

The rule I'd defend hardest. A report gets written even when there was nothing to do. This sounds trivial and it changes everything, because it converts silence into signal. An absent report can only mean the job died. Before this rule, a quiet morning meant either a quiet night or a broken scheduler, and I had to go check which.

- Automation you have to check up on is just unfinished automation.

The morning read is the acceptance test for the whole thing. The report's skeleton is three headings:

# Night report 2026-08-14
## what happened
## what was skipped, and why
## what needs me

If it can't fill those inside two minutes of my attention, the report is the bug. Five nightly reports in, the streak is young but every morning has had one waiting, and that is the property I refuse to lose. The coffee helps.

A session that closes has to prove it cleaned up

Alkis Yuv — Sun, 23 Aug 2026 21:58:43 +0000

The process monitor said the audio daemon was at 340% CPU. That was the whole symptom, hours after the session that caused it had closed, on a machine that was otherwise fine. Underneath: 326 audio capture streams running at once, 37 GB of raw audio in a temp directory, and a maintenance loop in my dictation setup that had leaked one recorder process per minute since a session earlier that day. That session had ended normally, reported nothing, and left the damage behind. Nothing I had built had a step where a session answers for the machine it is leaving.

Sessions close all the time without a goodbye. A context window ends, the pane gets killed, the laptop sleeps, and whatever the session spawned either keeps running or stops, and either can be wrong. The locks other sessions must respect, the throwaway worktrees the night run cuts, recorder processes, uncommitted files: all of it is state that outlives the session, and no later session knows to look at it. It is the same failure as the report nobody reads, in a different costume.

- A rule no mechanism forces through your eyes is prose.

This is the mechanism for the end of a session.

The design is one script and two hooks, and the property I was after lives in the second hook: a skipped gate cannot stay skipped.

Session end runs a suite of checks and writes a marker file for the project: green with a timestamp, or debt with the findings. Session start reads the marker. Green and less than a week old means silence; nothing printed, the session begins. Missing, stale or red means the previous session skipped the gate or failed it, and the new session inherits the findings as injected context (a start hook's output is context, that is the documented contract) and has to clear them and run the end check itself before doing anything else. A session that dies mid-flight leaves no marker, so the next one runs the suite on its behalf. There is no path through which the debt goes unseen, which is the only property that matters.

session end ──▶ run the suite ──▶ marker: ok, or debt + findings
                                     │
session start ──▶ read the marker ◀──┘
   ├─ ok, under a week old ──▶ silence, the session begins
   └─ missing, stale or debt ──▶ findings injected as context;
                                 clear them, run "end", then work

The suite is deliberately small, and every check names a real incident. Capture streams above two: the 326-stream class. The temp directory over 512 MB or twenty files: the 37 GB class. A lock older than forty-eight hours: a session that died holding it. Uncommitted paths at session end: the wrap-up rule, previously a habit, now checkable. A sweep worktree older than five days: a crashed night. Here is a runnable version with the first three:

#!/bin/sh
# session-gate.sh end|start
MARK="$HOME/.agent-gate/$(basename "$PWD").json"    # (1)
f=""
note() { f="$f  - $1\\n"; }
suite() {                                           # (2)
  n=$(pgrep -f avfoundation | wc -l | tr -d ' ')
  [ "$n" -gt 2 ] && note "AUDIO: $n capture streams (expect 1)"
  kb=$(du -sk /tmp/capture-live 2>/dev/null | cut -f1)
  [ "${kb:-0}" -gt 512000 ] && note "TMP: capture-live ${kb}KB"
  d=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
  [ "$d" -gt 0 ] && note "REPO: $d uncommitted paths"
}
mark() {                                            # (3)
  mkdir -p "${MARK%/*}"
  state=ok; [ -n "$f" ] && state=debt
  printf '{"state":"%s","when":"%s","findings":"%s"}\n' \
    "$state" "$(date -u +%FT%TZ)" "$f" >"$MARK"
}
case "$1" in
  end)   suite; mark ;;
  start) [ -f "$MARK" ] || { suite; mark; }         # (4)
         fresh=$(find "$MARK" -mtime -7)            # (5)
         grep -q '"state":"ok"' "$MARK" && [ -n "$fresh" ] && exit 0
         echo "SESSION-GATE DEBT: the previous session left work."
         echo "Clear it, then run: session-gate.sh end"
         sed -n 's/.*"findings":"\(.*\)".*/\1/p' "$MARK" |
           sed 's/\\n/\n/g' ;;                      # (6)
esac

The marker is per project, so debt greets the session that comes back to the place it was made, not a stranger in an unrelated repo.
One line per check, each named after a real incident; the suite grows by postmortem, never by imagination.
Written on every end, green or red, so an absent marker can only mean a session that never reached its end.
A start with no marker runs the suite itself, on the dead session's behalf.
Green expires after a week; an old green is not evidence.
The findings print verbatim, and a start hook's output is injected context, so the debt is the first thing the new session reads.

Wire end to your agent's session-end hook and start to its session-start hook, and it runs on every session from then on. Had it existed that day, the next session would have opened on this:

$ session-gate.sh start
SESSION-GATE DEBT: the previous session left work.
Clear it, then run: session-gate.sh end
  - AUDIO: 326 capture streams (expect 1)
  - TMP: capture-live 38797312KB

One thing about the shape. The checks are fail-soft and fast; the gate is not there to stop a session from ending, it is there to make the next session's first screen tell the truth.

What I would generalise: any resource a session can leave behind needs a counter somewhere, and the session boundary is the cheapest place to read it. The count that told the truth that day was capture streams, 326 of them, and that count now runs at every session end, whether or not the session remembers to.

The runner deleted what it told me to rescue

Alkis Yuv — Sun, 23 Aug 2026 21:58:07 +0000

One morning my night report said the same thing about two projects, six times over:

- work is committed but the push failed, manual push needed

I went looking for the work. There wasn't any. The children had died in the first second of their lives, a harness binary had moved the day before and was no longer on the path, and the runner had reported a push failure for sessions that never started. The next night the children ran properly, committed real work in four projects, and the runner deleted all of it. Same message.

The night job had just gained a merge-request flow. Each child works in a throwaway worktree on a per-night branch; when it commits, the runner pushes the branch and opens a merge request for my morning. Two defects were stacked under that one sentence, and the second is the one worth the essay.

child, in a throwaway worktree   runner
  commits on the night branch
           │
           ▼
                                 did it commit? compare with upstream
                                 ✗ fresh branch, no upstream: every
                                   child reads as "has unpushed work"
                                 push, from the worktree
                                 ✗ push URL disabled there, by design
                                 report: push failed, manual push needed
                                 cleanup: remove worktree, delete branch
                                 ✗ the only ref to the commits is gone

The first was the test for "did the child commit anything". It compared the branch against its upstream. A fresh branch has no upstream, the lookup failed, the fallback value read as "has unpushed work", and from then on every child, working or dead, looked identical to the runner. A proxy for the fact, not the fact.

The second was the push itself. My worktrees have their push URL disabled by design, it is the rail that guarantees an unattended agent can never push, so the push ran from exactly the place that cannot push. It failed every night it was tried. The report said manual push needed. And then the cleanup step, which had never been told about any of this, removed the worktree and deleted the branch, the only reference to the night's commits. The runner destroyed the thing it had just asked me to save, and the morning report, which files a push failure under things I fix by hand after coffee, gave no sign there was nothing left to push.

What saved the work is git's habit of keeping unreferenced objects around until a garbage collection. The rescue is three commands, and the comment is the important one:

$ git fsck --no-reflogs --lost-found | grep commit
dangling commit 3f9c2a1d7e...
dangling commit 8b07d4c5a2...
$ git log -1 --oneline 3f9c2a1
3f9c2a1 drain: align the retry helper with the new timeout API
$ git branch rescue/2026-08-21 3f9c2a1      # a ref, nothing else
# do NOT gc, prune or worktree-prune first: unreachable is what gc
# deletes

Four repos came back that way the same night. A fifth had two orphans the sweep missed, found by hand while writing this; one was five days old, and a later merge message had described it as already on main.

The fix is three changes, and each is a version of the same rule: decide from what verifiably exists, never from what a message says.

-# did the child commit? a proxy: compare the branch with its upstream
-n=$(git rev-list --count "$b@{u}..$b" 2>/dev/null || echo 1)
+# did the child commit? the fact: HEAD moved while the child ran
+pre=$(git rev-parse HEAD)
+run_child
+post=$(git rev-parse HEAD)
+[ "$post" != "$pre" ] && committed=1

-# cleanup: always
-git worktree remove "$wt" && git branch -D "$b"
+# cleanup: only when the remote verifiably holds every commit
+n=$(git rev-list --count "$b@{u}..$b" 2>/dev/null || echo 1)
+[ "$n" -eq 0 ] && git worktree remove "$wt" && git branch -D "$b"

Outcome is measured as HEAD movement during the child's run. A child that dies within thirty seconds with no commits is reported as exactly that, with the last two lines of its own output quoted in the report, and it gets no more rounds that night; a real session takes minutes even when it finds nothing to do. The push goes from the parent checkout, where pushing is allowed. And the branch is deleted only when the count of commits the remote lacks is zero, or the commits never existed. "Push failed" now means a commit exists and the remote does not have it, which is the only thing it ever should have meant.

The lesson generalises past git. Every night produces a report, and I had been treating the report as the state. It is a claim about the state, made by the same program that made the mistake.

- The destructive step in any automation has to be conditioned on the verified success, not the reported one.

And the two failures that look alike from outside, never started and started-then-failed, need different words, because the operator does different things for each. I had written that rule down for agents: re-verify before you repeat, assert from the primary source. It applies to shell scripts just as well, and they are even less likely to feel the tell.

One directory is the task manager my agents share

Alkis Yuv — Sun, 23 Aug 2026 21:57:31 +0000

When you run agents across many projects, findings stop respecting project boundaries almost immediately. A session working on one tool discovers a bug in another. A review in one repo produces work for three. My first instinct was the obvious one, let the session go fix it over there. That instinct is how two agents end up editing the same tree, and after auditing five collisions I banned it. A session's only sanctioned write into another project is a queue entry.

The queue is embarrassingly low-tech, one directory per target, one markdown file per task, a status line in the front matter: pending, taken, done, dropped. No database, no integration, and the only board is a one-page summary generated from the files themselves. Files stay put forever as history, and the receiving project's next session gets offered its pending entries automatically when it starts, take, defer, or drop, and the answer is written into the entry so nothing ever asks twice.

handovers/
├── board.md                  generated from the entries, one page
├── site/
│   ├── 004-syndication.md    status: done
│   └── 007-display-shapes.md status: pending
└── tooling/
    └── 012-retry-helper.md   status: taken

The lifecycle is four states and two side doors:

              take                       evidence pasted
 pending ──────────────▶ taken ──────────────────────────▶ done
   │  ▲                    │
   │  │ date reached       └──▶ dropped, reason written into the entry
   │  │
   ▼  │
 snoozed, at most a week       severity: risk ignores the snooze and
                               resurfaces every session until dealt with

A complete entry fits on one screen:

---
status: done
severity: normal
created: 2026-08-09
---
# Align the retry helper with the new timeout API

The ask: the helper still passes an option the API dropped in v3.
Update the call sites and run the suite.
Context: the failing CI run, and the changelog entry that dropped it.
Acceptance: `npm test` exits 0 with the retry cases green.
Evidence: "12 passed, 0 failed", pasted by the taker, 2026-08-10.

What makes it work is not the format though, it's three authoring rules that came from watching it fail.

Every entry carries an acceptance test. The body is written so the receiving session needs nothing else, the ask, the context links, and how to know it's done. Entries that skipped this read like riddles a week later, and riddles get dropped.

Done requires evidence. One pasted line showing the acceptance test passing.

- An assertion without evidence is not done, it's a hope with a status field.

This rule came directly from catching claims of finished work that a thirty-second check would have disproven.

And absence claims name what was checked. An entry once justified itself with "no record says this value is deliberate" while the record said exactly that, one file over. I ruled on a false premise that day. Since then, "nothing documents X" is only writable alongside the list of places you looked.

There is also a small vocabulary for time and urgency, a snooze field that hides an entry until a date, hard-capped at a week because my setup changes too fast for longer parking, and a risk severity that ignores snoozing entirely and resurfaces every session until someone deals with it.

The part I like most, the same queue serves humans and machines. My nightly automation drains the same entries my interactive sessions do, skips the ones marked as needing me, and flips the same statuses with the same evidence rule. One protocol, no translation layer. For coordination between agents, I keep finding that a directory of honest text files beats anything cleverer I've tried.

The queue's best story is not in this piece though. It's the night my agents built the same feature twice, where every file told the truth and I was the part that didn't.

Rules my agents actually follow

Alkis Yuv — Sun, 23 Aug 2026 21:56:55 +0000

I once measured how long a written rule survives a fresh agent session: 67 minutes. The rule was recorded right after one session swept another session's half-finished files into its commit, and it was plain:

- Stage explicit paths only, never git add -A.

The next session had never lived the incident, read the rule as advice, and did the thing anyway.

Everyone who works with coding agents ends up keeping some kind of mistakes file, the agent breaks something, you write down what happened, and you hope the note prevents a repeat. I kept one too. What the 67 minutes taught me is that the file is the easy third of the problem. The other two thirds are getting the rule enforced, and keeping the record small enough that anyone, human or agent, still reads it.

A written rule does not survive on its own, that is the honest part. Agents repeat mistakes while remembering the rule, you can watch them acknowledge it and do the thing anyway. Prose loses the fight against a model's priors. So my decision records stopped being prose and became entries with a fixed anatomy. This is the whole shape, using that staging rule as the worked example:

## D-035 — 2026-08-02 — Stage explicit paths only, never add-all
**Decision:** one imperative sentence, no hedging.
**Why:** written for a stranger with no transcript.
**Invariant:** the line that must stay true for the rule to hold.
**Boundary:** the condition under which this rule stops applying.
**Rung:** law or practice, how hard it binds.
**Verify:** `grep -rn "git add -A" hooks/ scripts/` → nothing
**Scope:** which projects the entry covers.

The two fields that changed everything are the least glamorous ones.

The first is Why, written for a stranger with no transcript. Not "as discussed", not a summary of a chat that no longer exists. If the reason can't stand alone, the decision will be relitigated by the next session and probably lost.

The second is Verify, a runnable command with an expected output. A rule you can only read is checked by luck. A rule you can execute is checked by machines, on schedule, forever. When one of my entries drifted from reality, the audit flagged it as a failing check and the fix was a one-line commit. Decay surfaced as a finding instead of a surprise. The auditor is the one piece of this system I made public, etymd, it reads the claims your instruction files make and checks them against the actual repo, npx etymd audit and you have it.

Between the mistakes file and the record there is a path, and I'd argue this path is the actual system. An incident gets noted where it happened, cheap and unstructured. Recurrence makes it countable. Only a countable pattern graduates into the record, with an invariant and a verify line, and only recorded rules get wired into hooks that block instead of advise.

incident, noted where it happened      cheap, unstructured
        │  happens again
        ▼
countable pattern                      a count, not a feeling
        │  graduates
        ▼
record entry: invariant + verify       law
        │  wired into
        ▼
hook that blocks instead of advising   enforcement

Skip the middle and you get rules nobody believes. Skip the end and you get beliefs nobody follows.

- Evidence, then law, then enforcement.

And then there is bloat, which in the agent era is the default outcome. Models write more than anyone reads, records grow faster than they bind, and a 3000-word decision document is just prose with a fancier name. My counterweights are all mechanical. Index lines have a character budget and a hook rejects the commit that exceeds it, I have watched it reject my own agent mid-task, which is exactly the point. Files have word budgets checked by an audit. A fact lives in exactly one document and the same decision recorded twice is treated as a defect, because two copies always drift.

The anatomy itself is the quiet anti-bloat device though. Seven short fields leave an essay nowhere to hide.

My night shift built the feature, and my day shift didn't notice

Alkis Yuv — Sun, 23 Aug 2026 21:56:19 +0000

I have a queue where cross-project work waits, and a nightly job that drains it, one headless agent per project, rails everywhere, rails being the mechanically enforced guardrails that stand in for trust in these setups. Last week an entry sat in that queue: build a writing section for my site. What happened to it over one night taught me more about running agents than the feature itself.

The night run took the entry properly, flipped its status, built the whole thing on an isolated branch, recorded its design decisions, and then stopped one step short on purpose. Its rails forbid publishing to the live site unattended. It wrote, in its own report, that deploying would bypass the morning review, and left me a one-line instruction for the morning. So far, the system working exactly as designed.

The morning shift was me, working with an interactive agent. And we built the same feature again, from scratch, on the main branch, and deployed it. Not because anything malfunctioned, but because I had read that queue entry a day earlier, when it still said pending, and I carried that stale picture in my head instead of re-reading the entry it would have taken ten seconds to open. The status file said taken. I never looked. And the night's report, the one carrying that one-line instruction, went unacted on that same morning, which I have to own too. A report no gate forces through your eyes is prose as well.

           night shift, headless         day shift, me with an agent
 evening   takes the entry: taken
           builds on its own branch
           stops before deploy, by rule
           reports: deploy after review
 morning                                 reads my memory: still pending
                                         rebuilds on main, deploys
 later     ── the two builds meet in review; the merge takes both ──

Here is what I find worth writing down. Every mechanized rail held. The claims kept the two builds from ever touching the same files, the drain's no-publish rule kept the night work reviewable, the branch isolation kept main clean. The only thing that failed was the part that ran on memory instead of mechanism, my own assumption that yesterday's state was still today's.

- Stored state decays, and the feeling of already knowing is exactly the moment the ten-second check is worth it.

I have that rule written down, of course. Rules in prose decay too, that's the joke, and it lands on me this time. So the fix that outlived the joke is mechanical, as it had to be. The queue now generates a one-page board from the entries, and taken sits as its own section on it, the night's claims in front of the day shift's eyes before any work starts. Built before that day ended, naturally.

The reconciliation had its own lesson. Two implementations of one feature, one by an unattended agent, one by an agent with me in the loop, and when I reviewed them side by side the night version was better. Cleaner architecture, a sitemap that maintains itself, fewer special cases in the server config. It also missed something only the live deployment surfaced, which the day version had already hit and solved. So the merge took the night's architecture and the day's hard-won fix, and both builds ended up mattering, which is a kinder ending than the duplicated hours deserved.

If you run agents overnight, my takeaways are three. Give the night shift rails, not trust, it will happily respect rules that are mechanically enforced. Make the morning review a real step, not a formality, mine genuinely picked a winner. And before you start any work, re-read the queue, not your memory of the queue. The entry knows. You only think you do.