<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
<channel>
<title>Dan Mercede</title>
<link>https://www.danmercede.com/</link>
<description>Essays and guides from Dan Mercede: turning AI from experiments into owned, governed workflows operators can actually run.</description>
<language>en</language>
<lastBuildDate>Tue, 17 Nov 2026 08:00:00 +0000</lastBuildDate>
<docs>https://www.rssboard.org/rss-specification</docs>
<atom:link href="https://www.danmercede.com/feed.xml" rel="self" type="application/rss+xml"/>
<atom:link href="https://pubsubhubbub.appspot.com/" rel="hub"/>
<item><title>Preserving Conversation Branches in Neo4j: A Runnable Example</title><link>https://www.danmercede.com/guides/preserving-conversation-branches-neo4j</link><guid isPermaLink="true">https://www.danmercede.com/guides/preserving-conversation-branches-neo4j</guid><pubDate>Tue, 17 Nov 2026 08:00:00 +0000</pubDate><description>Preserve conversation branches with parent links and a selected leaf. Run a five-message example locally, then inspect scoped Neo4j MERGE and ancestry queries.</description><content:encoded>&lt;h2 id=&quot;how-do-you-preserve-a-conversation-s-branches&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you preserve a conversation&amp;#x27;s branches?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Give every message a stable ID, preserve its parent ID, and store the selected leaf as a separate value. Follow only that leaf&amp;#x27;s parents when constructing the selected transcript. Keep the other messages and edges so another branch can still be recovered. Sorting all messages into one list can join answers that belonged to different paths.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Scope:&lt;/strong&gt; this is a synthetic, normalized five-message tree. It is not a ChatGPT export specification, a production ingestion pipeline, or a sample from private conversations. The local program validates the tree and generates Cypher text; it makes no network or database calls.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Evidence:&lt;/strong&gt; the &lt;a href=&quot;https://www.danmercede.com/examples/conversation-branches/fixture.json&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;fixture&lt;/a&gt; and &lt;a href=&quot;https://www.danmercede.com/examples/conversation-branches/branches.mjs&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;dependency-free program&lt;/a&gt; are published with this page. The Node example was executed for this release. The generated Cypher was checked against Neo4j&amp;#x27;s documentation, but was not executed against a Neo4j database for this guide.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/conversation-branches/preserve-branches.webp&quot; alt=&quot;Five synthetic messages fork after u1: one branch is u1, a1, u2; the selected branch is u1, a2, u3. Four parent links preserve both histories.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Synthetic conversation branch-demo. Selecting u3 keeps the rollback path active while preserving the tests path.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h2 id=&quot;what-does-the-small-example-contain&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does the small example contain?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Conversation &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;branch-demo&lt;/code&gt; has five messages. The two assistant replies share the same parent; they are alternatives, not consecutive turns.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Message&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Role&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Text&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Parent&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;user&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Can we ship?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;null&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a1&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;assistant&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Check tests&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u2&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;user&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Tests passed&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a1&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a2&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;assistant&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Check rollback&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u3&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;user&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Rollback ready&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a2&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The selected leaf is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u3&lt;/code&gt;. Its transcript is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a2&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u3&lt;/code&gt;: “Can we ship?”, “Check rollback”, “Rollback ready”. The alternate path &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a1&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u2&lt;/code&gt; remains available. Appending all five messages would falsely put both assistant replies and their follow-ups into the same exchange.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This model has &lt;strong class=&quot;font-semibold text-white&quot;&gt;five message nodes, four parent edges and two root-to-leaf paths&lt;/strong&gt;. A separate conversation node in Neo4j holds the conversation ID and selected-leaf property; it is not included in the five-message count.&lt;/p&gt;&lt;h2 id=&quot;run-the-branch-preserving-example-locally&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Run the branch-preserving example locally&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Download &lt;a href=&quot;https://www.danmercede.com/examples/conversation-branches/branches.mjs&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;branches.mjs&lt;/a&gt; and &lt;a href=&quot;https://www.danmercede.com/examples/conversation-branches/fixture.json&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;fixture.json&lt;/a&gt; into the same directory. With Node.js 20 or later:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;sh&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-sh&quot;&gt;node branches.mjs&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The output includes these fields, followed by the selected messages with their roles and text:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;json&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-json&quot;&gt;{
  &amp;quot;conversation&amp;quot;: &amp;quot;branch-demo&amp;quot;,
  &amp;quot;message_nodes&amp;quot;: 5,
  &amp;quot;parent_edges&amp;quot;: 4,
  &amp;quot;root_to_leaf_paths&amp;quot;: 2,
  &amp;quot;paths&amp;quot;: [[&amp;quot;u1&amp;quot;, &amp;quot;a1&amp;quot;, &amp;quot;u2&amp;quot;], [&amp;quot;u1&amp;quot;, &amp;quot;a2&amp;quot;, &amp;quot;u3&amp;quot;]],
  &amp;quot;selected_leaf&amp;quot;: &amp;quot;u3&amp;quot;,
  &amp;quot;selected_path&amp;quot;: [&amp;quot;u1&amp;quot;, &amp;quot;a2&amp;quot;, &amp;quot;u3&amp;quot;]
}&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Change only &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;selected_leaf&lt;/code&gt; to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u2&lt;/code&gt;, rerun the command, and the selected path becomes &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a1&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u2&lt;/code&gt;. Both branches remain stored. This is selection over preserved history; it does not rewrite message ancestry.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The script rejects duplicate message IDs, unknown parents, cycles, multiple roots, missing selections and a selected node that still has children. These checks run before it prints a summary or emits Cypher. Message order in the JSON array is not used to infer ancestry.&lt;/p&gt;&lt;h2 id=&quot;how-does-the-model-map-to-neo4j&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How does the model map to Neo4j?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The generated example uses isolated labels:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Model element&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Neo4j representation&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Conversation&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BranchExampleConversation&lt;/code&gt;, unique &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;id&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Message&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BranchExampleMessage&lt;/code&gt;, unique pair &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;(conversation_id, id)&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Parent link&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;(child)-[:REPLIES_TO]-&amp;gt;(parent)&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Current selection&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;selected_leaf&lt;/code&gt; property on the conversation&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Message IDs are scoped to their conversation. The selected leaf is a property, so changing the selection does not accumulate competing “current” relationships. The parent edges point backward toward the root; reading order is obtained by reversing the resulting ancestry path.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Restore &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;selected_leaf&lt;/code&gt; to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u3&lt;/code&gt; in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;fixture.json&lt;/code&gt; to reproduce the selected transcript shown below. Then generate the Cypher locally.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;sh&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-sh&quot;&gt;node branches.mjs --cypher &amp;gt; branch-demo.cypher&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Inspect the file before running it in a disposable Neo4j database. It creates two named uniqueness constraints, merges the conversation and message identities, and merges the four parent relationships. It contains no deletion command. Neo4j documents &lt;a href=&quot;https://neo4j.com/docs/cypher-manual/current/clauses/merge/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;MERGE&amp;#x27;s match-or-create behavior&lt;/a&gt; and &lt;a href=&quot;https://neo4j.com/docs/cypher-manual/current/schema/constraints/create-constraints/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;composite property uniqueness constraints&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Repeating the unchanged fixture is designed to reuse the same nodes and edges. Message content is set only when a message is created; the selected-leaf property is updated independently. &lt;strong class=&quot;font-semibold text-white&quot;&gt;This is not a synchronization algorithm:&lt;/strong&gt; use a new conversation ID for a changed content or ancestry snapshot. Reusing identities for different parent links could leave old edges behind. A production importer needs an explicit revision and conflict policy.&lt;/p&gt;&lt;h2 id=&quot;read-only-the-selected-ancestry&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Read only the selected ancestry&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The generated file ends with this query for the five-message fixture:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;cypher&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-cypher&quot;&gt;MATCH (c:BranchExampleConversation {id: &amp;quot;branch-demo&amp;quot;})
MATCH p=(leaf:BranchExampleMessage {conversation_id: c.id, id: c.selected_leaf})
        -[:REPLIES_TO*0..4]-&amp;gt;(root:BranchExampleMessage)
WHERE NOT (root)-[:REPLIES_TO]-&amp;gt;(:BranchExampleMessage)
  AND all(m IN nodes(p) WHERE m:BranchExampleMessage AND m.conversation_id = c.id)
RETURN [m IN reverse(nodes(p)) | {id: m.id, role: m.role, content: m.content}]
       AS selected_transcript;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Starting at &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u3&lt;/code&gt; and following parent edges can reach &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a2&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;; it cannot move down the other branch to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a1&lt;/code&gt; or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u2&lt;/code&gt;. The predicate limits the path to this conversation and ends at a root. The four-edge ceiling is derived from this fixture&amp;#x27;s node count, not a recommended limit for every conversation. See Neo4j&amp;#x27;s &lt;a href=&quot;https://neo4j.com/docs/cypher-manual/current/patterns/variable-length-paths/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;variable-length path documentation&lt;/a&gt; for the underlying traversal syntax.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The expected selected IDs are &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u1&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a2&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;u3&lt;/code&gt;. That is a documentation-checked query expectation, not a reported Neo4j execution result.&lt;/p&gt;&lt;h2 id=&quot;what-must-an-adapter-do-with-a-real-export&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What must an adapter do with a real export?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Normalize a supported export shape before using this example&amp;#x27;s validator. An export can contain structural roots with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;message: null&lt;/code&gt;, missing content, edited nodes or vendor-specific selection fields. Do not turn a structural root into an invented human message, silently discard its descendants, or guess parentage from timestamps.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An adapter should retain the source identifiers and ancestry, state how structural nodes are represented, and reject unsupported shapes. This sample requires exactly one message root and one selected leaf; it deliberately rejects raw export objects that do not satisfy that contract. Keep versioned fixtures for every export shape the adapter claims to support.&lt;/p&gt;&lt;h2 id=&quot;what-does-this-prove-about-the-larger-knowledge-graph&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does this prove about the larger knowledge graph?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This example proves a small data-model property locally: two branches survive, and selecting one returns only its ancestry. It does not measure retrieval quality, agent usefulness or production ingestion reliability.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;a href=&quot;https://www.danmercede.com/thoughts/2026-09-30-the-knowledge-graph-my-agents-stopped-asking&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;original knowledge-graph field report&lt;/a&gt; covers a different question. Its September 30, 2026 snapshot includes a preceding 30-day caller audit and a separate March-through-September monthly search history. Those windows should not be combined into one measurement. This companion adds no new usage observations.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Preserving history also does not grant it authority. Retrieved conversation content remains advisory context; current repository instructions, code and tests still govern the work. For the behavior check after an agent changes, continue to the &lt;a href=&quot;https://www.danmercede.com/guides/regression-test-ai-agent-prompt-model-change&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Proctor regression-testing guide&lt;/a&gt;.&lt;/p&gt;</content:encoded></item>
<item><title>How to regression-test an AI agent after a prompt or model change</title><link>https://www.danmercede.com/guides/regression-test-ai-agent-prompt-model-change</link><guid isPermaLink="true">https://www.danmercede.com/guides/regression-test-ai-agent-prompt-model-change</guid><pubDate>Tue, 17 Nov 2026 08:00:00 +0000</pubDate><description>Test an AI agent against behavior contracts after prompt or model changes. Reproduce an invoice regression with Proctor and a keyless Node example.</description><content:encoded>&lt;h2 id=&quot;what-should-an-agent-regression-test-check&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What should an agent regression test check?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Check the behavior you depend on:&lt;/strong&gt; required fields, exact business rules, allowed actions, and task-specific evidence. Run the same representative inputs against the baseline and the candidate. Treat a broken hard rule as a failure even when an evaluator likes the response. Keep subjective quality checks separate so a better turn of phrase cannot excuse an incorrect amount.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Scope:&lt;/strong&gt; this walkthrough tests invoice extraction using deterministic, synthetic outputs. It demonstrates regression detection and review routing. It does not measure a live model&amp;#x27;s accuracy, certify an invoice for payment, or install a production execution gate.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Reproduced evidence:&lt;/strong&gt; at &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/tree/ed7b11a156cacfc23b646eeb370fab376cbe6d66&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Proctor commit &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ed7b11a&lt;/code&gt;&lt;/a&gt;, five fixtures produced &lt;strong class=&quot;font-semibold text-white&quot;&gt;45 of 45 passing assertions&lt;/strong&gt; for the good path and &lt;strong class=&quot;font-semibold text-white&quot;&gt;40 of 45&lt;/strong&gt; for the deliberately degraded path. Every failure was the invoice-total invariant; the classifier returned &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;real-regression&lt;/code&gt;. The &lt;a href=&quot;https://www.danmercede.com/examples/agent-regression/verification.json&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;verification record&lt;/a&gt; names the source, commands, and limits. The &lt;a href=&quot;https://www.danmercede.com/works/proctor/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Proctor project page&lt;/a&gt; gives the broader project context.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/agent-regression/contract-regression.webp&quot; alt=&quot;Illustrated invoice regression: line items 100 and 50 require a total of 150; a candidate reporting 100 fails the contract and is held for review.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Concept diagram of the synthetic invoice example, not a screenshot of a production receipt.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h2 id=&quot;one-plausible-answer-one-concrete-failure&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;One plausible answer, one concrete failure&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The first &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/packages/sut-invoice/fixtures/inv-001.json&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;upstream invoice fixture&lt;/a&gt; has line items of 100 and 50. The good extractor returns 150. The deterministic degraded extractor returns only the first item&amp;#x27;s amount, 100. Both responses contain &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;vendor&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;currency&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;date&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;line_items&lt;/code&gt;, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;total&lt;/code&gt;.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Check&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Good output&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Degraded output&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Required fields are present&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Vendor is nonempty&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Currency is consistent&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Date is parseable&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Pass&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Line items sum to the reported total&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;100 + 50 = 150: pass&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;100 + 50 != 100: fail&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A schema or presence check alone cannot catch this bug. The &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/packages/engine/src/invariants.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;sum invariant&lt;/a&gt; compares the reported total with the line-item sum, using an absolute tolerance of &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;1e-6&lt;/code&gt; in this implementation. The &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/packages/engine/src/classifier.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;classifier&lt;/a&gt; recognizes an invariant failure before calling its optional reasoning dependency. That is the property this example proves.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The keyless learner produces this contract for the demo fixtures:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;json&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-json&quot;&gt;{
  &amp;quot;sutId&amp;quot;: &amp;quot;invoice&amp;quot;,
  &amp;quot;version&amp;quot;: 1,
  &amp;quot;fields&amp;quot;: [
    { &amp;quot;name&amp;quot;: &amp;quot;vendor&amp;quot;, &amp;quot;kind&amp;quot;: &amp;quot;structural&amp;quot; },
    { &amp;quot;name&amp;quot;: &amp;quot;currency&amp;quot;, &amp;quot;kind&amp;quot;: &amp;quot;structural&amp;quot; },
    { &amp;quot;name&amp;quot;: &amp;quot;date&amp;quot;, &amp;quot;kind&amp;quot;: &amp;quot;structural&amp;quot; },
    { &amp;quot;name&amp;quot;: &amp;quot;line_items&amp;quot;, &amp;quot;kind&amp;quot;: &amp;quot;structural&amp;quot; },
    { &amp;quot;name&amp;quot;: &amp;quot;total&amp;quot;, &amp;quot;kind&amp;quot;: &amp;quot;structural&amp;quot; }
  ],
  &amp;quot;invariants&amp;quot;: [
    &amp;quot;sum_line_items_eq_total&amp;quot;,
    &amp;quot;currency_consistent&amp;quot;,
    &amp;quot;vendor_nonempty&amp;quot;,
    &amp;quot;dates_parseable&amp;quot;
  ]
}&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Here, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;structural&lt;/code&gt; means present and non-null. It does not establish a field&amp;#x27;s correct value. The invariant implementations supply the concrete checks named in the contract.&lt;/p&gt;&lt;h2 id=&quot;run-a-small-example-without-dependencies&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Run a small example without dependencies&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Download &lt;a href=&quot;https://www.danmercede.com/examples/agent-regression/invoice-contract.mjs&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;invoice-contract.mjs&lt;/a&gt;, inspect it, and run it with Node.js 20 or later:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;node invoice-contract.mjs&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expected output:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;PASS baseline
PASS formatting
BLOCK regressed: sum_line_items_eq_total: expected 15000, received 10000
3 expected decisions reproduced. No model or production tool was called.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This is a &lt;strong class=&quot;font-semibold text-white&quot;&gt;standalone teaching fixture&lt;/strong&gt;, not a replacement for the Proctor engine. It expresses amounts as integer cents, permits the vendor&amp;#x27;s capitalization to change, and rejects a mismatched total. It makes no network requests and writes no files. Its three cases let you check that the contract accepts a known-good result, tolerates one harmless variation, and catches the specific regression.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;To inspect one decision with a meaningful process exit code:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;node invoice-contract.mjs --check baseline
node invoice-contract.mjs --check formatting
node invoice-contract.mjs --check regressed&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The first two exit with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;0&lt;/code&gt;. The deliberately regressed case prints &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;passed: false&lt;/code&gt; and exits with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;1&lt;/code&gt;. An unknown fixture or invalid argument exits with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;2&lt;/code&gt;. The default three-case demonstration exits successfully when all three &lt;strong class=&quot;font-semibold text-white&quot;&gt;expected decisions&lt;/strong&gt; occur, including the expected block.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A sum check proves internal consistency. An extractor that changes both the line items and the total to matching but incorrect values can still pass it. Add checks against the source invoice and task-specific expected facts before using an extraction result in a real workflow.&lt;/p&gt;&lt;h2 id=&quot;reproduce-the-proctor-result&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Reproduce the Proctor result&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The upstream project specifies Node.js 20+ and pnpm 9.12.0. Start from the pinned commit so the walkthrough and implementation agree:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;git clone https://github.com/OrionArchitekton/proctor.git
cd proctor
git checkout --detach ed7b11a156cacfc23b646eeb370fab376cbe6d66
pnpm install --frozen-lockfile
PROCTOR_FAKE_LLM=1 PROCTOR_GATEWAY=local pnpm demo&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The environment assignment shown is Bash syntax. It forces the keyless fake extractor and local gateway even if your shell already contains other settings. The &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/scripts/seed-demo.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;demo script&lt;/a&gt; learns a contract, runs both model labels, classifies the failure, and creates a local approval-task record.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The result to look for is:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;GOOD:       allPassed: true  (45/45 assertions)
DEGRADED:   allPassed: false (40/45 assertions)
Failure:    sum(line_items.amount)=150 total=100
Verdict:    real-regression
Rationale:  invariant violated: sum_line_items_eq_total&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This is a condensed excerpt of the executed run; the other four invoices fail the same invariant. Five structural fields plus four invariants make nine assertions per invoice, or 45 across the five fixtures. In keyless mode, the &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/workflows/src/deps.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;field proposer&lt;/a&gt; deliberately chooses structural checks for every field. The value-level protection here comes from the invariants.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For this guide&amp;#x27;s review, the installed demo script ran with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;node --import tsx scripts/seed-demo.ts&lt;/code&gt; under the same two environment settings. That runs the script behind &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;pnpm demo&lt;/code&gt; without the CLI&amp;#x27;s IPC listener. The upstream unit suite passed &lt;strong class=&quot;font-semibold text-white&quot;&gt;77 tests&lt;/strong&gt;, and the separate durable-workflow integration test passed &lt;strong class=&quot;font-semibold text-white&quot;&gt;one suspend/resume cycle&lt;/strong&gt;. These runs used the local gateway and fake extractor; they did not call a paid model or a live UiPath tenant.&lt;/p&gt;&lt;h2 id=&quot;what-happens-after-the-failure&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What happens after the failure?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The narrated demo creates a local task record. It does &lt;strong class=&quot;font-semibold text-white&quot;&gt;not&lt;/strong&gt; start the durable workflow runtime, send a real UiPath task, or prove a process restart can resume an approval. The separate upstream commands are &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;pnpm dev&lt;/code&gt; for the local dashboard and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;pnpm test:int&lt;/code&gt; for the suspend/resume integration test.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In the &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/workflows/src/proctorCycle.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;workflow implementation&lt;/a&gt;, passing reports complete; a &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;flaky&lt;/code&gt; verdict is recorded; &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;real-regression&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;legitimate-evolution&lt;/code&gt; wait for a human decision. Only &lt;strong class=&quot;font-semibold text-white&quot;&gt;approved legitimate evolution with a proposed patch&lt;/strong&gt; versions the contract. Approving a real regression does not rewrite the contract or change the failed report into a pass.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a quick visual comparison, open the &lt;a href=&quot;https://www.danmercede.com/proof?scenario=proctor-drift#gate-simulator&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Proctor drift scenario on Proof&lt;/a&gt;. That simulator illustrates the difference between an advisory warning and a held action. It is a separate browser demonstration, not the Proctor test runner.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-turn-this-into-a-merge-gate&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you turn this into a merge gate?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the demo and release decision separate. &lt;strong class=&quot;font-semibold text-white&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;pnpm demo&lt;/code&gt; returns success when the demonstration finishes, even though it deliberately detects a regression.&lt;/strong&gt; Its process exit code is not a ready-made CI approval signal.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An integration for your agent should run the candidate through the contract and fail its required check when &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;report.allPassed&lt;/code&gt; is false or the run is incomplete. Keep the report as evidence. If you allow a reviewer to approve legitimate evolution, version the reviewed contract and rerun the candidate against that version before accepting the change.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use a review packet with enough information to reproduce the decision:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Record&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Why it matters&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Baseline and candidate revisions&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Identifies the actual prompt, model configuration, and adapter being compared&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Fixture revision and contract version&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Keeps the target behavior from silently moving with the candidate&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Per-case results and raw outputs&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Shows which rule failed and which input caused it&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Repeated runs for variable behavior&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Helps separate intermittent failures from stable drift&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Reviewer, decision, and resulting version&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Makes any accepted behavior change explicit&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a live agent, change one variable at a time where practical. Keep the input set fixed and run enough repetitions for the behavior you are assessing. A pass over five synthetic invoices does not establish a production error rate. A merge gate also needs repository enforcement; a green local command alone cannot stop a merge. See &lt;a href=&quot;https://www.danmercede.com/thoughts/2026-05-19-the-merge-is-a-state-mutation&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;The Merge Is a State Mutation&lt;/a&gt; for that separate boundary.&lt;/p&gt;&lt;h2 id=&quot;what-this-version-does-not-cover&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What this version does not cover&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Proctor&amp;#x27;s current &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/packages/engine/src/runner.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;runner&lt;/a&gt; compares exact and semantic fields with the first value it sees in that run. It does not persist a separate expected reference for every fixture. A consistently wrong candidate can therefore establish its own field-level baseline, and diverse inputs need careful handling. The hard sum invariant still detects the failure shown above.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;a href=&quot;https://github.com/OrionArchitekton/proctor/blob/ed7b11a156cacfc23b646eeb370fab376cbe6d66/apps/web/app/api/approve/route.ts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;local approval endpoint&lt;/a&gt; also lacks production authentication and reviewer authorization. Use the dashboard locally for evaluation; an operational integration needs authenticated decisions and server-side task validation. These are concrete limits of the implementation, not evidence that a particular model is safe or unsafe.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with one failure that matters to your workflow. Write the rule that would have caught it, preserve its input as a fixture, and demonstrate both the pass and the failure. That gives the next prompt or model change an observable decision instead of another subjective reread.&lt;/p&gt;</content:encoded></item>
<item><title>What Does Your AI Mean by Ready?</title><link>https://www.danmercede.com/thoughts/2026-11-09-what-does-your-ai-mean-by-ready</link><guid isPermaLink="true">https://www.danmercede.com/thoughts/2026-11-09-what-does-your-ai-mean-by-ready</guid><pubDate>Mon, 09 Nov 2026 08:00:00 +0000</pubDate><description>A ready status cannot substitute for action-specific evidence, current permission and verification of delivery.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An operations lead sees “ready” beside an AI-generated weekly brief. The team expects delivery to follow. But the writer means the draft exists, the engineering team means its software passed tests, and the person responsible for sending means the edition has been approved. If the next person treats those statements as interchangeable, the team can send unfinished work or leave a deadline uncovered while the individual components keep reporting progress.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That is an illustrative team situation. The decision for the delivery owner is concrete: what action does this particular ready status permit, and which evidence supports it? Before you let one AI workflow hand work to another, settle that meaning with the person who consumes the status.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our own newsletter work exposed the distinction. We had a private article that passed text review but failed its cover&amp;#x27;s relevance review. Separately, software for a Hub release capability passed 726 tests. Those were useful results about different things. Neither result established that the next newsletter was approved, scheduled or published.&lt;/p&gt;&lt;h2 id=&quot;give-ready-a-consumer&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Give ready a consumer&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A readiness claim needs someone who knows what to do with it. A writer can finish a draft and hand it to an editor. An editor can accept that text for a particular edition. A publisher can submit the accepted package to a platform. A reader can finally receive what the team intended to send. Each handoff has a different consumer and a different next action.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For the operations lead in the briefing example, the practical problem is knowing which handoff has happened. A green writing task does not answer whether an editor has accepted the draft. An editor&amp;#x27;s acceptance does not tell the lead whether the platform retained a schedule. Without those distinctions, the lead has to reconstruct the workflow from chat messages just when the deadline is getting close.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I would start with one status that currently causes that reconstruction. Ask the person who acts on it to finish this sentence: when I receive this status, I am allowed to do this next. If the writer and recipient give different answers, you have found a handoff to clarify. You have not established which answer the system enforces yet.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The names can stay simple. A team might use draft_ready for work an editor can review, approved_to_send for the exact package a publisher can submit, and published_verified for a result someone has inspected on the public surface. Those are suggested names, not a description of an installed control. The useful part is making the promised action explicit.&lt;/p&gt;&lt;h2 id=&quot;what-our-separate-results-established&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What our separate results established&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In our private newsletter trial, the text and visual reviews answered separate questions. The text reviews accepted the article within that trial. The visual design review passed. The independent relevance review still rejected the cover because its retry-control scene did not communicate the article&amp;#x27;s distinction between inspection and starting work. Legible words and a recognizable badge had not settled that question.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The package therefore stayed unsealed, and the original result remained failed. The condition for a second private operation was not met. We retained that result rather than treating the other passing judgments as permission to publish the candidate. The failed visual judgment had a specific subject and consequence.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On another track, the Hub writer source passed its software checks, including the 726-test suite. That evidence supported a software claim about the tested source. It did not accept the article, qualify the publishing account or show that a newsletter existed in LinkedIn. We also had a verified Hub deployment from separate work. Its public revision proved that deployment, without proving a new newsletter release.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When we checked LinkedIn this Monday, the latest published edition was still the previous one. The native manager showed no scheduled article and no current edition among its saved drafts. The automated publishing route had remained held, and we had not completed an attended replacement. The release was uncovered. The cover gate had done its job; it had not completed the separate delivery obligation.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That is the limit I want to preserve in the lesson. We did not observe a platform losing an accepted schedule. We had distinct pieces of work with distinct evidence, and the remaining publication step had not happened. Calling the software or the private draft ready could not supply that missing event.&lt;/p&gt;&lt;h2 id=&quot;bind-the-claim-to-the-work&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Bind the claim to the work&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For an engineer, a status becomes more useful when it points to the exact work it describes. One implementation option is a small record naming the operation, the input fingerprint, the target, the proposed next action and the observation time. If the permission expires, that deadline belongs beside the claim. The fields help a consumer check identity and freshness; their presence alone does not make the evidence trustworthy.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Consider an editor who accepts a briefing and a writer who then changes its conclusion. The earlier acceptance belongs to the earlier text. A consumer that reads only the word approved can miss the change. A consumer that checks the accepted input fingerprint can refuse the mismatched handoff and ask for review of the new version. That refusal still needs to be implemented where the next action is admitted.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep evidence and permission distinct as well. A successful software test is evidence about the exercised behavior. An approval grants a particular action under its stated conditions. A platform&amp;#x27;s saved schedule is evidence about a retained submission. A public-reader check observes delivery. A team can record all four while refusing to let any one substitute for the others.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The control belongs at the point where work advances. An agent can propose that a package is ready, but the consumer should check the required evidence and current permission before it sends, merges or starts another operation. A sentence in the agent&amp;#x27;s instructions is not the same mechanism as a consuming path that refuses an unaccepted package. Check the path that actually performs the next action.&lt;/p&gt;&lt;h2 id=&quot;keep-unfinished-delivery-visible&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep unfinished delivery visible&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Accurate local states help engineering without relieving the delivery owner of the overall result. When a review rejects a candidate, the team still needs to know who owns the release, what remains unfinished and when to bring that exception to the owner. Otherwise the rejected step can stay correctly blocked while the deadline passes outside its scope.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A fallback needs its own permission. For the hypothetical briefing team, that might mean asking an authorized editor to finish a manual edition, or agreeing to miss the slot and tell the people waiting for it. It does not mean quietly lowering the visual bar or giving a diagnostic tool permission to send. A change in route should preserve the controls that matter to that route.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the exception attached to the original work. If a submission&amp;#x27;s outcome is unknown, inspect the existing submission before creating another. If no submission happened, say that plainly. Those are different recovery situations. Last week&amp;#x27;s edition addressed repeating work after missing confirmation; this week&amp;#x27;s question is what a readiness claim authorizes before the next person acts.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Verification should reach the person or system that needs the result. For a briefing, the team can check the public article&amp;#x27;s actual title, body, cover and response route after publication. That establishes the inspected delivery. It does not establish that readers found the article useful, generated a business conversation or improved a workflow. Those require their own observations.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The commercial question underneath this is familiar: who owns the AI workflow after the demonstration? Someone has to maintain the meaning of its handoffs, keep its permissions current and deal with rejected or uncertain results. The model can contribute work. The operating team still needs a clear account of which result permits which next action and who takes responsibility when the intended delivery is incomplete.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Which AI workflow in your operation has a “ready” status whose next permitted action is unclear? Describe the status and the action in the comments.&lt;/strong&gt;&lt;/p&gt;</content:encoded></item>
<item><title>Before Your AI Tries Again</title><link>https://www.danmercede.com/thoughts/2026-11-02-before-your-ai-tries-again</link><guid isPermaLink="true">https://www.danmercede.com/thoughts/2026-11-02-before-your-ai-tries-again</guid><pubDate>Mon, 02 Nov 2026 08:00:00 +0000</pubDate><description>A timeout after launch does not establish that an operation never ran; execution and result recovery require separate evidence.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When an AI-assisted workflow stops answering, your operations team still has a decision to make. Did the work stop, or did its confirmation disappear? If the next step updates a supplier record or sends a customer message, starting again can repeat an action the team is trying to finish. Those are illustrative workflows, and the operations lead who owns delivery must decide whether another attempt is allowed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before authorizing another attempt, ask what the original operation did and who is responsible for resolving an uncertain outcome. The person waiting for delivery needs that answer as much as the engineer operating the system. A timeout gives you a reason to investigate. By itself, it does not establish that the first attempt never ran.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I ran into this in my own operation while coordinating an AI review. Our caller stopped waiting, but the original review later finished. We recovered its result without asking the model to do the work again. The useful lesson was the separation between running an operation and finding out what happened to it.&lt;/p&gt;&lt;h2 id=&quot;give-the-uncertainty-an-owner&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Give the uncertainty an owner&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Choose one AI-assisted workflow where a repeat would matter. Name the person waiting for its result and the person allowed to decide what happens after a missing confirmation. They might be the same person. Make that responsibility explicit before the first ambiguous failure arrives.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For the supplier-record illustration, an operations lead might be waiting for a completed update while an engineer sees a request timeout. The engineer needs to establish whether the update reached the receiving system. The operations lead needs to know whether another attempt would repeat a change or simply retrieve its status. Neither question is answered by the caller&amp;#x27;s error alone.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Ask what the workflow can distinguish: an operation that never started, one still in progress, one with a retained result, and one whose outcome remains unknown. These are questions to investigate in the actual system, not labels to assign from a message on the screen. A missing result can remain unknown even after the worker has stopped.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Your team also needs a rule for that last condition. Decide who investigates, which evidence they can read, and when they should stop and escalate. Leaving uncertainty visible can be more useful than turning it into a confident failure and giving the next worker permission to start over.&lt;/p&gt;&lt;h2 id=&quot;what-happened-after-our-timeout&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What happened after our timeout&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;During an internal qualification on October 23, our coordination work sent a review to an AI worker. The caller waited for a receipt and timed out after 180 seconds. That established how long our caller waited. It did not establish that the native review had been cancelled or had never started.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The original operation later completed. We used a separate read-only lookup, bound to that operation and the digest, a fingerprint of its input text, to collect the retained result. The lookup did not initiate another inference. The original review&amp;#x27;s record still showed one dispatch attempt.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The surrounding stored records mattered. We retained the original intent and its completion context, and the worker&amp;#x27;s stored reply digest matched the digest of the reply delivered to our coordinator. The coordinator then checked the requested deliverable before closing the task. Recovering a reply and accepting the work were separate steps.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This was a bounded internal review task. It was not a customer update, and it did not measure duplicate charges or customer harm. It showed that a lost or late receipt could be recovered for this operation without repeating its inference. It did not establish a general delivery guarantee for every agent or failure.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We also kept the failed wait in the record. Replacing it with a clean success would erase the distinction that made the recovery worth inspecting: our first observation was incomplete, and the later evidence answered a question the timeout had left open.&lt;/p&gt;&lt;h2 id=&quot;recover-the-original-operation&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Recover the original operation&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An engineer needs an identity that survives the lost answer. Keep the original operation identifier with the intended input and the receiving system&amp;#x27;s reference, where one exists. If every recovery attempt invents a new operation, your team can lose the connection between the work that might already have happened and the work it is about to authorize.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In our implementation, result inspection is a separate path from execution. The inspection request identifies the original operation, supplies the input digest and explicitly requests read-only handling. The reader checks the stored identity and digest before returning the retained result. A conflict is refused; missing or unusable state remains &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;unknown&lt;/code&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That separation matters because a function called &amp;quot;check status&amp;quot; can still have side effects. Follow its consuming path. Does it only read retained evidence, or can it enter the worker again when a file is missing? In our path, inspection does not call the model. The reservation for an existing operation is preserved rather than deleted to make another attempt possible.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A digest answers a limited question about bytes. It helps bind a retained reply to the intended request; it does not establish that the reply is correct or that the requester has authority. The storage boundary and the identities your system trusts still matter. Our evidence assumes cooperating processes under the same operator, not protection from a hostile process with that operator&amp;#x27;s access.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The same limit applies to an idempotency key. Where a receiving service supports one, inspect its actual scope, retention and behavior for changed input. Reusing an identifier is useful only when the relevant execution path enforces the intended rule. An identifier written in a document cannot prevent duplicate effects at a service that ignores it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Some workflows already have an authorized retry contract that handles these cases. Use its documented boundary. The concern is an automatic repeat justified only by a timeout, with no account of the original attempt. More transport attempts and another business action are not necessarily the same thing.&lt;/p&gt;&lt;h2 id=&quot;a-result-still-needs-acceptance&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;A result still needs acceptance&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Finding a matching result closes one question. Your delivery owner still needs to know whether it satisfies the requested work. An AI can return a review that addresses the wrong material, misses a required check or stops short of the deliverable. Identity and content quality need different evidence.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If the workflow also changes an external system, inspect that effect separately. A retained model answer does not prove that a supplier update was applied or that a customer received a message. Conversely, the external effect may be present even when the caller has no final answer. Keep the intended result, observed effect and acceptance decision distinct.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In our review case, the coordinator checked the deliverable and correlated the returned evidence before recording completion. That responsibility did not move to the model because a reply arrived. The person accepting the work still owned the decision to close it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Your handoff should tell the next operator what is known, what remains uncertain and which action is permitted. Preserve the original failure and later readback together. A historical success is useful context, but the next operator must still check the current operation rather than borrow certainty from an earlier run.&lt;/p&gt;&lt;h2 id=&quot;make-the-next-attempt-a-decision&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Make the next attempt a decision&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Ask your engineer to walk through one safely retained case, or an already authorized harmless test, where the caller loses its confirmation after work starts. Trace the original operation to the receiving side and inspect what recovery actually does. This is an inspection aid, not permission to interrupt a live customer workflow.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then ask what happens when the evidence is unavailable. A recovery path should have a bounded wait and a named owner for escalation. If the first attempt&amp;#x27;s outcome cannot be resolved, keep that uncertainty in the decision. A human approval for another attempt does not prove the first one had no effect.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The owner may decide to reconcile the receiving system, wait for a late result, stop the workflow or authorize a further attempt under an understood duplicate risk. Engineering should make those choices operable, including any service-specific retry protections. The important change is that the next action follows the known state and authority, rather than the emotional pressure to make an error disappear.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I want an AI workflow&amp;#x27;s handoff to survive a missing answer. Someone should be able to identify the original attempt, inspect the evidence it left and explain who can authorize the next move. Recovering that account can be the work that finishes the workflow.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Which AI-assisted workflow in your operation needs the first attempt accounted for before it can run again? Describe that workflow in the comments.&lt;/p&gt;</content:encoded></item>
<item><title>Build a Supervisor Agent: Talk to One Session While the Rest Keep Moving</title><link>https://www.danmercede.com/guides/build-a-supervisor-agent</link><guid isPermaLink="true">https://www.danmercede.com/guides/build-a-supervisor-agent</guid><pubDate>Sat, 31 Oct 2026 07:00:00 +0000</pubDate><description>On 2026-10-31 one Claude Code session supervised four Codex threads and a second Claude Code session for a full day while I mostly made decisions. This guide shows how to build that supervisor from built-in messaging, plain files and a few small scripts, and the seven mistakes that became its rules.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If you run more than two or three coding agents on one project, you&amp;#x27;ve probably noticed where the time goes. One session finishes and needs a review, another is waiting on an answer only a third one has, and you&amp;#x27;re the one carrying messages between terminals. The agents are fast, and you&amp;#x27;re the queue.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;So I stopped being the queue. On 2026-10-31 I talked to one Claude Code session all day. It kept four Codex threads and a second Claude Code session moving, answered their questions, checked their handoffs, merged what passed its gates and brought me decisions: approve this cut, pick that name, choose where CI runs. I still carried a few messages by hand, every one a Codex question asked where the supervisor couldn&amp;#x27;t see it, and that gap became a rule too.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The whole thing is built from public pieces: Claude Code&amp;#x27;s cross-session messaging, Codex CLI&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;codex queue&lt;/code&gt;, a few plain text files and a few small scripts. There&amp;#x27;s no new service to run. This guide walks through each piece, with snippets written for this guide and tested before they went in, and then the mistakes from that day and the rule each one produced.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Who this is for:&lt;/strong&gt; developers already running several Claude Code and Codex sessions (or other coding agents) on one project, who want those sessions to keep moving while they&amp;#x27;re away and to talk to only one of them.&lt;/p&gt;&lt;h2 id=&quot;what-did-one-supervisor-session-do-on-2026-10-31&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What did one supervisor session do on 2026-10-31?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-31, from 8:30 AM to 8:30 PM Pacific, one Claude Code session supervised four Codex threads and one other Claude Code session on a documentary video pipeline. Across that day 24 pull requests merged in the project, and two documentary scripts went from draft to narration, each fact-checked by a session that didn&amp;#x27;t write it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The workers were a production thread, a thread polishing a third film, a build thread and a research thread, all in Codex, plus one Claude Code session that researched, narrated and assembled the second film. The supervisor and the writer subagents it launched wrote both scripts. The review bots on each pull request counted as workers too, since their findings had to be read, sorted and routed to the session that owned the code.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Some moments from the supervisor&amp;#x27;s running log, in Pacific time:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Time&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What happened&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;10:42 AM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Hosted CI stops starting jobs: the account hit its spending limit&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;11:50 AM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The supervisor brings up self-hosted runners, so jobs start again&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;3:45 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The second film&amp;#x27;s key-scene proof is verified, and its script writing starts&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;4:31 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The supervisor messages the other Claude session itself, instead of asking me to nudge it&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;4:58 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Two narration jobs need the same GPU, so the supervisor puts them in order&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;5:06 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The first narration finishes, and the GPU release is passed to the second job&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;6:11 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The supervisor finds and fixes a CI bug it had introduced that afternoon&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;6:46 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The second film&amp;#x27;s private review package is sealed and verified&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;8:17 to 8:27 PM&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;I set three standing rules for the supervisor and its workers&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The second film went from key-scene proof to a sealed review package in about three hours, and its script went through six drafts on the way.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My part was mostly decisions. Among them, I approved one film&amp;#x27;s latest cut, settled a naming question, chose which machine hosts CI, held one release decision until more data was in, gave review notes on the finished cut, and set the three rules. I also carried messages by hand a few times: I pasted two Codex questions into the supervisor and its two answers back, and once pressed Steer in all four Codex threads so a new rule landed right away. Every one of those traced back to a Codex thread asking where the supervisor couldn&amp;#x27;t see it, which is the gap the inbox rule closed. Two lines from the supervisor&amp;#x27;s log, with session names and IDs removed, show the kind of thing it recorded:&lt;/p&gt;&lt;blockquote class=&quot;my-5 border-l-2 border-copper-500/50 pl-5 text-slate-300&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;4:31 PM: CORRECTION: peer Claude sessions ARE messageable. SendMessage delivered the fact-check request with notify_when_idle. No Dan nudge needed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;8:18 PM: Dan rule: busy Codex reads log; idle Codex needs a queue push.&lt;/p&gt;&lt;/blockquote&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/supervisor-agent/supervisor-architecture.webp&quot; alt=&quot;The supervisor architecture. You, marked decisions only, talk to the supervisor session, which holds standing approvals, a decisions list and merge on green, and messages workers itself without relaying through you. The supervisor sends SendMessage to Claude Code sessions in both directions, with a one-shot notice when a turn ends, and sends a one-line pointer to Codex threads with codex queue, using Steer in the app when it can&amp;#x27;t wait. Every session reads and appends shared files: append-only workstream logs carrying a path and SHA-256 on every handoff, a supervisor inbox for workers&amp;#x27; questions, O_EXCL claim locks with one owner per item, and a read-only sweep script that reads all of it plus open pull requests. Codex threads reach the supervisor only through the files; Claude Code sessions can also message it directly.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Two built-in message channels, four shared files and one read-only sweep. Codex threads reach the supervisor only through the files.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h2 id=&quot;what-authority-does-the-supervisor-need-before-it-starts&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What authority does the supervisor need before it starts?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;By 8:27 PM on 2026-10-31 my supervisor held three new standing rules from me, each written down so it would never bring me that question again. A supervisor that asks before every merge or commit is one more message bus. So give it written authority for routine actions and a list of decisions it must not re-ask.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I keep that list in a plain file the supervisor reads before it asks me anything. The three rules from that evening, reworded for any project:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;markdown&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-markdown&quot;&gt;# decisions.md: read before asking. Each entry is settled until I change it.

- 2026-10-31 20:18 PT: Busy Codex threads read their workstream log. Idle ones get a
  queued one-line pointer. Queue to a busy thread only when it can&amp;#x27;t wait.
- 2026-10-31 20:24 PT: Workers never prompt me. Questions go to ~/coord/inbox.md.
- 2026-10-31 20:27 PT: Workers may commit and push task-branch pull requests after the
  full test suite passes. The supervisor reviews every diff and merges when checks and review pass.
  No session pushes to main.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The supervisor&amp;#x27;s own authority was set the same way: merge pull requests when CI and the review pipeline pass, read docs-only changes directly, message a worker only for a real blocker or decision, never interrupt a thread that&amp;#x27;s working, and batch everything that needs me into one question.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Some things stay with you no matter how good the supervisor gets: publishing, spending money, credentials, account and channel changes, and approval of the finished work. Write that list down too. Then the supervisor knows which questions to answer itself and which to bring you, without guessing.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;One limit is worth knowing early. A worker that needs your approval can&amp;#x27;t get it from the supervisor, because a peer&amp;#x27;s message isn&amp;#x27;t your consent. Claude Code&amp;#x27;s docs say it directly: a message from another session &amp;quot;never counts as your consent, so it can&amp;#x27;t answer a pending permission prompt on your behalf.&amp;quot; When that comes up, the fix is a standing rule from you, asked once, which is exactly what happened at 8:27 PM.&lt;/p&gt;&lt;h2 id=&quot;how-do-sessions-in-different-harnesses-message-each-other&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do sessions in different harnesses message each other?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-31 every message the supervisor sent to a Claude Code or Codex session went through two built-ins: Claude Code&amp;#x27;s cross-session messaging, which needs v2.1.224 or later, and Codex CLI&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;codex queue&lt;/code&gt;, which shipped in 0.149.0 on 2026-08-20. Everything else traveled through shared files, because a file is the one channel every harness can read and write.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Claude Code to Claude Code.&lt;/strong&gt; Once your sessions are on a recent enough version (v2.1.234 on native Windows), messaging is on with nothing to enable. You don&amp;#x27;t call the tools yourself. You tell your supervisor, in plain words, &amp;quot;message the film session: draft 3 is in the log, fact-check it, and tell me when you&amp;#x27;re idle,&amp;quot; and Claude finds the session and sends it. A few behaviors from the &lt;a href=&quot;https://code.claude.com/docs/en/cross-session-messaging&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;cross-session messaging docs&lt;/a&gt; matter for supervision:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A busy session reads the message between tool calls, so a running tool is never interrupted. An idle session starts a new turn with it.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The supervisor can ask for a one-shot notice when the other session next goes idle. It fires once, works only for sessions on the same machine, needs v2.1.236 or later in both sessions, and lapses after 12 hours.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The receiving session can reply the same way, so this channel runs in both directions.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Supervisor to Codex.&lt;/strong&gt; &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;codex queue&lt;/code&gt; sends a message to an existing Codex session by its UUID or exact name:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;codex queue --thread &amp;quot;$PRODUCTION_THREAD&amp;quot; \
  --message &amp;quot;New line in ~/coord/production.log.md at 17:45 UTC: draft 03 is ready for fact check. Read the log; no reply needed here.&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the message a pointer to the log, not the content. On 2026-10-31 a message queued to an idle thread started it right away, and a message queued to a busy thread waited until its turn ended. Codex&amp;#x27;s release notes say queued messages wake idle sessions, and its docs describe a message queued from the composer as waiting for the next run. The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;codex queue&lt;/code&gt; reference doesn&amp;#x27;t say how a busy thread handles one, but waiting for the turn to end is what I saw. When something truly can&amp;#x27;t wait, Codex&amp;#x27;s Steer adds a message to the turn that&amp;#x27;s running: press Enter while Codex is working in the CLI, or use Steer in the app.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Codex to the supervisor&lt;/strong&gt; goes through files. A Codex thread appends to its log or the inbox, and the supervisor&amp;#x27;s watcher wakes it. That asymmetry is the reason the logs exist.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/supervisor-agent/message-routing.webp&quot; alt=&quot;A two-by-two grid of how a message reaches a worker. A busy Claude Code session reads a SendMessage between tool calls, without interrupting a running tool. An idle Claude Code session starts a new turn when a SendMessage arrives, and the sender can ask for a one-shot notice when it goes idle. A busy Codex thread gets the news from its log, which it re-reads between steps, while a queued message waits for the turn to end. An idle Codex thread gets a queued pointer with codex queue, and Steer is only for urgent cases. Footnotes: the Claude Code rows come from its cross-session messaging docs, version 2.1.224 or later; the Codex busy row is what I observed on 2026-10-31, since the codex queue reference doesn&amp;#x27;t say when a busy thread receives one.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Log first. Push only when the worker is idle or the matter can&amp;#x27;t wait.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h2 id=&quot;why-does-every-workstream-need-an-append-only-log&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Why does every workstream need an append-only log?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;At 8:16 PM on 2026-10-31 I asked about the messages in a busy Codex thread&amp;#x27;s queue. All four the supervisor had sent were stale, because the work they announced had already moved on. A log reaches a busy session in any harness and keeps the history a message loses. An idle Codex thread still needs a push to read it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;So each workstream gets one log file, and every session on it, in any harness, appends to it. The rules are short:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Append only. Never edit an earlier line, so the log is a record, not a draft.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;One line per entry: a UTC timestamp, who wrote it, what happened, and what&amp;#x27;s next.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Every handoff names a path and its SHA-256, so the next session can prove it has the exact file the last one meant.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Tell busy workers to re-read their log between steps. That&amp;#x27;s how a working Codex thread picks up news mid-turn.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A few shell helpers make the format hard to get wrong. Every session sources the same file, and all the shared files live in one folder outside any checkout, so every worktree and every harness sees the same copy:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;# coord.sh: source this in every session&amp;#x27;s shell. One line per append, UTC stamps.
# The folder sits outside any checkout, so every worktree and harness sees the same files.
COORD=&amp;quot;${COORD:-$HOME/coord}&amp;quot;; mkdir -p &amp;quot;$COORD&amp;quot;
stamp() { date -u &amp;#x27;+%Y-%m-%d %H:%M UTC&amp;#x27;; }
sha() { { sha256sum &amp;quot;$1&amp;quot; 2&amp;gt;/dev/null || shasum -a 256 &amp;quot;$1&amp;quot;; } | cut -c1-64; }

# log WORKSTREAM WHO TEXT: append a line to that workstream&amp;#x27;s log
log() { printf -- &amp;#x27;- %s %s: %s\n&amp;#x27; &amp;quot;$(stamp)&amp;quot; &amp;quot;$2&amp;quot; &amp;quot;$3&amp;quot; &amp;gt;&amp;gt; &amp;quot;$COORD/$1.log.md&amp;quot;; }

# ask WHO QUESTION NEEDS BLOCKING: put a question in the supervisor inbox, print its ID
ask() {
  local id=&amp;quot;$1-$(date -u &amp;#x27;+%H%M%S&amp;#x27;)-$RANDOM&amp;quot;
  printf -- &amp;#x27;- %s %s: ASK [%s]: %s Needs: %s. Blocking: %s.\n&amp;#x27; &amp;quot;$(stamp)&amp;quot; &amp;quot;$1&amp;quot; &amp;quot;$id&amp;quot; &amp;quot;$2&amp;quot; &amp;quot;$3&amp;quot; &amp;quot;$4&amp;quot; &amp;gt;&amp;gt; &amp;quot;$COORD/inbox.md&amp;quot;
  echo &amp;quot;$id&amp;quot;
}

# receipt FILE: the path and SHA-256 every handoff carries
receipt() { printf &amp;#x27;%s sha256 %s&amp;#x27; &amp;quot;$1&amp;quot; &amp;quot;$(sha &amp;quot;$1&amp;quot;)&amp;quot;; }&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A handoff line then looks like this:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;- 2026-11-02 17:45 UTC writer: Draft 03 ready for fact check: ~/coord/script-03.json sha256 2da6d7ac8575...d87d. Gate: PASS. Next owner: checker.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;After that evening the supervisor&amp;#x27;s rule became log first, and queue a pointer only when the thread is idle or the matter can&amp;#x27;t wait.&lt;/p&gt;&lt;h2 id=&quot;how-do-workers-ask-questions-without-interrupting-you&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do workers ask questions without interrupting you?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-31 I pasted two Codex questions into the supervisor by hand, because each thread had asked in its own prompt box, where the supervisor couldn&amp;#x27;t see it. At 8:24 PM I made it a rule: workers never prompt me. Every question goes into one append-only inbox file, and the worker keeps working.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An inbox line carries five things: who&amp;#x27;s asking, a unique ID, the question, what the answer needs (a path or a receipt), and whether the worker is blocked. The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ask&lt;/code&gt; helper above writes it:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;- 2026-11-02 17:50 UTC build-round: ASK [build-round-175012-4821]: May I take over the stalled caption PR? Its owner has been idle 14 hours. Needs: ~/coord/handoffs/captions/RECEIPT.txt. Blocking: no.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The supervisor answers with a message to the worker and an answer line that repeats the ask&amp;#x27;s ID, so the sweep can tell which asks are still open:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;- 2026-11-02 17:57 UTC supervisor: ANSWER [build-round-175012-4821]: yes, receipt verified, take it.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Most asks never reach you. A worker asking which branch to rebase onto, whether a review finding is real, or whether a receipt checks out gets its answer from the supervisor. The asks only you can answer, like publishing, spend or creative approval, the supervisor holds and batches into one structured question, so you make five decisions in one sitting instead of being pinged five times.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When I set the rule, the supervisor queued it to all four Codex threads, I pressed Steer so they would read it right away, and the supervisor messaged the other Claude session, which already messaged it directly. In the next 52 minutes five questions came in through the inbox from three Codex threads, and the supervisor answered the first three within two minutes each.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-stop-two-sessions-from-doing-the-same-work&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you stop two sessions from doing the same work?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;At 7:57 PM on 2026-10-31 the supervisor handed a stalled pull request to the build thread, after checking that its previous owner had been idle for more than 14 hours. The receipt held the SHA-256 of the staged patch, so uncommitted work survived the move. A handoff like that only works if ownership is exclusive first.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The simplest exclusive claim is a lock file the operating system creates only when it doesn&amp;#x27;t already exist:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;#!/usr/bin/env python3
&amp;quot;&amp;quot;&amp;quot;claim.py ITEM HOLDER: take exclusive ownership of one work item, or refuse.&amp;quot;&amp;quot;&amp;quot;
import json, os, sys, time

COORD = os.environ.get(&amp;quot;COORD&amp;quot;, os.path.expanduser(&amp;quot;~/coord&amp;quot;))

def claim(item: str, holder: str) -&amp;gt; bool:
    root = os.path.join(COORD, &amp;quot;claims&amp;quot;)
    os.makedirs(root, exist_ok=True)
    path = os.path.join(root, f&amp;quot;{item}.lock&amp;quot;)
    try:
        # O_CREAT | O_EXCL: the OS creates the file only if it does not exist yet,
        # so two sessions racing for the same item cannot both succeed.
        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
    except FileExistsError:
        with open(path, encoding=&amp;quot;utf-8&amp;quot;) as fh:
            print(f&amp;quot;HELD {item}: {fh.read().strip() or &amp;#x27;(being written)&amp;#x27;}&amp;quot;, file=sys.stderr)
        return False
    with os.fdopen(fd, &amp;quot;w&amp;quot;, encoding=&amp;quot;utf-8&amp;quot;) as fh:
        json.dump({&amp;quot;holder&amp;quot;: holder, &amp;quot;since&amp;quot;: time.strftime(&amp;quot;%Y-%m-%dT%H:%M:%SZ&amp;quot;, time.gmtime())}, fh)
    return True

if __name__ == &amp;quot;__main__&amp;quot;:
    sys.exit(0 if claim(sys.argv[1], sys.argv[2]) else 1)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When I started 20 claimers for the same item at once, one exited 0 and 19 exited 1 with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;HELD&lt;/code&gt;. A session that gets &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;HELD&lt;/code&gt; stands down, or writes an ask in the inbox, and never works around the lock.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A lock records who claimed the item, not whether they&amp;#x27;re still working. Before the supervisor reassigned that pull request, it checked the owner&amp;#x27;s last activity and found no reviews in flight. Then it wrote the handoff as files the next owner can verify:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;H=&amp;quot;$COORD/handoffs/captions&amp;quot;; mkdir -p &amp;quot;$H&amp;quot;
git diff --cached --binary &amp;gt; &amp;quot;$H/staged.patch&amp;quot;
git status --short         &amp;gt; &amp;quot;$H/status.txt&amp;quot;
(cd &amp;quot;$H&amp;quot; &amp;amp;&amp;amp; sha256sum staged.patch &amp;gt; RECEIPT.txt)    # macOS: shasum -a 256

# The new owner, in its own checkout, after sourcing coord.sh:
H=&amp;quot;$COORD/handoffs/captions&amp;quot;
(cd &amp;quot;$H&amp;quot; &amp;amp;&amp;amp; sha256sum -c RECEIPT.txt) &amp;amp;&amp;amp; git apply --index &amp;quot;$H/staged.patch&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If you want claims with generations, task revisions and safe hand-back, the &lt;a href=&quot;https://www.danmercede.com/guides/coordinate-local-agents-with-orion-pm&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion PM guide&lt;/a&gt; covers a fuller version of the same idea.&lt;/p&gt;&lt;h2 id=&quot;how-does-the-supervisor-see-everything-without-asking-anyone&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How does the supervisor see everything without asking anyone?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-31 my supervisor ran its sweep 17 times between 8:15 AM and 8:32 PM, usually right before deciding what to do next. A sweep is one read-only script that prints each workstream&amp;#x27;s newest log lines and quiet time, the unanswered asks and the open pull requests, so the supervisor sees everything without sending a message.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A skeleton you can adapt:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;#!/usr/bin/env python3
&amp;quot;&amp;quot;&amp;quot;sweep.py: one read-only screen of every workstream. It sends no messages.&amp;quot;&amp;quot;&amp;quot;
import glob, json, os, re, subprocess, time

COORD = os.environ.get(&amp;quot;COORD&amp;quot;, os.path.expanduser(&amp;quot;~/coord&amp;quot;))
now = time.time()

print(&amp;quot;== Workstreams (minutes since the last log line)&amp;quot;)
for path in sorted(glob.glob(f&amp;quot;{COORD}/*.log.md&amp;quot;)):
    lines = [l.rstrip() for l in open(path, encoding=&amp;quot;utf-8&amp;quot;) if l.strip()]
    quiet = int((now - os.path.getmtime(path)) / 60)
    print(f&amp;quot;{quiet:&amp;gt;5}m  {os.path.basename(path)}{&amp;#x27;  QUIET&amp;#x27; if quiet &amp;gt;= 45 else &amp;#x27;&amp;#x27;}&amp;quot;)
    for line in lines[-2:]:
        print(f&amp;quot;         {line[:150]}&amp;quot;)

print(&amp;quot;\n== Unanswered asks&amp;quot;)
asks, answered = {}, set()
for line in open(f&amp;quot;{COORD}/inbox.md&amp;quot;, encoding=&amp;quot;utf-8&amp;quot;):
    if m := re.match(r&amp;quot;- \S+ \S+ UTC (\S+): ASK \[([^\]]+)\]: (.*)&amp;quot;, line):
        asks[m[2]] = f&amp;quot;{m[1]}: {m[3]}&amp;quot;
    if m := re.match(r&amp;quot;- \S+ \S+ UTC supervisor: ANSWER \[([^\]]+)\]&amp;quot;, line):
        answered.add(m[1])
for key, text in asks.items():
    if key not in answered:
        print(f&amp;quot;  {&amp;#x27;BLOCKING &amp;#x27; if &amp;#x27;Blocking: yes&amp;#x27; in text else &amp;#x27;&amp;#x27;}{key}: {text[:120]}&amp;quot;)

print(&amp;quot;\n== Open pull requests&amp;quot;)
out = subprocess.run([&amp;quot;gh&amp;quot;, &amp;quot;pr&amp;quot;, &amp;quot;list&amp;quot;, &amp;quot;--json&amp;quot;, &amp;quot;number,title,isDraft,mergeStateStatus&amp;quot;],
                     capture_output=True, text=True).stdout or &amp;quot;[]&amp;quot;
for pr in json.loads(out):
    state = &amp;quot;draft&amp;quot; if pr[&amp;quot;isDraft&amp;quot;] else pr[&amp;quot;mergeStateStatus&amp;quot;].lower()
    print(f&amp;quot;  #{pr[&amp;#x27;number&amp;#x27;]:&amp;lt;4} {state:&amp;lt;9} {pr[&amp;#x27;title&amp;#x27;][:70]}&amp;quot;)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Quiet time in this skeleton comes from the log, so it works the same for every harness. My own sweep takes Codex quiet time from each session&amp;#x27;s local transcript instead, and doesn&amp;#x27;t read the inbox yet. That transcript layout isn&amp;#x27;t documented, so if you copy the idea, treat it as a convenience that can break on an update, and keep the log as the source of truth.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The sweep decides what the supervisor does next, and most of the time the answer is nothing. A &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;QUIET&lt;/code&gt; flag on a thread that&amp;#x27;s mid-render is fine. A &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BLOCKING&lt;/code&gt; ask or a pull request with failing checks is where it acts.&lt;/p&gt;&lt;h2 id=&quot;how-does-the-supervisor-wait-without-polling&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How does the supervisor wait without polling?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Between 3:33 PM and 4:58 PM on 2026-10-31 my supervisor armed a fresh file watcher 12 times, a new one each time a handoff it was waiting on landed. A watcher is a small background command that exits the moment a log or the inbox grows, so the supervisor reacts to the change instead of asking &amp;quot;are you done?&amp;quot;&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;#!/usr/bin/env bash
# wait-grow.sh FILE...: exit as soon as any file grows, and show its new tail.
# Run it as a background command; its exit is the wake-up.
files=(&amp;quot;$@&amp;quot;); sizes=()
for f in &amp;quot;${files[@]}&amp;quot;; do [ -e &amp;quot;$f&amp;quot; ] || : &amp;gt; &amp;quot;$f&amp;quot;; sizes+=(&amp;quot;$(wc -c &amp;lt; &amp;quot;$f&amp;quot;)&amp;quot;); done  # never touch: the sweep reads mtime
while sleep 15; do
  for i in &amp;quot;${!files[@]}&amp;quot;; do
    if [ &amp;quot;$(wc -c &amp;lt; &amp;quot;${files[$i]}&amp;quot;)&amp;quot; -gt &amp;quot;${sizes[$i]}&amp;quot; ]; then
      echo &amp;quot;grew: ${files[$i]}&amp;quot;; tail -n 3 &amp;quot;${files[$i]}&amp;quot;; exit 0
    fi
  done
done&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Ask your supervisor to run it in the background over the files it&amp;#x27;s waiting on, for example &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;wait-grow.sh ~/coord/inbox.md ~/coord/production.log.md&lt;/code&gt;. When the command exits, Claude Code delivers the background task&amp;#x27;s result to the session, and the supervisor reads the new lines and acts. Then it arms the next one.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Claude Code has other wait primitives, and each fits a different job:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The idle notice&lt;/strong&gt; from cross-session messaging, for &amp;quot;tell me when the film session finishes this turn.&amp;quot;&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The &lt;a href=&quot;https://code.claude.com/docs/en/tools-reference&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Monitor tool&lt;/a&gt;&lt;/strong&gt;, which streams events from a running command and has Claude interject when one arrives, for watching a long build or render.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;&lt;a href=&quot;https://code.claude.com/docs/en/scheduled-tasks&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Scheduled tasks&lt;/a&gt;&lt;/strong&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/loop&lt;/code&gt;, for fixed-time checks like a 9:00 AM publish or the hourly sweep.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The rule is the same for all of them: wait on an event, and don&amp;#x27;t poll a session with messages. A &amp;quot;how&amp;#x27;s it going?&amp;quot; to a busy Codex thread just joins its queue and goes stale there.&lt;/p&gt;&lt;h2 id=&quot;why-should-the-supervisor-verify-instead-of-trusting-reports&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Why should the supervisor verify instead of trusting reports?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-31 a fact check scored a script&amp;#x27;s style at about 3.9, under the project&amp;#x27;s limit of 4, by joining its paragraphs with single spaces. The project&amp;#x27;s own check joins them with blank lines, and on that input the same script scored about 8.2. The recheck found it a draft later. Measure with the enforcing code, on the enforcing input.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Four habits do most of the work:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Path and SHA-256 on every handoff.&lt;/strong&gt; &amp;quot;Draft 3 is ready&amp;quot; is a claim. &amp;quot;~/coord/script-03.json sha256 2da6...d87d&amp;quot; is something the next session can check.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Re-measure with the code that enforces the rule.&lt;/strong&gt; Call the project&amp;#x27;s own function on the same input it will see in production. A count from your own reimplementation is a different measurement.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The writer never checks its own work.&lt;/strong&gt; On 2026-10-31 the supervisor&amp;#x27;s writers wrote both scripts, the production thread checked the first film&amp;#x27;s, and the second Claude session checked the second film&amp;#x27;s.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;One gate that runs every rule before any handoff.&lt;/strong&gt; That afternoon and evening three slips got past the checks in place: the style score above, two chapter-ending questions that the supervisor&amp;#x27;s own voice edit had turned into statements, and an opening question missing a word from the stakes list the production gate looks for. Each was found later, by a different session, after it had already cost a round trip. The first two led the supervisor to write one gate script, and the third got past that script&amp;#x27;s first version, so the gate gained a rule for it.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The gate is a short script that runs every check, keeps going after a failure, and prints the receipt:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;#!/usr/bin/env python3
&amp;quot;&amp;quot;&amp;quot;gate.py DRAFT: run every check before a handoff. Exit 0 only when all of them pass.&amp;quot;&amp;quot;&amp;quot;
import hashlib, subprocess, sys

draft = sys.argv[1]
# Each entry calls the project&amp;#x27;s own enforcing check, never a copy of it.
CHECKS = [
    (&amp;quot;style score&amp;quot;,      [&amp;quot;python3&amp;quot;, &amp;quot;-m&amp;quot;, &amp;quot;checks.style&amp;quot;, draft]),
    (&amp;quot;chapter endings&amp;quot;,  [&amp;quot;python3&amp;quot;, &amp;quot;-m&amp;quot;, &amp;quot;checks.endings&amp;quot;, draft]),
    (&amp;quot;required quotes&amp;quot;,  [&amp;quot;python3&amp;quot;, &amp;quot;-m&amp;quot;, &amp;quot;checks.quotes&amp;quot;, draft]),
    (&amp;quot;opening question&amp;quot;, [&amp;quot;python3&amp;quot;, &amp;quot;-m&amp;quot;, &amp;quot;checks.hook&amp;quot;, draft]),
]
failed = []
for name, cmd in CHECKS:  # run them all, so one failure cannot hide another
    ok = subprocess.run(cmd).returncode == 0
    print(f&amp;quot;{&amp;#x27;PASS&amp;#x27; if ok else &amp;#x27;FAIL&amp;#x27;}  {name}&amp;quot;)
    if not ok:
        failed.append(name)
digest = hashlib.sha256(open(draft, &amp;quot;rb&amp;quot;).read()).hexdigest()
print(f&amp;quot;{draft} sha256 {digest}&amp;quot;)
print(&amp;quot;RESULT:&amp;quot;, &amp;quot;PASS&amp;quot; if not failed else &amp;quot;FAIL &amp;quot; + &amp;quot;, &amp;quot;.join(failed))
sys.exit(1 if failed else 0)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before you trust a new gate, run it on a draft you know is bad. Mine failed the older drafts that had slipped through and passed their fixed versions, so I knew it could tell them apart.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/supervisor-agent/handoff-gate.webp&quot; alt=&quot;The handoff pipeline. A writer session drafts the work and runs gate.py, which runs every rule and exits 0 only if all pass. On a pass, the writer appends a log line with the path and SHA-256, and a checker session, a different session, re-measures with the real code before the next stage: narrate, build or merge. A gate failure loops back to the writer to fix and rerun the whole gate, and the checker&amp;#x27;s corrections loop back as a new draft with a new SHA-256. A footnote: on 2026-10-31 three slips got past the checks in place, and each was found later by a different session: a style score measured on the wrong paragraph join, two chapter questions edited into statements, and an opening question with no stakes word. The gate grew a rule for each.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;The writer never checks its own work, and no check runs alone.&lt;/figcaption&gt;&lt;/figure&gt;&lt;h2 id=&quot;what-went-wrong-and-which-rule-fixed-it&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What went wrong, and which rule fixed it?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The 2026-10-31 run produced seven mistakes worth keeping, and each became a standing rule. Most trace back to the supervisor itself: it queued messages a busy thread couldn&amp;#x27;t read yet, asked me to nudge a session it could message, shipped a CI hook that failed a job, and merged a stacked pull request into the wrong branch.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What went wrong&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;The rule it produced&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Four messages queued to a busy Codex thread were stale before it read them&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Log first. Queue a pointer only when the thread is idle or the matter can&amp;#x27;t wait&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;At 4:17 PM the supervisor said I needed to nudge the other Claude session&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The supervisor messages sessions itself. You never relay&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Three slips got past the checks in place, each a different rule&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;One gate runs every rule before any handoff&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Two narration jobs could have started on one GPU at the same moment&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Put the jobs in an explicit order, and pass a release message between them&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A worker needed commit approval, and a peer can&amp;#x27;t grant yours&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Ask the human once, for a standing rule&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The supervisor&amp;#x27;s own CI hook failed a job&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Find it in the job log, reproduce it, fix it, write it up&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A stacked pull request merged into its parent branch, not main&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The merge script skips any pull request whose base isn&amp;#x27;t main&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The nudge.&lt;/strong&gt; At 4:17 PM the second Claude session had been idle for half an hour, with a fact-check request waiting in its log, and the supervisor logged that I&amp;#x27;d need to nudge it. Thirteen minutes later I asked whether I really had to. It checked, found that peer Claude sessions are messageable, and sent the request itself with an idle notice attached. If your supervisor ever tells you to go poke a session, ask it whether it can message that session itself, and then put the answer in its instructions.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The GPU.&lt;/strong&gt; By late afternoon both films were ready to narrate, on one GPU that a 3D render and a review model loaded by the supervisor&amp;#x27;s own review runs were already sharing. Each narration job had its own watcher waiting for free memory, so both could have seen the GPU free up at the same instant and started together. The supervisor set the order (the second film first, then the rest of the first film&amp;#x27;s chapters), held its own review runs, and asked the second Claude session to log a release line when its job finished. At 5:06 PM that line arrived and the supervisor passed the GPU on.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The commit approval.&lt;/strong&gt; At about 8:27 PM the second Claude session said it would stop before committing its next fix. Its rules said to show me a diff and wait for my explicit approval, and it wrote back that a peer request couldn&amp;#x27;t stand in for that approval. It was right. The supervisor asked me one question, whether to approve its next two changes or set a standing rule, and I picked the standing rule. It recorded my exact answer in the decisions file and passed it on word for word.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The CI hook.&lt;/strong&gt; That afternoon the supervisor had added a job-started hook to the self-hosted runners, to clean up a temp file a secret scanner kept leaving behind. GitHub runs Bash hooks with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;-e&lt;/code&gt;, and a non-zero exit fails the job before it starts. That evening a job failed because the hook&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;find&lt;/code&gt; hit an item it couldn&amp;#x27;t delete. By 6:11 PM the supervisor had read the job log, reproduced exit 1 with the old hook under &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;bash -e&lt;/code&gt; and exit 0 with the fixed one, and added a section to the runner runbook.&lt;/p&gt;&lt;h2 id=&quot;where-should-you-start&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Where should you start?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with the pieces my 2026-10-31 run leaned on most, in this order: a decisions file, one log per workstream, the inbox, the sweep, then claims and the gate. The first three are plain text files that take minutes. The last three are small scripts, and each replaces a question you&amp;#x27;d otherwise answer by hand.&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Write &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;decisions.md&lt;/code&gt;&lt;/strong&gt; with your standing approvals and the list of things that always come to you.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Create one log per workstream&lt;/strong&gt; and tell every session to append to it, re-read it between steps, and put a path and SHA-256 on every handoff.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Create &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/coord/inbox.md&lt;/code&gt;&lt;/strong&gt; and tell every worker, in every harness, that questions go there and never to you.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Run the sweep&lt;/strong&gt; before you message anyone, and let the supervisor run it on a schedule.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Add claims&lt;/strong&gt; when two sessions could reach for the same work, and &lt;strong class=&quot;font-semibold text-white&quot;&gt;add the gate&lt;/strong&gt; the first time a handoff comes back with a problem a script could have found.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then open one session and tell it it&amp;#x27;s the supervisor: it owns coordination, it reads the decisions file before asking you anything, and it messages workers itself.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;One step is still manual. When a Codex thread asks in its own prompt box instead of the inbox, the supervisor can&amp;#x27;t see the question until someone carries it over. The inbox rule moved the questions to where the supervisor can see them, and closing that gap for good is what I&amp;#x27;m building next.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run this for a day and the change shows up in what reaches you. Apart from those few relays, what reached me on 2026-10-31 was decisions, and the sessions kept working between them. Talk to one agent, and make it earn that trust by checking everything it&amp;#x27;s handed.&lt;/p&gt;</content:encoded></item>
<item><title>Who Gets to Interrupt Your AI Work?</title><link>https://www.danmercede.com/thoughts/2026-10-26-who-gets-to-interrupt-your-ai-work</link><guid isPermaLink="true">https://www.danmercede.com/thoughts/2026-10-26-who-gets-to-interrupt-your-ai-work</guid><pubDate>Mon, 26 Oct 2026 07:00:00 +0000</pubDate><description>A cooperative shared-resource lock coordinates only participating callers; an idle observation does not reserve capacity for a workflow.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If your operations lead promises an AI-assisted job will finish before the next handoff, someone has to own the capacity it needs. A scheduled report, an automated review and a maintenance check can each have permission to run while competing for the same resource. When they overlap, the person waiting for delivery inherits the interruption.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before promising that window, ask who can allow another job into it and who takes responsibility when the work stops. That is a decision the workflow owner can make with engineering. It belongs beside the delivery commitment.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I ran into this in my own AI experiments. A shared lock was held, and a background audit still reached the model. The observed consequence was interrupted internal work and an incomplete experiment. Customer delay is a possible consequence in other workflows, not a measured outcome from this case.&lt;/p&gt;&lt;h2 id=&quot;name-the-work-that-needs-the-window&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Name the work that needs the window&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Choose one workflow where interruption matters. Say who is waiting for its result, what resource it shares, and when the result is needed. You can do that before discussing the scheduler or the model server.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For example, suppose an operations team uses AI to prepare a supplier review before a human approves the next step. That is an illustration. The delivery owner needs to know whether routine document processing can take the same capacity during that review, and whether the review can safely wait if something more urgent arrives.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then ask the engineer responsible for the workflow to describe the intended arrangement: who owns the window, which other callers it covers, what is allowed to interrupt it, and who handles stopping and restoration. A caller includes a background job or a person&amp;#x27;s manual command, as well as another agent.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That description gives you something concrete to discuss. It still needs evidence from the paths that actually use the resource. A calendar entry records an agreement; the running system determines whether another job can get through. Keep the promised arrangement and its observed enforcement visible together.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;You may decide the work can share capacity and tolerate delay. Or you may decide a particular window needs protection. Either decision is clearer when the delivery owner and the resource owner agree on what an interruption means.&lt;/p&gt;&lt;h2 id=&quot;what-our-lock-actually-covered&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What our lock actually covered&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On October 19, an AI experiment in my operation was running against a shared GPU. The runner held the existing shared lock. The acquisition used &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;flock&lt;/code&gt;, a file-locking mechanism that lets cooperating processes coordinate access to the same resource.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An hourly audit reached the model service through another path. Its smoke check requested a different model, and its later summarization used the expected model. The audit did not acquire the experiment&amp;#x27;s lock. Native caller records and the surrounding server logs established the competing request and the model change.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The experiment&amp;#x27;s guard detected the foreign connection and stopped our runner. The expected model was restored by the audit&amp;#x27;s later summarization. That final state did not mean the model had remained undisturbed throughout the run. The qualification stayed incomplete, so it supplied no comparative quality or economic result.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The lock had a limited scope. It coordinated processes that used it. A caller making a direct request to the model API could enter without asking for that lock. The missing boundary was between the participating callers and the other routes to the same resource.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A separately approved later window temporarily paused that hourly audit, with pause and restoration verified. During that window, a new review producer appeared and the guard stopped our trial again. This time no foreign inference connection was observed at the stop. It was a preventive stop for a potential caller, and the experiment still remained incomplete.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Those two stops need different descriptions. The first had an observed competing call. The second showed that pausing the audit had left another potential producer outside the arrangement. Treating both as demonstrated collisions would overstate the evidence, while treating the audit pause as complete protection would overstate the remedy.&lt;/p&gt;&lt;h2 id=&quot;check-every-route-that-can-reach-the-resource&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Check every route that can reach the resource&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An engineer investigating this needs to follow the callers. If one worker obtains a file lock and another sends requests directly to an API, the first worker&amp;#x27;s lock does not make the API reject the second. The same problem can appear when one queue enforces a limit while a maintenance script bypasses that queue.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Ask where admission happens. A common dispatcher can apply an agreed rule to the callers that pass through it. A lock can coordinate participants that acquire the same lock. A process with a separate entry path needs to be included, restricted or explicitly accepted as an exception. Naming the resource alone does not identify that boundary.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then ask what remains outside the rule. A scheduler may cover ordinary jobs while a manual command can still enter. A reservation may cover one account while another account uses the same service. These are questions about the actual paths in your system; they need inspection rather than an assumption that one control covers them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;You do not need to route every kind of work through one mechanism. You do need an accurate statement of which work the chosen arrangement coordinates. That lets the workflow owner decide whether the remaining interruptions are acceptable before promising a completion time.&lt;/p&gt;&lt;h2 id=&quot;decide-how-a-protected-job-gives-way&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Decide how a protected job gives way&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Protection also needs an interruption rule. An urgent operational check may deserve priority over an experiment. The person authorizing that priority should know which work will stop, what happens to its partial result, and who is responsible for resuming it. A request being more urgent does not make its consequences disappear.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep observation and reservation separate. A quiet machine tells you about the observation interval. It does not tell you whether another owner will launch work a moment later. A protected future window needs an arrangement with those callers and evidence that the relevant entry paths honor it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a bounded workflow, a refusal to start can be the right result. During execution, a guard may instead stop the job when an unexpected caller appears. Record whether the guard saw actual competing use or stopped on a precautionary condition. The operator needs that distinction to decide what to investigate next.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An interrupted run also leaves an accounting question. Preserve the work completed, the result still missing and any usage that remains unknown. A clean stop does not establish a completed task or a complete bill. Decide whether another attempt is warranted only after understanding what the first one did.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If protection requires temporarily holding another team&amp;#x27;s job, its owner must authorize that hold and its restoration. Name who checks the restored state and what evidence they will retain. A workflow can finish while its temporary controls leave someone else&amp;#x27;s operation waiting; restoration is part of the responsibility you are assigning.&lt;/p&gt;&lt;h2 id=&quot;make-the-commitment-small-enough-to-inspect&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Make the commitment small enough to inspect&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with one shared dependency and one delivery window. Ask for a view of the relevant callers, the intended priority and the behavior when a caller arrives outside that arrangement. Inspect retained evidence or an already authorized, harmless test. This is an inspection aid, not permission to disrupt a live workload.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For the supplier-review illustration, the question is whether the review can depend on the agreed capacity until its handoff, including the jobs that might enter from elsewhere. A person still owns accepting the supplier decision. Resource coordination does not establish that the AI&amp;#x27;s review is correct or that the next action is authorized.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The useful outcome is a narrower delivery promise that someone can operate: the covered work, the interruption decision, the state left after a stop and the owner of the next move. Any uncovered path remains a limitation to discuss. Writing those details down does not prove the system enforces them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When I hand an AI workflow to another person, I want them to know what can interrupt it and who resolves that interruption. That makes the dependency part of the handoff, instead of leaving the next operator to discover it while someone waits for the result.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Which AI workflow in your operation needs a protected window, and what else can use the same capacity? Describe that workflow in the comments.&lt;/p&gt;</content:encoded></item>
<item><title>Claude Code Cache Usage: What 471 Sessions Reveal About Token Cost</title><link>https://www.danmercede.com/guides/where-claude-code-usage-goes</link><guid isPermaLink="true">https://www.danmercede.com/guides/where-claude-code-usage-goes</guid><pubDate>Fri, 23 Oct 2026 07:00:00 +0000</pubDate><description>Measure Claude Code cache reads, cache writes, and subagent usage. A 471-session case study, a local Python counter, and the limits of API-price estimates.</description><content:encoded>&lt;h2 id=&quot;what-should-you-measure-first&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What should you measure first?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Separate uncached input, cache writes by lifetime, cache reads, and output. Deduplicate streamed and replayed requests before adding them up. Then compare token share with API list-price share. Use Claude Code&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/usage&lt;/code&gt; view for your plan&amp;#x27;s limits; a local token-price estimate does not reconstruct subscription billing.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For example, at the Opus 5.5 rates used here, reading 500,000 cached tokens costs $0.10; writing the same prefix into a one-hour cache costs $4.00. That is a price calculation, not a measurement of how many subscription credits either action consumes. &lt;a href=&quot;https://platform.claude.com/docs/en/about-claude/pricing&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Anthropic&amp;#x27;s pricing&lt;/a&gt; and &lt;a href=&quot;https://code.claude.com/docs/en/costs#using-the-usage-command&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Claude Code&amp;#x27;s usage documentation&lt;/a&gt; describe the two views.&lt;/p&gt;&lt;h2 id=&quot;scope-and-evidence&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Scope and evidence&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What this analysis covers&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Evidence and limit&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Measurement window&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Seven-day lookback run on October 23, 2026. The exact cutoff timestamp and timezone were not published.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;What was counted&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Local transcript analysis reported 471 sessions, 21,449 API calls, and 6.15 billion tokens, including subagents. These are the original author&amp;#x27;s measurements, not a new November sample.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Software observed&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Claude Code 2.1.301 through 2.1.305. Cache lifetimes below describe those logs, not a promise about every version or provider.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Price basis&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Each supported model&amp;#x27;s token buckets, using the dated rate table below. Approximately $2,500 is API list-price value, not an invoice or subscription charge.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;What a reader can reproduce&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The local counting method and price arithmetic. Raw work transcripts are not published, so the aggregate sample cannot be independently reconstructed from this page.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;November 17 review&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The whole guide and the current official pricing, caching, usage, and plugin references were reread. The original private transcript analysis was not rerun.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Who this is for:&lt;/strong&gt; heavy Claude Code users who want to know where their usage goes, and anyone running subagents or long sessions who has never looked at the token mix underneath.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Start here:&lt;/strong&gt; &lt;a href=&quot;#how-do-you-measure-your-own-claude-code-usage&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;run the local measurement&lt;/a&gt;, then &lt;a href=&quot;#how-do-you-compare-a-change-without-losing-quality&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;compare the next week&lt;/a&gt;. If the costly work is an external handoff, the companion &lt;a href=&quot;https://www.danmercede.com/guides/claude-code-controls-grok-bot&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Claude Code to Grok Bot guide&lt;/a&gt; covers request IDs, explicit completion, and ambiguous sends. It does not establish that moving the work saves money.&lt;/p&gt;&lt;hr class=&quot;my-10 border-white/10&quot;/&gt;&lt;h2 id=&quot;how-do-you-measure-your-own-claude-code-usage&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you measure your own Claude Code usage?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On October 23, 2026, I ran Anthropic&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;session-report&lt;/code&gt; plugin over seven days of local transcripts and got 471 sessions, 21,449 API calls and 6.15 billion tokens. The plugin reads saved transcripts under &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.claude/projects&lt;/code&gt;, including subagent transcripts. Your available history depends on what remains on that machine.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The plugin is listed in &lt;a href=&quot;https://claude.com/marketplace/plugins/session-report&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Anthropic&amp;#x27;s official marketplace&lt;/a&gt;. In Claude Code:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300&quot;&gt;/plugin install session-report@claude-plugins-official
/session-report&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It writes an HTML report you can sort and expand. The &lt;a href=&quot;https://github.com/anthropics/claude-plugins-official/blob/fd30cee3ecd5a8ee772733c5d20c0f2bae2da2f0/plugins/session-report/skills/session-report/analyze-sessions.mjs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;published analyzer source&lt;/a&gt; supports &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--json --since 7d&lt;/code&gt;. A streamed response can have several records for one request, and a resumed session can replay history into a new file. The analyzer deduplicates usage and retains the largest output-token count for a request within a file. If you write your own counter, account for both cases before trusting the totals.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the report private until you inspect it: prompts and project names can appear in the output. For comparisons, save the report, the analysis time, the selected window, the Claude Code version, and the price table you used.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My week, from the plugin&amp;#x27;s JSON:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Measure&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Value&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Sessions&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;471&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;API calls&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;21,449&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Input tokens&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;6.12B (97.2% cache reads)&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Output tokens&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;21.6M&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Subagent runs&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;688 (1.96B tokens, 32% of all tokens)&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Calls that wrote more than 100K uncached tokens&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;223&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That table reads like a well-tuned setup. 97% cached sounds like the cache is doing its job. It is doing its job, and that&amp;#x27;s exactly why the number tells you so little.&lt;/p&gt;&lt;h2 id=&quot;why-is-97-cached-the-wrong-number-to-watch&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Why is &amp;quot;97% cached&amp;quot; the wrong number to watch?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In my week, cache reads were 96.9% of all tokens but about 46% of the cost at API list prices. Cache writes were 2.8% of tokens and about 38% of the cost. Output was 0.4% of tokens and about 16%. Token share and cost share draw two different maps of the same week.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The reason is the price ladder. These are the Claude Opus 5.5 rates used in the October 23, 2026 analysis, per million tokens. They still matched &lt;a href=&quot;https://platform.claude.com/docs/en/about-claude/pricing&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Anthropic&amp;#x27;s published pricing&lt;/a&gt; at the November 17 review:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Token type&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Price&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;vs. base input&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Cache read&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;$0.20&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;0.05x&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Base input (uncached)&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;$4.00&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;1x&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;5-minute cache write&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;$5.00&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;1.25x&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;1-hour cache write&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;$8.00&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;2x&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Output&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;$20.00&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;5x&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A 1-hour cache write costs 40 times what a cache read costs. So a session holding 500,000 tokens of context pays about $0.10 to re-read it on the next turn, and about $4.00 to write it again from scratch. One rewrite costs the same as forty reads of that same context.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;So I priced every request in the week by its own model and token types. The session-report plugin counts tokens, not money, so I wrote a small script to weigh them. It keeps one usage record per request ID and splits cache writes by their time-to-live, using the &lt;a href=&quot;https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;API&amp;#x27;s cache-creation fields&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Save the following as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;weigh.py&lt;/code&gt;. Its price rows are the historical analysis inputs, not an automatically maintained price catalog. It skips unknown models and warns about their excluded tokens. Records without a request ID are excluded, and missing usage fields count as zero. Treat the result as a partial estimate if your transcripts do not have the expected fields. This script estimates token charges only; tool fees, provider-specific prices, discounts, and subscription metering are outside it.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;#!/usr/bin/env python3
&amp;quot;&amp;quot;&amp;quot;Weigh Claude Code token usage by API list price (not plan quota).&amp;quot;&amp;quot;&amp;quot;
import glob, json, os, sys
from collections import defaultdict
from datetime import datetime, timedelta, timezone

# USD per million tokens: (input, output, cache read), from Anthropic&amp;#x27;s pricing
# page on 2026-10-23. Longer model IDs first: matching is by prefix.
PRICES = {
    &amp;quot;claude-opus-5-5&amp;quot;: (4.00, 20.00, 0.20),
    &amp;quot;claude-sonnet-5-5&amp;quot;: (2.00, 10.00, 0.10),
    &amp;quot;claude-haiku-5-5&amp;quot;: (0.10, 0.50, 0.01),  # prompts up to 100K tokens
    &amp;quot;claude-fable-5-1&amp;quot;: (10.00, 50.00, 0.25),
    &amp;quot;claude-opus-5&amp;quot;: (5.00, 25.00, 0.50),
}
HAIKU_LONG = (0.50, 2.50, 0.05)  # Haiku 5.5 prompts over 100K tokens
days = float(sys.argv[1]) if len(sys.argv) &amp;gt; 1 else 7
since = datetime.now(timezone.utc) - timedelta(days=days)

best = {}  # request id -&amp;gt; (model, usage); keep the record with the most output
skipped = 0
for path in glob.glob(os.path.expanduser(&amp;quot;~/.claude/projects/**/*.jsonl&amp;quot;), recursive=True):
    with open(path, errors=&amp;quot;replace&amp;quot;) as fh:
        for line in fh:
            if &amp;#x27;&amp;quot;usage&amp;quot;&amp;#x27; not in line:
                continue
            try:
                e = json.loads(line)
            except ValueError:
                skipped += 1
                continue
            msg, rid, ts = e.get(&amp;quot;message&amp;quot;) or {}, e.get(&amp;quot;requestId&amp;quot;), e.get(&amp;quot;timestamp&amp;quot;)
            u = msg.get(&amp;quot;usage&amp;quot;) if isinstance(msg, dict) else None
            if not (u and rid and ts):
                continue
            try:
                when = datetime.fromisoformat(str(ts).replace(&amp;quot;Z&amp;quot;, &amp;quot;+00:00&amp;quot;))
            except ValueError:
                skipped += 1
                continue
            if when.tzinfo is None:  # treat offset-less timestamps as UTC
                when = when.replace(tzinfo=timezone.utc)
            if when &amp;lt; since:
                continue
            if rid not in best or (u.get(&amp;quot;output_tokens&amp;quot;) or 0) &amp;gt;= (best[rid][1].get(&amp;quot;output_tokens&amp;quot;) or 0):
                best[rid] = (msg.get(&amp;quot;model&amp;quot;, &amp;quot;?&amp;quot;), u)

tokens, cost, unpriced = defaultdict(int), defaultdict(float), defaultdict(int)
for model, u in best.values():
    n = lambda d, k: d.get(k) or 0  # missing or null counts as 0
    cc = u.get(&amp;quot;cache_creation&amp;quot;) or {}
    w1h = n(cc, &amp;quot;ephemeral_1h_input_tokens&amp;quot;)
    parts = {
        &amp;quot;uncached&amp;quot;: n(u, &amp;quot;input_tokens&amp;quot;),
        &amp;quot;write_1h&amp;quot;: w1h,
        &amp;quot;write_5m&amp;quot;: max(n(u, &amp;quot;cache_creation_input_tokens&amp;quot;) - w1h, 0),  # total includes 1h
        &amp;quot;read&amp;quot;: n(u, &amp;quot;cache_read_input_tokens&amp;quot;),
        &amp;quot;output&amp;quot;: n(u, &amp;quot;output_tokens&amp;quot;),
    }
    price = next((p for k, p in PRICES.items() if model.startswith(k)), None)
    if price is None:
        unpriced[model] += sum(parts.values())
        continue
    prompt = sum(n(u, k) for k in (&amp;quot;input_tokens&amp;quot;, &amp;quot;cache_creation_input_tokens&amp;quot;, &amp;quot;cache_read_input_tokens&amp;quot;))
    if model.startswith(&amp;quot;claude-haiku-5-5&amp;quot;) and prompt &amp;gt; 100_000:
        price = HAIKU_LONG
    # fast mode doubles every rate; US-only routing adds 10%
    mult = (2 if u.get(&amp;quot;speed&amp;quot;) == &amp;quot;fast&amp;quot; else 1) * (1.1 if u.get(&amp;quot;inference_geo&amp;quot;) == &amp;quot;us&amp;quot; else 1)
    inp, out, rd = (x * mult for x in price)
    rate = {&amp;quot;uncached&amp;quot;: inp, &amp;quot;write_5m&amp;quot;: 1.25 * inp, &amp;quot;write_1h&amp;quot;: 2 * inp, &amp;quot;read&amp;quot;: rd, &amp;quot;output&amp;quot;: out}
    for kind, count in parts.items():
        tokens[kind] += count
        cost[kind] += count * rate[kind] / 1e6

t, c = sum(tokens.values()), sum(cost.values())
if skipped:
    print(f&amp;quot;skipped {skipped} unreadable transcript lines; totals may be low&amp;quot;)
for model, count in unpriced.items():
    print(f&amp;quot;no price row for {model}: {count / 1e6:,.1f}M tokens left out&amp;quot;)
if c == 0:
    sys.exit(&amp;quot;nothing priced: add a PRICES row for your model&amp;quot;)
print(f&amp;quot;{len(best)} requests, {t / 1e6:,.0f}M priced tokens, ${c:,.0f} at list price&amp;quot;)
for kind in tokens:
    print(f&amp;quot;{kind:9} {100 * tokens[kind] / t:5.1f}% of tokens  {100 * cost[kind] / c:5.1f}% of cost&amp;quot;)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run it with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;python3 weigh.py 7&lt;/code&gt; for the last seven days. In the original analysis it matched the plugin to within 0.1% on request count and total tokens, and put the week at roughly $2,500 at API list price. That agreement is a reported result from October, not a new verification of the private dataset.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The dated table uses standard long-context rates for Opus 5.5 and Sonnet 5.5, the higher Haiku 5.5 tier above 100,000 prompt tokens, and modifiers for supported fast-mode and US-only requests. None of those modifiers showed up in my week: every request ran at standard speed on global routing. Check the current provider and model prices before applying this script to different traffic; do not assume its modifier rules cover a new model.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/claude-code-usage/token-vs-cost-share.webp&quot; alt=&quot;Two stacked bars comparing one week of Claude Code usage. By tokens, cache reads fill 97% of the bar. By list price, cache reads are 46%, cache writes 38% and output 16%.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Same week, two maps: cache writes are 3% of the tokens and 38% of the list-price cost.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The practical change is what you watch. A hit rate of 97% says little about cost. The cache write share says a lot, and it moves when your habits change.&lt;/p&gt;&lt;h2 id=&quot;what-is-a-cache-break-and-where-did-mine-come-from&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What is a cache break, and where did mine come from?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The plugin flags any call that writes more than 100,000 tokens it couldn&amp;#x27;t read from cache. My week had 223 of them, holding 42% of all cache-write tokens. When I lined each one up against the previous call in the same transcript, 209 of the 223 (94%) followed idle gaps longer than the observed cache lifetime. I classified those as consistent with expiry. Timing alone cannot exclude a simultaneous prompt change or another invalidation.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A cache entry has a time-to-live. A cache hit refreshes the entry; after expiry, a request may have to write its prefix again. Anthropic documents &lt;a href=&quot;https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;five-minute and one-hour cache lifetimes&lt;/a&gt;. In my transcripts the two kinds of context used different windows: 98% of main-session cache writes were 1-hour writes, and 100% of subagent cache writes were 5-minute writes. That is what my logs show on Claude Code 2.1.301 through 2.1.305, not a documented guarantee, so check the &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;cache_creation&lt;/code&gt; fields in your own transcripts before you rely on it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;So I sorted the 223 big writes by what happened just before each one:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What came before the rewrite&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Breaks&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Write tokens&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;List price&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A main session sat idle for over an hour&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;72&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;38.3M&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;about $307&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A subagent had finished, then got a follow-up message over 5 minutes later&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;92&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;19.5M&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;about $76&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A subagent waited over 5 minutes on its own tool call&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;42&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;9.9M&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;about $44&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A subagent sat idle over 5 minutes in some other way&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;3&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;0.7M&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;about $3&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The prefix changed while the cache was still live&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;13&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;2.3M&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;about $14&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The first call of a transcript&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;1&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;0.3M&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;about $2&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The first four rows are the expiry-consistent cases: 72 + 92 + 42 + 3 = 209. The prefix-change row covers an edited system prompt, a changed tool list, or a model switch while the observed lifetime had not elapsed. It was 13 breaks out of 223.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;At list price, those 223 rewrites cost about $446, or 18% of my week. That is 223 calls out of 21,449.&lt;/p&gt;&lt;h2 id=&quot;why-do-subagents-cost-more-than-their-token-count-suggests&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Why do subagents cost more than their token count suggests?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In my week, 688 subagent runs made up 32% of all tokens but 64% of all cache writes. A new subagent read a median 17,900 tokens from cache on its first call, then wrote a median 55,000 more. The bigger cost came later: 92 times, I sent a follow-up to a subagent that had already finished, after its 5-minute cache had expired.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with the first call, because every subagent pays it. The shared part of the prompt was already cached (78% of first calls read more than 10,000 tokens from cache), but the subagent&amp;#x27;s own brief and context were new, and across 688 runs those first-call writes added up to 39 million tokens, 23% of all my cache writes.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The follow-ups are the part I didn&amp;#x27;t expect. When a subagent finishes and you message it again, my transcripts show Claude Code continuing the same subagent with all of its context. If that follow-up arrives more than five minutes later, the cache is gone, and the whole subagent context gets written back. In my week, the median rewrite from a revived subagent was 178,000 tokens, more than three times the median cost of starting a fresh one. The median gap before those follow-ups was 9.3 minutes, so these weren&amp;#x27;t hour-long pauses. They were the ordinary rhythm of a coordinator getting to a subagent&amp;#x27;s result a few minutes late.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Long tool calls matter less than I assumed. 42 subagent breaks came after the subagent waited more than five minutes on its own command, a build or a test run or a sleep, which cost about $44 for the week. That&amp;#x27;s real, but it&amp;#x27;s about 60% of the follow-up cost, and both are small next to the main-session row.&lt;/p&gt;&lt;h2 id=&quot;what-does-walking-away-from-a-long-session-cost&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does walking away from a long session cost?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;72 of my main-session cache breaks came after more than an hour idle, and they cost about $307 at list price, 12% of my week. 57 of them were me coming back to a session, after a median gap of 11 hours, with a median rewrite of 489,000 tokens. Typing &amp;quot;continue&amp;quot; sends the whole context again as a 1-hour write, at twice the base input price.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The math is blunt. A session that has grown to 500,000 tokens of context costs about $4 in cache writes the moment you resume it the next morning, before the model does anything new. Do that across several open sessions and it adds up, while every individual turn still looks cheap.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The other 15 weren&amp;#x27;t a person coming back. 9 followed a foreground command that ran for more than an hour, so the session&amp;#x27;s own cache expired while it waited, and 6 followed a background task notification that woke an idle session.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;You have two simple options before you step away from a big session. End it with a short written handoff and start fresh, so the next session begins small. Or compact it while the cache is still warm, so what gets rewritten later is a summary instead of the full history. I didn&amp;#x27;t measure the compaction option here; it follows from the price table, since a compaction run while the cache is warm reads the history at the cheap rate.&lt;/p&gt;&lt;h2 id=&quot;what-does-this-tell-you-about-the-usage-draining-5x-reports&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does this tell you about the &amp;quot;usage draining 5x&amp;quot; reports?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Nothing conclusive. The original motivation was &lt;a href=&quot;https://x.com/CampbellKaleb23/status/2112957708219433095&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;an October 21 report of faster usage drain&lt;/a&gt; and &lt;a href=&quot;https://x.com/bcherny/status/2113417302402322910&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Anthropic&amp;#x27;s subsequent response&lt;/a&gt;. That was the context when I wrote the October analysis, not a claim about the investigation&amp;#x27;s status today. A token mix priced at API rates cannot establish why a subscription limit changed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;What the transcripts do give you is a local baseline. Compare cache-write share, large rewrites, subagent activity, model mix, and completed work across equivalent windows. A difference can come from workload or software behavior as well as habits. No difference does not prove that the cause is external: local logs can be incomplete. Claude Code&amp;#x27;s current &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/usage&lt;/code&gt; view adds plan bars and approximate attribution from that machine&amp;#x27;s history, while its session dollar estimate remains separate from subscriber billing.&lt;/p&gt;&lt;h2 id=&quot;what-i-m-changing&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What I&amp;#x27;m changing&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The first three changes come straight from rows in the tables above:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;After a long break, I start fresh with a handoff instead of resuming a huge context.&lt;/strong&gt; That was 57 resumes and most of the $307 main-session row.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Follow-ups to a finished subagent go out within five minutes, or go to a fresh subagent with a short brief.&lt;/strong&gt; A revived subagent rewrote a median 178,000 tokens; a fresh one wrote 55,000. That was 92 breaks and about $76.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Long waits run in the main session, not inside a subagent.&lt;/strong&gt; The main session keeps a 1-hour cache in my logs; a subagent keeps five minutes. That was 42 breaks and about $44.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;I watch the cost share, not the hit rate.&lt;/strong&gt; The weekly check is the script above, and the line I read first is cache writes.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;These are workflow changes I chose from the measured rows, not a controlled before-and-after savings result. Reusing an agent can preserve context you would otherwise have to rebuild. A shorter brief is useful only if it retains the requirements and evidence needed to finish correctly.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-compare-a-change-without-losing-quality&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you compare a change without losing quality?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with one seven-day baseline. Choose one change, such as a written handoff before leaving a large session, then collect another seven-day report. Hold the price table constant when comparing token efficiency; use actual invoices or plan readings for billing questions.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Record for both windows&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Why it matters&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Start and end timestamps, timezone, software versions&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Makes the periods and tool behavior comparable.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Requests, token buckets, unknown models, missing records&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exposes changes in mix and holes in the counter.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Cache-write share, rewrites above 100K, subagent runs&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Connects the change to a specific source of usage.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Completed tasks, regression results, rework&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Prevents lower usage from being mistaken for better performance when less work was completed.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;API estimate and plan readings in separate columns&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Keeps a modeled price from becoming a billing claim.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a quick check of the article&amp;#x27;s price arithmetic, this dependency-free example makes no API calls:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;python3 - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
tokens = 500_000
read_usd = tokens * 0.20 / 1_000_000
write_usd = tokens * 8.00 / 1_000_000
print(f&amp;quot;Cache read: ${read_usd:.2f}&amp;quot;)
print(f&amp;quot;One-hour write: ${write_usd:.2f}&amp;quot;)
print(f&amp;quot;Price ratio: {write_usd / read_usd:.0f}x&amp;quot;)
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expected output is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;$0.10&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;$4.00&lt;/code&gt;, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;40x&lt;/code&gt;. Those values validate only the arithmetic under the stated rates, not the private 471-session sample.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If you change a prompt or model to reduce usage, &lt;a href=&quot;https://www.danmercede.com/guides/regression-test-ai-agent-prompt-model-change&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;regression-test the agent&amp;#x27;s behavior&lt;/a&gt; before accepting the result. If you delegate external work to another product, use the companion &lt;a href=&quot;https://www.danmercede.com/guides/claude-code-controls-grok-bot&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Claude Code to Grok Bot webhook guide&lt;/a&gt; to keep acceptance, completion, and retry decisions explicit.&lt;/p&gt;</content:encoded></item>
<item><title>Hand over development evidence without losing the original observation</title><link>https://www.danmercede.com/guides/agent-development-evidence-handoff</link><guid isPermaLink="true">https://www.danmercede.com/guides/agent-development-evidence-handoff</guid><pubDate>Mon, 19 Oct 2026 07:00:00 +0000</pubDate><description>Retain exact worktree-report bytes, pass compact context and independently re-observe before completing a local demonstration.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A development task often outlives the process that started it. The next worker needs the original evidence, an explanation of what remains unfinished and a fresh view of the repository. Passing a summary alone loses detail. Passing a task claim alone does not make an old observation current.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The development evidence profile in Orion Starter composes four independent tools around that problem. One worker retains an exact worktree observation and yields. A separately invoked worker recovers those exact bytes, obtains its own claim and observes again before completing one deliberately narrow demonstration.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This guide covers Orion Starter &lt;strong class=&quot;font-semibold text-white&quot;&gt;0.3.0-rc.1&lt;/strong&gt;, an opt-in release candidate. Download the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/releases/download/v0.3.0-rc.1/orion-starter-0.3.0-rc.1.zip&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;versioned ZIP&lt;/a&gt;, &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/releases/download/v0.3.0-rc.1/SHA256SUMS&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;SHA256SUMS&lt;/a&gt; and &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/releases/download/v0.3.0-rc.1/release-verification.json&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;verification receipt&lt;/a&gt;. Verify the ZIP and verification receipt against SHA256SUMS before extracting the ZIP. The receipt identifies the selected source, archive and observed validation scope; this preview is not a stable 0.3.0 release.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;ZIP SHA-256:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;0140b2c4e3df2ad1bb0f015c9785d3ff44b44a6da51004026344a02c5ba91c01&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;h2 id=&quot;keep-the-roles-separate&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep the roles separate&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Tool&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Owns&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What it does not establish&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;PM 0.1.1&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Task state, revisions, claims and current evidence&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Permission from the user or a file lock&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Worktree Report 0.1.0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Registered-worktree observations and coverage&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Merge safety or repaired code&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Results 0.1.0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exact retained text and recoverable native references&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;That the observation is still current&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Handoff 0.1.0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Immutable context and pickup assessment&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A transferred claim or authority to execute prose&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The profile&amp;#x27;s goal is to capture and independently re-observe a deliberately created dirty-path overlap. A positive overlap is expected. Completing this demonstration means the second worker observed that overlap with complete coverage, retained its own evidence and read back the completed task. It never means the conflicting edits were repaired.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The default PM/browser and optional PM/browser/Handoff profiles remain available with their existing package pins, executable examples and locks. This new profile has its own four-wheel lock and no browser, npm, account, provider key, hook or systemd prerequisite. It installs no background service and adopts no existing runtime state.&lt;/p&gt;&lt;h2 id=&quot;start-with-a-fresh-extraction-and-synthetic-data&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Start with a fresh extraction and synthetic data&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The package&amp;#x27;s &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/blob/v0.3.0-rc.1/profiles/development-evidence/README.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;standalone profile walkthrough&lt;/a&gt; is included in the extracted ZIP. Its first block verifies the profile metadata, downloads the exact selected wheels and checked pip 26.2.1 installer, and installs into a virtual environment created without bundled pip. The installer is separate from the four installed packages.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The next block creates an empty private workspace outside Git. It initializes a run-specific demonstration task and Handoff store, selects an empty Results parent, and creates a synthetic repository with two linked worker worktrees. Both workers deliberately edit the same tracked path. Fixture creation is an explicit setup operation; &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;inspect&lt;/code&gt; does not create these resources.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Initial native qualification is CPython 3.11 on Linux x86_64 under WSL2, local ext4, Git 2.43.0 and linked SQLite 3.45.1. Other platforms, network filesystems, cross-host fencing, independent newcomer adoption and native Claude/Codex/Grok/Dot integration remain unverified. A general wheel tag does not expand that support claim.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An October 31 operator reproduction used the exact ZIP and selected release wheels on CPython 3.11.9, WSL2/ext4, Git 2.43.0 and linked SQLite 3.45.1. A separately invoked consumer recovered the producer&amp;#x27;s exact 3,163-byte report, made a new observation under a different claim generation and read back the synthetic task as done with no remaining claim. The selected metadata snapshot was 173 bytes. These sizes describe that run, not a fixed report size or a whole-context budget.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The same reproduction retained partial coverage without completing the task, refused an ambiguous Handoff pickup, and passed the archive&amp;#x27;s 38 development-evidence process tests. Those tests include stale or replaced context, missing capture and loss of ownership. This is one operator&amp;#x27;s local reproduction; the profile remains a preview pending independent newcomer evidence. The older continuity guide and its video still teach 0.2.0-rc.1.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;After running the package&amp;#x27;s verified install and synthetic-setup blocks, keep the printed &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;DEMO_ROOT&lt;/code&gt;. Run the following from the extracted distribution root:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
: &amp;quot;${DEMO_ROOT:?Use the synthetic workspace printed by the package walkthrough}&amp;quot;
.private/evidence-venv/bin/python -I -B profiles/development-evidence/run.py inspect --selection &amp;quot;$DEMO_ROOT/selection.json&amp;quot;
.private/evidence-venv/bin/python -I -B profiles/development-evidence/run.py produce --selection &amp;quot;$DEMO_ROOT/selection.json&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Inspection reads the exact selected task/store identity and public component versions. The producer then creates its own attempt and task claim, scans only the explicit roots, and retains the exact emitted UTF-8 report including its final newline. Exit 1 from the reporter is an expected complete positive observation.&lt;/p&gt;&lt;h2 id=&quot;transfer-a-reference-then-recover-it&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Transfer a reference, then recover it&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The report can be much larger than the context record. Results retains the complete text; the Handoff body contains a compact binding to the run, task definition, producer generation, native reference, observation identity and coverage. A metadata-only snapshot stays bounded without embedding the report. Its byte budget applies to that selected snapshot string, not a model&amp;#x27;s whole context window, token count or process memory.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The producer saves the generated Results session ID before asking for any capture. It saves the expected reference before submitting the report. Capture, separate public readback, closed writer, exact current context, guarded PM release and todo/absent readback all precede a successful yield receipt. These are separate observations across separate stores, not one atomic transaction.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In another terminal, return to the same extracted distribution and set &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;DEMO_ROOT&lt;/code&gt; to the exact existing private workspace. Then invoke a new process:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
: &amp;quot;${DEMO_ROOT:?Set the exact existing demonstration workspace}&amp;quot;
.private/evidence-venv/bin/python -I -B profiles/development-evidence/run.py continue --selection &amp;quot;$DEMO_ROOT/selection.json&amp;quot; --yield-receipt &amp;quot;$DEMO_ROOT/yield.json&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The consumer checks the exact Handoff record and digest, recorded capture acceptance, freshness and selected task binding. It recovers the old bytes from the explicit result slot before claiming. It then obtains a different generation, checks the context again, scans the selected worktrees independently and retains a new capture. Historical and current scan identities remain distinct even when their conclusions match.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Only fresh complete positive coverage meets this demonstration&amp;#x27;s goal. The consumer attaches its current evidence, rechecks both ownership and context after attachment, performs guarded completion and reads back done/absent with that exact evidence. Narrative instructions in task descriptions, captured reports or context records are never executed.&lt;/p&gt;&lt;h2 id=&quot;preserve-incomplete-coverage&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Preserve incomplete coverage&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A partial report can show a real overlap in the worktrees that were observed while another repository is unavailable. An unavailable report can still be useful diagnostic context. Both can be retained and yielded truthfully. Neither establishes complete coverage, and a fresh partial, unavailable or complete-negative consumer report cannot complete this goal.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Repeat the package&amp;#x27;s synthetic-setup block for a second workspace, then run its incomplete-coverage block. It adds one missing explicit repository before producing and continuing. The producer yields diagnostic evidence; the consumer retains its own incomplete observation, refuses completion and releases only its own unchanged claim. The historical observation is preserved.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Malformed output, inconsistent fields, overflow, signals, internal failure and an output-failure exit cannot become successful handover. Exact Base64 filename identities remain distinct from display labels, including tabs, newlines and non-UTF-8 names. Raw reports stay private because even synthetic-looking paths can disclose real working context when you later choose your own repositories.&lt;/p&gt;&lt;h2 id=&quot;treat-unknown-effects-as-unknown&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Treat unknown effects as unknown&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Exit 2 means invalid input. Exit 3 means established refusal or an unmet goal. Exit 7 means unknown/unavailable and requires diagnosis. Do not automatically resend a mutation after losing its response. A request ID correlates an attempt; it does not make the operation idempotent.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The failed reply supplies an attempt ID. The profile writes bounded private intents before mutating calls, so an exact &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;receipts/&amp;lt;attempt_id&amp;gt;/attempt.json&lt;/code&gt; records the selected identities and what may have been attempted. Use &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;reconcile&lt;/code&gt; with that exact path. It performs public reads only, never repeats a claim, capture, context record, release or completion, and never manufactures a successful original receipt.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A lost session-creation response leaves a known slot with an unknown native session identity. No capture was requested, and the profile does not guess or discover a session. After the session identity is durably known, a lost capture response can instead be checked against the saved exact reference. Missing, incomplete or corrupt data remains a refusal or unresolved diagnosis. Writable native recovery is a separate explicit operation.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/blob/v0.3.0-rc.1/docs/runbooks/starter-development-evidence.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;profile runbook&lt;/a&gt; explains claim/context changes, native repair boundaries, output/process limits and quiescent backup. References provide identity, not execution authority.&lt;/p&gt;&lt;h2 id=&quot;retain-data-when-removing-the-environment&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Retain data when removing the environment&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The package walkthrough verifies a closed Results backup through exact public readback, then removes only its selected environment. All owned helper/profile processes must have exited before the copy. A copy of a live SQLite database is not a validated backup. A full run restore also needs the matching PM/Handoff state, selection and receipts under the same pinned artifacts.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Removing an environment does not remove retained observations, context, task state, synthetic repositories or backups. Review the exact owned temporary parent before deliberately disposing of data. Keep old published archives immutable and select the prior environment with matching backups when rolling back.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The useful boundary is observable: the next worker can recover what the first worker actually saw, then establish its own current evidence. It still needs the current request, valid ownership and a goal that the new observation can satisfy.&lt;/p&gt;</content:encoded></item>
<item><title>&#39;Done&#39; Needs a Receipt: Four Checks Before You Believe an Agent Finished</title><link>https://www.danmercede.com/guides/done-needs-a-receipt</link><guid isPermaLink="true">https://www.danmercede.com/guides/done-needs-a-receipt</guid><pubDate>Mon, 19 Oct 2026 07:00:00 +0000</pubDate><description>When an agent says deployed, armed, fixed or verified, that is a claim, not evidence. Four MIT-licensed skills from orion-skills turn each claim into a receipt: output from the system itself, captured after the change, that would read differently if the claim were false.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It said healthy. Every API call said 502.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-06-20, a dashboard backend I run showed &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Up 9 days (healthy)&lt;/code&gt; in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;docker ps&lt;/code&gt;, and the dashboard pages returned 200 with a rendered shell. So a status check and a title check both called it live. But every API route behind those pages was returning 502, and only a real browser render with console capture showed it: 40 errors, all 502.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Agents write the status word as the last step of a plan, and the plan was written before the work ran. So &amp;quot;deployed&amp;quot; often means &amp;quot;I ran the deploy command&amp;quot;, and &amp;quot;tests pass&amp;quot; can mean &amp;quot;the tests that are left pass&amp;quot;. The agent isn&amp;#x27;t lying. It&amp;#x27;s reporting its own narration, and the narration ends on a success word because that&amp;#x27;s how plans end.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My rule now is short. &lt;strong class=&quot;font-semibold text-white&quot;&gt;A completion word without a receipt beside it is a claim, and I treat it as one.&lt;/strong&gt; This guide covers what counts as a receipt, the four claims that most need one, the open-source skills that make an agent bring the receipt without being asked, and what a receipt still doesn&amp;#x27;t prove.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Who this is for:&lt;/strong&gt; anyone who lets Claude Code, Codex or another coding agent deploy, merge, install hooks, or run verification on their behalf, and then reads the agent&amp;#x27;s summary to decide what happened.&lt;/p&gt;&lt;hr class=&quot;my-10 border-white/10&quot;/&gt;&lt;h2 id=&quot;what-makes-a-piece-of-output-a-receipt&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What makes a piece of output a receipt?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-07-18 my own test suite went 503 of 503 green over a bug I had diagnosed correctly and then failed to fix. I&amp;#x27;d added a fixture that made the normal-day test pass, and the alert it guarded could still never clear. Green read the same with the bug alive, so green wasn&amp;#x27;t a receipt.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Three independent review passes flagged it. The suite never did, because I had changed what the suite measured.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A receipt has three properties:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The system produced it&lt;/strong&gt;, not the agent&amp;#x27;s prose. A curl status code, a runner&amp;#x27;s summary line, a hook&amp;#x27;s own BLOCKED message. A sentence in the agent&amp;#x27;s final message that says &amp;quot;verified&amp;quot; is not output from anything.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;It was captured after the change, in this turn.&lt;/strong&gt; A green check from before the last push, or a status from yesterday&amp;#x27;s handoff, describes a different system.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;It would read differently if the claim were false.&lt;/strong&gt; This is the property most proxies fail. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/health&lt;/code&gt; returns 200 whether the new code is serving or the old code is, so it can&amp;#x27;t tell you which one you have.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The third test is the one I run in my head: imagine the claim is false, and ask whether this output would change. If it wouldn&amp;#x27;t, it&amp;#x27;s a proxy.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Claim&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Proxy (reads the same either way)&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Receipt&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&amp;quot;Deployed&amp;quot;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;deploy exited 0, container healthy, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/health&lt;/code&gt; 200, PR merged&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;running build SHA equals the merge SHA; the declared route answers; the failing case now succeeds&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&amp;quot;Tests pass&amp;quot;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&amp;quot;all green&amp;quot; in the summary&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the runner&amp;#x27;s own count line, compared with the count on &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main&lt;/code&gt;, plus a diff of the test files&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&amp;quot;The gate is armed&amp;quot;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;hook installed, CI green, monitor OK&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the gate blocking a planted violation, in its own output&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&amp;quot;It&amp;#x27;s still broken&amp;quot; / &amp;quot;it landed&amp;quot;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the handoff note, the local checkout&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the failing case reproduced now; &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;origin&lt;/code&gt; after a fresh &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;git fetch&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&amp;quot;Verified by the reviewers&amp;quot;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the summary flag, the verdict count&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;completed reads per claim, with pending claims named&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &amp;quot;tests pass&amp;quot; row deserves one more line, because it&amp;#x27;s the claim where the cheapest proxy hides the worst failure. If an agent deletes or skips the failing test, the run really is green. Two commands show it:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;# test files deleted on this branch since it left main
git diff --diff-filter=D --name-only main...HEAD -- tests/

# skip or focus markers added on this branch
git diff main...HEAD -- tests/ | grep -nE &amp;#x27;^\+.*(skip|xfail|\.only\()&amp;#x27;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The three dots matter. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main...HEAD&lt;/code&gt; compares the branch with the point where it left &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main&lt;/code&gt;, so a test added on &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main&lt;/code&gt; since then doesn&amp;#x27;t show up as &amp;quot;deleted on this branch&amp;quot;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;And the runner&amp;#x27;s collected count is part of the receipt. If &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main&lt;/code&gt; collects 212 tests and the branch collects 211, the word &amp;quot;green&amp;quot; leaves out the one that matters.&lt;/p&gt;&lt;h2 id=&quot;choose-the-completion-boundary-before-the-work-starts&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Choose the completion boundary before the work starts&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Make this sentence specific: &lt;strong class=&quot;font-semibold text-white&quot;&gt;This task is complete when someone can observe the requested result at the place it will be used.&lt;/strong&gt; The boundary depends on the request.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Requested result&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Where to check it&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What that does not establish&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A private draft&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The readable document&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Publication or delivery to another person&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A source repair&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The requested revision and its corrected behavior&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Adoption by a running service&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A deployed repair&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The running version and the real user path&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Every future case or delivery&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A delivered message&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The recipient outcome required by the task&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Receipt merely because a queue accepted it&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A draft request does not require publication. A source change does not silently authorize deployment. A deployment request should not end at a successful build. Choose the boundary that matches the authority and the outcome actually requested.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Bind the evidence to the change: include the relevant revision or artifact identifier, environment, observation time and case exercised. Exclude sensitive values. A passing check from an older revision or a screenshot from a preview environment answers a different question from whether the current production change works.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the check proportionate. One successful delivery proves that case at that time; it does not establish that every future delivery will succeed. Once the requested outcome is observed, report that result and its practical limits.&lt;/p&gt;&lt;h2 id=&quot;why-isn-t-green-ci-and-a-healthy-container-proof-of-deployed&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Why isn&amp;#x27;t green CI and a healthy container proof of &amp;quot;deployed&amp;quot;?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In June 2026 I found a merged feature that had done nothing in production for about two months. The running image had been built before the merge and never rebuilt, so the repo had the code and the server didn&amp;#x27;t. Rebuilding the image, with zero code changes, fixed it on 2026-06-18.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The PR was merged, and the service kept answering the whole time, with the old code. Both were true statements about the wrong thing.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;prove-deploy-is-live&lt;/code&gt; skill asks for three proofs, and none of them substitutes for another:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Version identity.&lt;/strong&gt; The running artifact is the new build. Compare a baked build SHA, a &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/version&lt;/code&gt; route or the running image digest against the merge commit, not against &amp;quot;the PR merged&amp;quot;.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The real route serves.&lt;/strong&gt; Probe the route users actually hit, never &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/health&lt;/code&gt; and never a bare &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/&lt;/code&gt;. By HTTP class, 2xx, 3xx, 401, 403, 405 and 429 mean the app answered; 404, 5xx and a refused connection count as a regression. For a worker or a queue consumer, &amp;quot;serves&amp;quot; means a real item went in and came out the other end.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The behavior is correct end to end.&lt;/strong&gt; Rerun the case that was failing and watch it succeed. For a single-page app, that means rendering it and reading the console and the data calls, because the shell can return 200 while every API call behind it fails.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/done-needs-a-receipt/deploy-proxies-vs-receipts.webp&quot; alt=&quot;Two rows. The top row shows four amber proxy signals: deploy exited 0, container healthy, /health returns 200, PR merged. The bottom row shows three green receipts joined by arrows: version identity, real route serves, behavior end to end, each with the failure it rules out.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Proxies are necessary at most. Each receipt rules out a failure the proxies can&amp;#x27;t see.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In shell, the first two are a few lines, run from a clone of the repo. The names here are placeholders for your own service:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;# 1. Version identity: the running build contains the merge commit
git fetch -q origin
merge_sha=$(gh pr view 123 --json mergeCommit -q .mergeCommit.oid)
running_sha=$(curl -s https://app.example.com/version)
if git merge-base --is-ancestor &amp;quot;$merge_sha&amp;quot; &amp;quot;$running_sha&amp;quot;; then
  echo &amp;quot;VERSION OK: $running_sha contains the merge&amp;quot;
else
  echo &amp;quot;STALE: running $running_sha&amp;quot;
fi

# 2. The declared route answers (never /health)
curl -s -o /dev/null -w &amp;#x27;route %{http_code}\n&amp;#x27; https://app.example.com/api/orders&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If you can&amp;#x27;t run one of the proofs, the honest status is &amp;quot;wired but unproven&amp;quot;. That phrase does a lot of work in my sessions. It tells me exactly which check is missing, and it stops a half-proven deploy from being filed as done.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-know-a-gate-is-armed-and-not-just-quiet&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you know a gate is armed and not just quiet?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-19 I staged a fake GitHub token in a scratch repo whose pre-commit hook blocks tokens. The commit went through with exit 0, and a secret scanner printed &amp;quot;no leaks found&amp;quot;. Two controls were installed and both looked green. Neither had stopped anything, and the reason was different for each.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Green has two causes: nothing to catch, or catching nothing. The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;prove-control-binds&lt;/code&gt; skill exists to tell them apart, and its whole method is to plant a violation and watch the control fire from its own output. These are the runs from that scratch repo, with git 2.43.0 and gitleaks 8.24.3:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Run&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What I staged&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What happened&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;1&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ghp_&lt;/code&gt; followed by 36 copies of the letter &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a&lt;/code&gt;, local hook in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;.git/hooks&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;committed, exit 0, &amp;quot;no leaks found&amp;quot;&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;2&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ghp_&lt;/code&gt; followed by 36 random letters and digits&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;blocked by the scanner, exit 1&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;3&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;same random token, with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;-c core.hooksPath=.git/hooks&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;blocked by my local hook, exit 1&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two separate things were wrong in run 1.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;My hook was dead code.&lt;/strong&gt; My global git config sets &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;core.hooksPath&lt;/code&gt;, so git looks for hooks in that directory and never in the repo&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;.git/hooks&lt;/code&gt;. The hook I wrote was installed, executable and correct, and git never ran it. The scanner output came from a different hook entirely. If I hadn&amp;#x27;t read whose message it was, I&amp;#x27;d have credited my own hook.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The canary looked fake, and the scanner agreed.&lt;/strong&gt; With its default rules, gitleaks passed a token made of one repeated letter. It also passed &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ghp_&lt;/code&gt; plus the alphabet in order, which has plenty of entropy, so I&amp;#x27;m reporting what it did rather than guessing at why. A random token was blocked at once. A canary has to look like the real thing, assembled from random characters at run time so the full token string never sits in a file, or the control&amp;#x27;s silence tells you nothing.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The skill keeps a table of the silent no-op shapes. These are the ones I see most:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Shape&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;How it stays green&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Shadowed hook&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;a global &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;core.hooksPath&lt;/code&gt; makes &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;.git/hooks/*&lt;/code&gt; dead code&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Empty pathspec&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;a pathspec that matches no files scans nothing and passes&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Subset CI&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the required check runs a fixed file list, so new tests never gate&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Vacuous skip&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;a conditional skip lets the gate pass without running&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Aged-out monitor&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the monitor shows OK after its producer stopped reporting&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Reaper alibi&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the cleanup job exits green having removed nothing&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Review checks are gates too, and they fail the same way. On 2026-09-19 one of my pull requests showed six checks, all green or passing, and no line-by-line review had happened. One review bot&amp;#x27;s plan only writes a summary. A cloud integration had hit its usage limit. The two checks that were genuinely green were a secret scan and a build, and neither is a review. Behind them, two review passes timed out, and two engines refuse diffs over 200,000 characters (this one was 300,874). The green checks hid all of it, and each engine&amp;#x27;s own log or comment said so.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The receipt for &amp;quot;armed&amp;quot; is the canary command and the control&amp;#x27;s own blocking output, recorded where the next person will look. For &amp;quot;reviewed&amp;quot;, it&amp;#x27;s each reviewer&amp;#x27;s own log. Without those, &amp;quot;armed&amp;quot; means &amp;quot;installed&amp;quot; and &amp;quot;reviewed&amp;quot; means &amp;quot;a check ran&amp;quot;.&lt;/p&gt;&lt;h2 id=&quot;why-re-check-a-claim-the-last-session-made&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Why re-check a claim the last session made?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-06-25 I concluded that a site migration had only half landed, on four separate signals: old links, a missing runbook, missing sitemap entries and a PR that looked unmerged. All four were false. My checkout of this site&amp;#x27;s repo was 8 commits behind, and one &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;git fetch&lt;/code&gt; flipped every signal.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Even &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;git show origin/main:&amp;lt;file&amp;gt;&lt;/code&gt; agreed with the wrong answer, because my local copy of &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;origin/main&lt;/code&gt; predated the merge. A handoff note, a teammate&amp;#x27;s diagnosis and your own memory of yesterday all fail the same way: true when written, and possibly false now.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I hit a small version of this while writing the guide. My notes said this site&amp;#x27;s single-page app returned HTTP 200 for a guide that doesn&amp;#x27;t exist, a classic soft 404, and I was about to use it as the example. I probed it first. On 2026-10-19, a missing &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/guides/&lt;/code&gt; page returns a real 404; a fix in late September replaced the catch-all rewrite. The trap is still common on single-page apps, but my note about my own site was stale.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;reprobe-stale-premise&lt;/code&gt; skill treats any claim you didn&amp;#x27;t verify this session as a hypothesis, and gives each kind its own probe:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;&amp;quot;It&amp;#x27;s still broken.&amp;quot;&lt;/strong&gt; Rerun the failing case now. If it no longer reproduces, report &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ALREADY-FIXED (checked: &amp;lt;command&amp;gt;)&lt;/code&gt; and stop. Don&amp;#x27;t invent a fix for a bug that&amp;#x27;s gone.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;&amp;quot;Tool X doesn&amp;#x27;t exist.&amp;quot;&lt;/strong&gt; Search by concept and by alias, not only by name. Report &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ABSENT (checked: &amp;lt;command&amp;gt;)&lt;/code&gt;, never a silent absence.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;&amp;quot;Did the PR land?&amp;quot;&lt;/strong&gt; Run &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;git fetch origin&lt;/code&gt; first. Without it, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;git show origin/main:&amp;lt;file&amp;gt;&lt;/code&gt; reads your local copy of the remote, which can be days old. Then confirm with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;gh pr view &amp;lt;n&amp;gt; --json state,mergedAt&lt;/code&gt;. The remote is the truth and the clone is a cache.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;&amp;quot;It merged, so it&amp;#x27;s out.&amp;quot;&lt;/strong&gt; Merged isn&amp;#x27;t deployed. Go back to the three proofs.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The status words in those bullets are the receipt format. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ALREADY-FIXED (checked: ...)&lt;/code&gt; carries its own evidence, so the next reader can rerun it instead of trusting it.&lt;/p&gt;&lt;h2 id=&quot;what-did-a-panel-of-verifier-agents-actually-verify&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What did a panel of verifier agents actually verify?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-06-29 a 105-agent research run hit rate limits in its verify stage. No verifier managed to vote on 25 useful sources, and the run&amp;#x27;s tooling recorded each 0-0 vote as &amp;quot;refuted&amp;quot;, so the run&amp;#x27;s summary would have thrown all 25 away. They hadn&amp;#x27;t been refuted. A rate limit returns a default, not a judgment.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Fan-outs fail in a specific way. A verifier that hits a rate limit or a timeout still returns something, and the something is often its default verdict. So a throttled panel can report &amp;quot;all refuted&amp;quot;, and a dead skeptic can report &amp;quot;survived the skeptic&amp;quot;. Both read as confident results.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;triage-fanout-verdicts&lt;/code&gt; skill reads the mechanism fields before the verdict fields: how many reads each verifier completed, what errors it logged, and whether it said it couldn&amp;#x27;t decide. It ships a small script that re-buckets every claim from those fields and ignores the aggregator&amp;#x27;s summary flag. I fed it a four-claim sample shaped like a throttled run, where every claim said &amp;quot;refuted&amp;quot; and the summary said &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;all_refuted: true&lt;/code&gt;:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;python3 skills/triage-fanout-verdicts/scripts/triage_verdicts.py verify.json&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;BLOCKING: 3/4 claims are PENDING (abstention/infra-failure is not a verdict); re-verify before any decision they are load-bearing for.
{
  &amp;quot;total&amp;quot;: 4,
  &amp;quot;buckets&amp;quot;: {
    &amp;quot;CONFIRMED&amp;quot;: [],
    &amp;quot;REFUTED&amp;quot;: [
      &amp;quot;c1&amp;quot;
    ],
    &amp;quot;PENDING_INFRA&amp;quot;: [
      &amp;quot;c2&amp;quot;,
      &amp;quot;c3&amp;quot;
    ],
    &amp;quot;PENDING_ABSTAIN&amp;quot;: [
      &amp;quot;c4&amp;quot;
    ]
  },
  &amp;quot;pending&amp;quot;: 3,
  &amp;quot;clean&amp;quot;: false
}&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It exits 3 when anything is pending, so a script or an agent loop can gate on it. Only c1 was refuted from completed reads. c2 and c3 had none (a 429 and a timeout), and c4&amp;#x27;s verifier read two sources, then said it couldn&amp;#x27;t decide. A pending claim gets re-verified by a different route, never rounded to a verdict. I wrote up the gate design behind this in &lt;a href=&quot;https://www.danmercede.com/guides/verifier-abstention-not-refutation&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Self-Correcting Agents: Learning the Loop the Hard Way&lt;/a&gt;.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-make-the-agent-bring-the-receipt-without-being-asked&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you make the agent bring the receipt without being asked?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;prove-deploy-is-live&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;prove-control-binds&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;reprobe-stale-premise&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;triage-fanout-verdicts&lt;/code&gt; ship in &lt;a href=&quot;https://github.com/OrionArchitekton/orion-skills&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;orion-skills&lt;/a&gt; v0.6.0 (2026-09-28), MIT licensed, alongside 23 others. Claude Code loads skills from &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.claude/skills/&lt;/code&gt;, so a copy is the whole install, and a short project rule carries the same demand into every turn, not only the turns where a skill&amp;#x27;s description happens to match.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;git clone --branch v0.6.0 https://github.com/OrionArchitekton/orion-skills
cd orion-skills
mkdir -p ~/.claude/skills
for s in prove-deploy-is-live prove-control-binds \
         reprobe-stale-premise triage-fanout-verdicts; do
  cp -r &amp;quot;skills/$s&amp;quot; ~/.claude/skills/
done&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The repo README also covers the &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;skills&lt;/code&gt; CLI and Codex installs. Each skill&amp;#x27;s description names the moment it applies (&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;prove-deploy-is-live&lt;/code&gt;, for one, triggers when the agent is about to declare a deploy live), so the agent loads it when it&amp;#x27;s about to make the claim.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;mkdir -p&lt;/code&gt; line isn&amp;#x27;t decoration. Without it, on a machine with no &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.claude/skills&lt;/code&gt; yet, the first &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;cp -r&lt;/code&gt; creates that directory as a copy of the skill, so one skill&amp;#x27;s files land loose in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.claude/skills/&lt;/code&gt;, and nothing reports an error.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Skills fire on a match, though, and I want the rule on every turn. So I also keep a short block in the project instructions file the agent reads at the start of a session (&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;CLAUDE.md&lt;/code&gt; or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;AGENTS.md&lt;/code&gt;):&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;markdown&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-markdown&quot;&gt;## Completion claims
- Never write &amp;quot;deployed&amp;quot;, &amp;quot;live&amp;quot;, &amp;quot;fixed&amp;quot;, &amp;quot;armed&amp;quot;, &amp;quot;passing&amp;quot; or &amp;quot;verified&amp;quot;
  without the command you ran and its output beside it.
- If you could not run the proof, write &amp;quot;wired but unproven&amp;quot; and name the
  missing check.
- A claim from a handoff, a teammate or an earlier session is a hypothesis.
  Re-probe it before acting on it.
- A verifier that timed out, was rate limited or abstained has not voted.
- Report status as one of: LIVE, WIRED-UNPROVEN, ALREADY-FIXED (checked: ...),
  ABSENT (checked: ...), PENDING.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That gives every summary a small, fixed vocabulary:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Status&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Means&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;LIVE&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;all three deploy proofs ran this turn, output attached&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;WIRED-UNPROVEN&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;changed, but at least one proof didn&amp;#x27;t run; the missing one is named&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ALREADY-FIXED (checked: ...)&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;the inherited bug no longer reproduces&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ABSENT (checked: ...)&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;searched by concept and alias, not found&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;PENDING&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;a verifier didn&amp;#x27;t complete; not a verdict either way&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;h2 id=&quot;what-does-a-receipt-not-prove&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does a receipt not prove?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-06-20 a dashboard&amp;#x27;s pages returned a real 200, captured live from the system itself, while every API call behind them failed. That 200 was a receipt, and it proved the page shell loaded, which was never in question. A receipt proves one observation at one moment, and it&amp;#x27;s only as good as the question you pointed it at.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;So three limits are worth stating plainly.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The receipt can point at the wrong thing.&lt;/strong&gt; A 200 from the wrong route is a convincing receipt for a claim you didn&amp;#x27;t make. The skills push you toward the declared route and the original failing case for exactly this reason, but choosing them is still your call.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The agent can&amp;#x27;t author its own receipt.&lt;/strong&gt; Output pasted into the agent&amp;#x27;s prose is prose. The receipt is a tool result in the session record, from a command that queried the system. Read the command as well as its output, because &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;echo &amp;quot;VERSION OK&amp;quot;&lt;/code&gt; is a tool call too.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Proof has a cost, so scale it to the blast radius.&lt;/strong&gt; A local refactor needs the test count and the test-file diff, not three deploy proofs. A production cutover needs all three, for every service it touched. Each skill&amp;#x27;s &amp;quot;when not to use&amp;quot; note keeps it to its own claim (&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;prove-deploy-is-live&lt;/code&gt; is for after a deploy, not for a local change), so the heavy proofs only show up where the claim calls for them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The words I trust least in an agent&amp;#x27;s final message are done, live and verified. They still show up, and now each one arrives with the command that earned it, or it says unproven and names what&amp;#x27;s missing.&lt;/p&gt;&lt;h2 id=&quot;when-the-final-check-depends-on-a-future-event&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;When the final check depends on a future event&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Sometimes the repaired version is running but the next ordinary event has not happened. Say both things plainly. For example:&lt;/p&gt;&lt;blockquote class=&quot;my-5 border-l-2 border-copper-500/50 pl-5 text-slate-300&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The repaired collector is installed, and its requested native reads succeeded. The normal scheduled batch has not run yet. Observe the next batch before claiming scheduled adoption.&lt;/p&gt;&lt;/blockquote&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That is an illustrative reporting pattern, not a benchmark result. Name the next observation point. Do not label an unfinished check as a defect, or create a customer message or business record just to make the status look complete.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use this instruction when asking an agent for its completion note:&lt;/p&gt;&lt;blockquote class=&quot;my-5 border-l-2 border-copper-500/50 pl-5 text-slate-300&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;State the result I requested. Describe what changed. Link the evidence for that result, including the revision and environment where relevant. State what remains unverified. If a check is blocked or waiting for an event, name the next observation or exact decision required. Keep publication, sending, deployment and other outward actions within the authority already given.&lt;/p&gt;&lt;/blockquote&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The answer should let you accept the result, check one remaining fact, or resolve a concrete blocker. A prepared artifact is useful progress. Close the task when the evidence establishes the requested outcome.&lt;/p&gt;</content:encoded></item>
<item><title>See overlapping work without guessing who owns it</title><link>https://www.danmercede.com/guides/git-worktree-overlap-report</link><guid isPermaLink="true">https://www.danmercede.com/guides/git-worktree-overlap-report</guid><pubDate>Mon, 19 Oct 2026 07:00:00 +0000</pubDate><description>Use explicit Git worktree observations, exact path identities and coverage states to coordinate concurrent changes.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Git worktrees let several changes move forward in separate checkouts. They also make it easy to miss that two changes touch the same path. The useful question is concrete: which registered worktrees currently report the same uncommitted path?&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Orion Worktree Report answers that question for repositories you explicitly select. It includes coverage in the answer because an unavailable checkout cannot be treated as a clean one. The command observes local state. It does not assign work, lock files or decide whether a merge is safe.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The walkthrough creates one disposable repository and two linked worktrees. It leaves ordinary project repositories alone.&lt;/p&gt;&lt;h2 id=&quot;install-into-a-dedicated-environment&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Install into a dedicated environment&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use CPython 3.11, Git 2.43.0 and a local ext4 filesystem on Linux x86_64 under WSL2 for the initial tested target. Other environments remain unverified. Start in a fresh local folder containing the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-worktree-report/releases/download/v0.1.0/orion_worktree_report-0.1.0-py3-none-any.whl&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;v0.1.0 wheel&lt;/a&gt;. The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-worktree-report/releases/tag/v0.1.0&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;release page&lt;/a&gt; also carries the source archive and SHA256SUMS. The first command below verifies this guide&amp;#x27;s selected wheel digest before any installer executes.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The installer is a separate checksum-pinned pip wheel from PyPI. Python extracts it locally, then runs it in isolated mode to install the reporter into an environment created without bundled pip or setuptools. This uses no global tool upgrade. Keep the installer folder for removal later. Downloading pip needs HTTPS; installing the reporter uses no index or dependencies.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
test ! -e .venv
test ! -e .installer
printf &amp;#x27;f06d7ca9d3fd1001b9bd16ed18a8ee7827727c09eeb4a535f41692723336550b  orion_worktree_report-0.1.0-py3-none-any.whl\n&amp;#x27; | sha256sum --check --strict
curl --fail --location --proto &amp;#x27;=https&amp;#x27; --tlsv1.2 --max-time 60 \
  https://files.pythonhosted.org/packages/f3/6e/1736e5b4ae2b778ef2f81c47d797de9f891d4d8acb047a24ca37a60294dd/pip-26.2.1-py3-none-any.whl \
  --output pip-26.2.1-py3-none-any.whl
printf &amp;#x27;71138adf1f4ca900cdb7d289c21b7494329f2332b6d85f0e1c42108c0384ed3e  pip-26.2.1-py3-none-any.whl\n&amp;#x27; | sha256sum --check --strict
python3.11 -m zipfile -e pip-26.2.1-py3-none-any.whl .installer
python3.11 -m venv --without-pip .venv
python3.11 -I .installer/pip --isolated --python .venv/bin/python install --no-index --no-deps ./orion_worktree_report-0.1.0-py3-none-any.whl
.venv/bin/orion-worktree-report --json version&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;There are no Python runtime dependencies. The reporter environment contains only the reporter, with its own bin/python; the POSIX launcher isolates imports and disables bytecode writes before Python startup. The separate installer and its vendored libraries are setup tools, not packages installed into that environment. Other installation layouts are unverified. Git must be trusted and on PATH. No daemon, hook or configuration change is installed.&lt;/p&gt;&lt;h2 id=&quot;build-one-disposable-example&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Build one disposable example&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Continue in this same folder and shell. Use ordinary Git settings in your test environment; the fixture-creation commands themselves are standard Git operations.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;mkdir demo-repo
git -C demo-repo init -b main
git -C demo-repo config user.name &amp;#x27;Synthetic example&amp;#x27;
git -C demo-repo config user.email &amp;#x27;example@example.invalid&amp;#x27;
printf &amp;#x27;base\n&amp;#x27; &amp;gt; demo-repo/shared.txt
git -C demo-repo add shared.txt
git -C demo-repo commit -m &amp;#x27;Synthetic baseline&amp;#x27;
git -C demo-repo worktree add -b worker-a ../worker-a
git -C demo-repo worktree add -b worker-b ../worker-b
DEMO_ROOT=&amp;quot;$(pwd)/demo-repo&amp;quot;
.venv/bin/orion-worktree-report --json scan --repo &amp;quot;$DEMO_ROOT&amp;quot; &amp;gt; clean.json&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The last command exits 0. The JSON reports one repository, three registered and observed worktrees, complete coverage and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;no_overlap_observed&lt;/code&gt;. The reporter uses Git&amp;#x27;s registration list, so the worktrees need not sit at any particular folder depth.&lt;/p&gt;&lt;h2 id=&quot;make-one-shared-dirty-path&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Make one shared dirty path&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;printf &amp;#x27;worker a\n&amp;#x27; &amp;gt; worker-a/shared.txt
printf &amp;#x27;worker b\n&amp;#x27; &amp;gt; worker-b/shared.txt
OVERLAP_EXIT=0
.venv/bin/orion-worktree-report --json scan --repo &amp;quot;$DEMO_ROOT&amp;quot; &amp;gt; overlap.json || OVERLAP_EXIT=$?
test &amp;quot;$OVERLAP_EXIT&amp;quot; -eq 1&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This command deliberately exits &lt;strong class=&quot;font-semibold text-white&quot;&gt;1&lt;/strong&gt;. It observed an overlap with complete coverage. The block captures and checks that exit explicitly so the walkthrough can continue under &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;set -e&lt;/code&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The report names &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;shared.txt&lt;/code&gt; and one unordered pair of worktree IDs. It reports exact path identity, not whether the edits conflict semantically. Two worktrees can touch the same file in compatible ways. Separate clones with matching history remain separate repositories.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Staged changes, unstaged changes and individual nonignored untracked files enter the dirty-path set. Indexed renames/copies retain source and destination roles. Committed-only divergence, ignored files and submodule interiors do not enter this report&amp;#x27;s scope. Filename identities are Base64 of exact bytes; an exact UTF-8 label is supplied only when valid. Display labels are not comparison keys.&lt;/p&gt;&lt;h2 id=&quot;keep-a-missing-observation-visible&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep a missing observation visible&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;PARTIAL_EXIT=0
.venv/bin/orion-worktree-report --json scan --repo &amp;quot;$DEMO_ROOT&amp;quot; --repo &amp;quot;$(pwd)/missing-repo&amp;quot; &amp;gt; partial.json || PARTIAL_EXIT=$?
test &amp;quot;$PARTIAL_EXIT&amp;quot; -eq 3&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The result exits &lt;strong class=&quot;font-semibold text-white&quot;&gt;3&lt;/strong&gt; and says coverage is partial. The already observed positive pair can remain as a known subset. The registered-worktree total is null because one selected repository could not be discovered. That unknown is not zero.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When a known registration is unavailable, its unobserved dirty paths are null. Parse failure, timeout, configured unsupported features, detected drift and exceeded limits also prevent a complete negative answer.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Result&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Meaning&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exit 0, complete, no overlap observed&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Every selected supported scope was observed; no exact pair appeared.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exit 1, complete, overlap observed&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;One or more exact pairs appeared with complete coverage.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exit 3, partial&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Only a subset was observed; no absence claim is available.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exit 2, 4 or 70, unavailable&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Invalid invocation, unavailable/limited observation or internal failure.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Always read interface version, process exit, coverage, conclusion and problems together. A failed output write is unsuccessful too. A valid JSON object alone establishes no coverage claim.&lt;/p&gt;&lt;h2 id=&quot;know-the-observation-boundary&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Know the observation boundary&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On supported stable repositories, the command initiates no writes to objects, refs/reflogs, index, configuration, working files or registrations and creates no in-repository locks, caches or reports. Filesystem access-time bookkeeping is excluded. Native inventories and helper sentinels check this boundary on the acceptance target.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before any repository-aware Git setup, bounded configuration snapshots are checked with includes disabled. Include targets are refused before they are opened. Filters, included repository configuration, submodules/gitlinks, sparse or split indexes, partial/promisor clones and bare repositories are refused. Index flags that can hide changed paths, including assume-unchanged and skip-worktree, are refused as unsupported observations too. Intent-to-add remains observable. The reader disables optional locks, fsmonitor, global/system config and attributes, prompts and inherited Git redirection/tracing. Repository-local ignore rules remain active. These controls require cooperative stable configuration and a trusted executable. They are not a sandbox against malicious Git or a concurrent configuration writer.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Repeated observations compare registrations, HEAD, index/config digests and status. Detected changes make coverage incomplete without a silent retry. Matching samples cannot rule out a change-and-revert between reads or fence another writer.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Work is bounded: eight supplied roots, 64 registrations, 4,096 dirty paths per worktree, 1,000 overlap records, bounded command/output/config/index sizes, five seconds per Git command and a 60-second owned scan deadline. Exceeded limits remain visible problems. Host scheduling and uninterruptible I/O have no hard wall-clock guarantee. See the package behavior contract for all byte caps.&lt;/p&gt;&lt;h2 id=&quot;retain-the-report-deliberately&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Retain the report deliberately&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The example saves reports outside the selected repository. Reports contain absolute local roots, branch names and file names. Keep them private until you review and sanitize them. The command does not emit file contents, diffs, remotes or raw Git diagnostics.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A later PM or Results consumer can deliberately attach a report through its own public interface. This package creates no task, lease, Handoff record, persistent store or integration, and changes no other package pin. The observation is evidence for your next decision; the authority to change files comes from your actual workflow.&lt;/p&gt;&lt;h2 id=&quot;remove-the-package&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Remove the package&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;python3.11 -I .installer/pip --isolated --python .venv/bin/python uninstall -y orion-worktree-report&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Uninstall removes package files only. Your synthetic repositories, linked worktrees and saved reports remain. No runtime state needs migration.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The first-party package uses MIT. Its NOTICE acknowledges ECC by Affaan Mustafa and retains the upstream MIT license for the selected overlap/deduplication concepts. The reference identifies pinned upstream material; it does not claim an exact historical source pin. The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-worktree-report&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;source, behavior contract and runbook&lt;/a&gt; describe the complete supported surface.&lt;/p&gt;</content:encoded></item>
<item><title>The Tool Worked. The Agent Couldn&#39;t Use It.</title><link>https://www.danmercede.com/thoughts/2026-10-19-the-tool-worked-the-agent-couldnt-use-it</link><guid isPermaLink="true">https://www.danmercede.com/thoughts/2026-10-19-the-tool-worked-the-agent-couldnt-use-it</guid><pubDate>Mon, 19 Oct 2026 07:00:00 +0000</pubDate><description>A successful integration test establishes access for the executor that ran it; accepting a workflow requires evidence from its intended executor through the permitted route.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Your team delivers an AI integration. The developer runs it, gets a response, and marks the work complete. On Monday, the person responsible for the workflow asks the agent to use it. The agent cannot reach the tool.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The operations lead now owns a capability the team expected to have and still cannot use. Someone has to stop their work, reconstruct the developer&amp;#x27;s setup, and decide whether the missing access is a configuration problem or a boundary that should stay closed. If a customer is waiting on the result, the handoff has become their delay too.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That customer consequence is hypothetical. The access failure came from my own operation. We had a working tool, a successful host test, and an agent that could not run the same command from its own environment.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The host test answered a narrower question than the handoff required.&lt;/p&gt;&lt;h2 id=&quot;the-installer-and-the-worker-had-different-access&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;The installer and the worker had different access&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The integration connected a local AI assistant to an existing task relay. A small command-line adapter submitted an explicitly requested task and collected the response. The command lived in Linux under Windows Subsystem for Linux. The agent expected to use it was running through a Windows PowerShell executor with its own restrictions.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The adapter worked from the environment used to install and test it. That established something useful: the command was present and the tested route could run it. It did not establish that the consuming agent could read the files, invoke Linux, or reach the command through an approved interface.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We added a narrow Windows launcher for the adapter. It fixed the distribution, Linux user, interpreter, and command rather than exposing a general shell. A help check from the Windows host succeeded. From the agent&amp;#x27;s restricted executor, the reported error was &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Wsl/Service/E_ACCESSDENIED&lt;/code&gt;. Adapter help never appeared.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;So the second green check had the same limit as the first. We had proved another route from an environment we controlled. The intended worker still lacked a verified route.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The recovery needed a separately approved invocation from that worker. A reported help check then succeeded through the approved route. Later, a retained consumer check reported successful collection from the agent&amp;#x27;s native Linux executor, with the request and returned value compared against the existing local response. Those observations belong to their respective environments. A later success does not make the earlier host test sufficient.&lt;/p&gt;&lt;h2 id=&quot;a-tool-name-is-only-the-start-of-the-handoff&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;A tool name is only the start of the handoff&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When you ask whether an agent has a tool, the answer needs an actor and an operation. Can this worker, under this identity, perform this permitted action from the environment where the work will run?&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;You can install the same command on a machine and get different answers from an interactive terminal, a restricted desktop agent, a scheduled job, and a service account. They can differ in visible files, executable paths, network access, credentials, and approval requirements. Sharing a physical machine does not make their access equivalent.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An operations leader should not need to diagnose each of those differences personally. But someone has to own acceptance across them. If engineering hands over a successful terminal session and operations accepts a working business process, the two teams have agreed to different deliverables.&lt;/p&gt;&lt;h2 id=&quot;put-acceptance-in-the-worker-s-environment&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Put acceptance in the worker&amp;#x27;s environment&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For one AI workflow, name the executor that will do the work. Be specific enough to distinguish a developer&amp;#x27;s terminal from the agent&amp;#x27;s actual runtime and account. Then name the allowed operation and the result someone will inspect.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For our adapter, displaying command help answered an access question. It did not establish that a task could be submitted, that the response would arrive, or that the response belonged to the request. Each of those needed its own evidence and the appropriate authority to run the check.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a hypothetical invoice workflow, the equivalent distinction is between opening the invoice system and creating the intended draft under the correct business account. If the workflow stops at a draft for a person to approve, acceptance should stop there too. A developer&amp;#x27;s ability to send a live invoice supplies neither permission nor a requirement for the agent to do so.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with the least consequential check that answers the open question. Reading help can establish that a command starts. A permitted test record can establish a particular write path. A retained request identifier and matching result can establish the observed round trip. Keep the claim as narrow as the observation.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If you cannot run the required check without new authority, record that boundary explicitly. The work can be installed while acceptance remains open. That gives the workflow owner an accurate decision instead of a green status that conceals unfinished delivery.&lt;/p&gt;&lt;h2 id=&quot;a-denial-deserves-a-decision&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;A denial deserves a decision&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An access failure creates pressure to make the demonstration work. Someone suggests a broader account, a copied credential, or a general execution bridge. The missing capability can quietly become permission to expand what the agent may do.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Treat the denial as evidence about the current route. First determine whether the intended operation belongs within the worker&amp;#x27;s authority. Then identify the smallest approved interface that supports it. If the owner has not approved that access, keep the operation blocked and make the requested decision precise.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our launcher was deliberately narrow. That reduced what it exposed, but it did not make the surrounding executor&amp;#x27;s restrictions disappear. Fixing the command&amp;#x27;s interface and authorizing the caller to invoke it were separate concerns.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Engineers should preserve that distinction in the result they return. A permission denial should retain its cause and identify the blocked step. If an agent silently tries a more powerful route, the eventual success can conceal a change in authority that the workflow owner never accepted.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Fail-closed behavior also needs an owner for the next move. Name who can approve the missing access, choose another permitted route, or decide the workflow should remain manual. Otherwise a correct refusal leaves the business waiting without a person responsible for resolving it.&lt;/p&gt;&lt;h2 id=&quot;follow-the-result-back-to-the-request&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Follow the result back to the request&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Reaching the tool still leaves the result to verify. An accepted submission, an available response file, and a correctly interpreted result answer different questions. The worker needs the answer in a form it can use and associate with the original request.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The adapter retained a request identifier and caller attribution. For its bounded live check, the response had to carry the matching identity and expected value. Caller attribution helped connect the records; it was not authentication. A successful process exit alone was insufficient.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We also encountered a response the transport had returned but the adapter had not recognized. The repair was to correct the parser and collect the existing response. Sending the task again would have tested another action while leaving the original result unresolved.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That recovery detail matters to whoever operates the workflow after delivery. They need to know where to look when the agent has no usable answer, how to distinguish an access failure from an unresolved submission, and when a retry could create a second action. The integration handoff should include that path alongside the successful one.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This evidence establishes specific observed invocations. It does not certify every operation, future account change, or surrounding workflow. Keep the records identifiable so a later operator can see what was actually tested.&lt;/p&gt;&lt;h2 id=&quot;try-the-handoff-you-expect-someone-else-to-use&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Try the handoff you expect someone else to use&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Choose one AI capability your team already considers delivered. Identify its intended worker and one harmless operation within that worker&amp;#x27;s existing authority. Ask for the check from that environment, without borrowing the developer&amp;#x27;s account or adding access to get through it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Follow the result to the place the next person uses it. If the check stops, identify the exact boundary and who owns the next decision. If it succeeds, record which operation and route succeeded. One observation establishes that path; it does not clear every path the agent might later need.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then look at the delivery record. Does it name the actual executor, the permitted action, the result that was inspected, and the person responsible when it fails? Those details let operations distinguish an installed component from a workflow they can depend on.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I want the acceptance check to follow the person or agent expected to do the work. That is where the promise of the integration gets tested, and where its limitations become useful information.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If your team has an AI integration caught between a successful demo and daily use, the Readiness Scan my agency offers maps one workflow, its failure modes, and who owns its handoffs. &lt;a href=&quot;https://www.orionintelligenceagency.com/readiness-scan?utm_source=linkedin&amp;amp;utm_medium=newsletter&amp;amp;utm_campaign=readiness_scan&amp;amp;utm_content=fcn_ed14&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Work with my agency on one workflow&lt;/a&gt;.&lt;/p&gt;</content:encoded></item>
<item><title>Capture agent results without filling every selected view</title><link>https://www.danmercede.com/guides/capture-agent-results-with-byte-bounded-snapshots</link><guid isPermaLink="true">https://www.danmercede.com/guides/capture-agent-results-with-byte-bounded-snapshots</guid><pubDate>Sun, 18 Oct 2026 07:00:00 +0000</pubDate><description>Store complete text privately, pass a byte-bounded snapshot, and recover exact results by reference.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A tool can return more text than you want to pass to the next step. Trimming the return value can make the current view smaller, but the consumer still needs a dependable way to recover the exact original. It also needs to know when storing the result failed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;orion-results separates three operations: capture complete text in an explicitly selected private session, render a bounded snapshot, and read an exact result reference. The output promise applies to the complete UTF-8 snapshot string. It includes references, separators, inline JSON and omission counts. It does not limit tokens, the original input, previous strings you retained, process memory or a model&amp;#x27;s whole context window.&lt;/p&gt;&lt;h2 id=&quot;install-the-verified-release&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Install the verified release&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Download the wheel and source archive from the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-results/releases/tag/v0.1.0&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;v0.1.0 release&lt;/a&gt; into a new empty working folder. Keep both original filenames. The source archive supplies the complete backup/recovery example; the wheel is the installed library.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The following commands use CPython 3.11 on the demonstrated Linux/WSL2 local ext4 environment. Run all four command blocks in this guide from the same folder and shell. The first block checks the exact published bytes before installing or extracting anything; an unexpected checksum stops the walkthrough.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
sha256sum -c &amp;lt;&amp;lt;&amp;#x27;SHA256&amp;#x27;
67af57c4deda8967db83c2176642184bb3b7fb59f826539284086efa95e78e2e  orion_results-0.1.0-py3-none-any.whl
8463a8dfa19e9cfe4cf18718b82b0863ffcf52d4db180928908a0a810c61a56b  orion_results-0.1.0.tar.gz
SHA256
test ! -e .venv-results-demo
test ! -e orion_results-0.1.0
tar -xzf orion_results-0.1.0.tar.gz
RESULTS_WHEEL=&amp;quot;$(pwd)/orion_results-0.1.0-py3-none-any.whl&amp;quot;
RESULTS_SOURCE=&amp;quot;$(pwd)/orion_results-0.1.0&amp;quot;
python3.11 -m venv .venv-results-demo
.venv-results-demo/bin/python -m pip install --no-index --no-deps &amp;quot;$RESULTS_WHEEL&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;There are no pip runtime dependencies or database service to configure. Installation and import do not create capture sessions. The caller chooses an absolute root; there is no implicit home, vendor-session search or latest-session fallback.&lt;/p&gt;&lt;h2 id=&quot;capture-select-recover&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Capture, select, recover&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This walkthrough owns a fresh synthetic temporary directory. Its context manager removes only that directory after the demonstration. For real work, choose and retain a private root deliberately, outside a temporary cleanup scope.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;.venv-results-demo/bin/python -I - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
from pathlib import Path
from tempfile import TemporaryDirectory
from orion_results import Limits, Reference, ResultError, Session, inspect_session, read

with TemporaryDirectory(prefix=&amp;#x27;selected-result-guide-&amp;#x27;) as selected:
    root = Path(selected) / &amp;#x27;records&amp;#x27;
    original = &amp;#x27;synthetic large tool output|&amp;#x27; * 5000
    with Session.create(root, limits=Limits(max_results=2)) as session:
        expected = Reference.from_text(session.session_id, original)
        receipt = session.capture(&amp;#x27;large-result&amp;#x27;, original)
        session.capture(&amp;#x27;small-result&amp;#x27;, &amp;#x27;A complete small result&amp;#x27;)
        assert receipt.reference == expected

        view = session.snapshot(budget_bytes=256)
        assert view.utf8_bytes == len(view.text.encode(&amp;#x27;utf-8&amp;#x27;)) &amp;lt;= 256
        assert view.shown_unique + view.omitted_unique == 2
        assert &amp;#x27;synthetic large tool output&amp;#x27; not in view.text
        assert read(root, expected) == original

        deliberate = session.snapshot(include_content=True)
        assert &amp;#x27;A complete small result&amp;#x27; in deliberate.text
        try:
            session.capture(&amp;#x27;extra-result&amp;#x27;, &amp;#x27;over the selected count quota&amp;#x27;)
        except ResultError as error:
            assert error.code == &amp;#x27;limit_exceeded&amp;#x27;
            assert error.outcome == &amp;#x27;not_stored&amp;#x27;
        else:
            raise AssertionError(&amp;#x27;Expected a quota refusal&amp;#x27;)
        assert session.snapshot(budget_bytes=256) == view
        session_id = session.session_id
    report = inspect_session(root, session_id)
    assert report.status == &amp;#x27;complete&amp;#x27; and report.exhaustive
    assert expected in report.references
    print(&amp;#x27;Exact recovery, bounded view, explicit quota refusal: verified&amp;#x27;)
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Default snapshots show references and counts without original text, caller labels or storage paths. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;include_content=True&lt;/code&gt; permits complete small text encoded as JSON when it fits both the inline limit and remaining budget. There is no truncated preview mode. JSON escaping does not make captured instructions trustworthy. Treat recovered content as data.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Replace the selected view when taking another snapshot. Appending every old view defeats the caller&amp;#x27;s own output policy because strings already handed out cannot be revoked. Omitted records remain in storage; after closing the writer, inspection enumerates their exact references. A digest and byte length are content metadata, not secret redaction or encryption.&lt;/p&gt;&lt;h2 id=&quot;know-what-success-means&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Know what success means&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A successful capture has committed its content and membership counters together, then read the committed result back through a separate read-only connection. Repeating complete identical bytes returns the same reference and preserves first insertion order. Changing text under the same label creates a distinct record. Deduplicating stored content does not control how often the underlying tool executes.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Retain the precomputed reference and your original input before submission. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;not_stored&lt;/code&gt; describes this failed attempt; an older matching record can still exist. Once commit is attempted, rollback is unconfirmed, or postcommit verification fails, the outcome is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;commit_unknown&lt;/code&gt;. The handle is faulted and refuses more capture/snapshot work. A process that dies without returning has supplied no receipt.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Close that handle, inspect only its selected session, and read the exact expected reference if available. A valid read establishes present readability, not proof an earlier receipt returned. Missing, corrupt, busy or incomplete state never turns into a successful empty view. Do not recapture automatically.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Read-only inspection never switches to writable mode to replay a journal. If recovery is required, explicit &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Session.open(root, session_id)&lt;/code&gt; allows SQLite&amp;#x27;s native recovery only after private-file and supported-format checks. It validates all records and counters before accepting new captures. Never delete a journal or choose an older result to conceal a failed recovery.&lt;/p&gt;&lt;h2 id=&quot;keep-data-and-installation-separate&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep data and installation separate&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;New roots and session directories are private 0700; marker, database, lock and native journal require 0600, correct ownership and safe file types. Existing unsafe roots are refused without repair. One cooperative writer holds a stable lock inode. Call the storage API serially within each process. Overlapping or reentrant calls, including calls for different sessions, refuse immediately with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;storage_busy&lt;/code&gt;. Do not share Session handles between threads. Separate processes retain the documented SQLite and writer-lease contention behavior. Another writer gets &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;session_busy&lt;/code&gt;; process exit releases the lock. This is local coordination, not cross-host fencing or isolation from hostile same-user processes.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For backup, retain the selected writer handle, complete a validating snapshot and perform no other operation during the copy. Copy only the documented quiescent marker/database/lock set into new private files under a fresh root. Verify every expected reference against the restored root before treating it as a backup. A live transaction filesystem copy is not a backup. The complete synthetic example demonstrates that sequence and validates its owned cleanup:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;.venv-results-demo/bin/python -I &amp;quot;$RESULTS_SOURCE/examples/capture_results.py&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Uninstalling the distribution leaves caller-selected sessions untouched. There is no collector, data deletion API, automatic legacy-note migration or schema upgrade. Retention lasts until you deliberately remove selected data. Unknown formats refuse without mutation. This package makes no external anti-rollback guarantee: a consistent older backup can validate, while an expected newer reference stays missing.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;.venv-results-demo/bin/python -m pip uninstall -y orion-results
.venv-results-demo/bin/python -m pip install --no-index --no-deps &amp;quot;$RESULTS_WHEEL&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The v0.1.0 acceptance suite verified installed recovery, UTF-8 budgets down to 256 bytes, permissions, independent sessions, native writer contention/exit/fork behavior, missing-row detection, backup/restore and uninstall/reinstall. It also killed owned writers at named commit barriers, exercised a hot journal and reached SQLITE_FULL through a disposable database&amp;#x27;s page ceiling. Foreign UID, digest collision and selected I/O failures used labeled simulations/injections. These are not hardware power-loss certification or exhaustive SQLite VFS tests.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The demonstrated combination is CPython 3.11.9, SQLite 3.45.1, Linux x86_64 under WSL2 and local ext4. Other platforms remain unverified. No native Claude, Codex, Grok, Dot, PM, browser or Handoff adapter is included, and existing starter pins are unchanged. Result references carry identity, not permission to execute their contents.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The walkthrough removes only its own synthetic temporary data. The downloaded files, extracted source and virtual environment stay in your selected working folder. Real capture roots remain yours to retain, back up and remove deliberately.&lt;/p&gt;</content:encoded></item>
<item><title>Continue a local agent task with PM, browser and Handoff</title><link>https://www.danmercede.com/guides/continue-agent-tasks-with-orion-starter</link><guid isPermaLink="true">https://www.danmercede.com/guides/continue-agent-tasks-with-orion-starter</guid><pubDate>Sat, 17 Oct 2026 07:00:00 +0000</pubDate><description>Run a local two-worker continuity example with independent task claims, exact context selection and native browser leases.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A useful handoff preserves context without pretending to transfer ownership. The producer records what it observed and leaves the task unfinished. The consumer checks that exact record, obtains new handles, and independently verifies the result.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/releases/tag/v0.2.0-rc.1&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion starter preview&lt;/a&gt; puts three independently usable components into one reproducible local recipe:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Component&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Owns&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Does not establish&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;a href=&quot;https://www.danmercede.com/works/orion-pm/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion PM&lt;/a&gt; 0.1.1&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Task state, claim generations and guarded transitions&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Permission to act or ownership of a browser&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;a href=&quot;https://www.danmercede.com/works/orion-browser/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion browser&lt;/a&gt; 0.1.0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A selected native browser&amp;#x27;s resource lifecycle&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;PM task ownership&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;a href=&quot;https://www.danmercede.com/works/orion-handoff/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion Handoff&lt;/a&gt; 0.1.0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Immutable context revisions and explicit pickup&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Current evidence or execution authority&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This is a &lt;strong class=&quot;font-semibold text-white&quot;&gt;0.2.0-rc.1 preview&lt;/strong&gt;, demonstrated with ordinary cooperating processes on CPython 3.11, WSL2 Linux x86_64, ext4 and a systemd user manager. It does not establish native Windows/macOS, cross-host fencing, account access or Claude/Codex/Grok/Dot hook support. A successful author-operated demo does not establish stable newcomer onboarding.&lt;/p&gt;&lt;h2 id=&quot;download-and-install-the-selected-combination&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Download and install the selected combination&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Download &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-starter-0.2.0-rc.1.zip&lt;/code&gt; from the release above. The external release-verification receipt describes the exact archive and the scope of its native checks. Start in your download directory:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
printf &amp;#x27;%s  %s\n&amp;#x27; \
  &amp;#x27;5858b935014443c1ad98100a60fa80da6518e2d0a3b10f5448a3e50110963b48&amp;#x27; \
  &amp;#x27;orion-starter-0.2.0-rc.1.zip&amp;#x27; | sha256sum -c -
unzip orion-starter-0.2.0-rc.1.zip
cd orion-starter-0.2.0-rc.1&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The continuity profile adds Handoff through its own complete dependency lock. The original PM/browser profile remains available. Install the profile from the extracted root:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
python3.11 -m venv .venv
.venv/bin/python -m pip install --require-hashes --force-reinstall -r bootstrap-requirements.txt
.venv/bin/python -m pip install --require-hashes -r profiles/continuity/requirements.lock
npm ci --prefix driver
python3 scripts/check_profile.py
.venv/bin/orion-pm --json version
.venv/bin/orion-handoff --json --version
.venv/bin/orion-browser --version
driver/node_modules/.bin/agent-browser --version&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Chrome and browser system packages are explicit prerequisites under their own licenses. Use the browser release&amp;#x27;s setup documentation. Installation above does not create a store, start a browser, edit harness settings or sign in to an account.&lt;/p&gt;&lt;h2 id=&quot;create-isolated-synthetic-state&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Create isolated synthetic state&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use a shell without inherited browser or navigation-client overrides. Choose a free X screen from 10 through 99; the block below uses 84 and refuses a collision rather than selecting another resource. The task and context stores stay separate, outside source control. A setup failure is a reason to inspect the new directory, not rerun initialization over it.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;export XDG_RUNTIME_DIR=&amp;quot;${XDG_RUNTIME_DIR:-/run/user/$(id -u)}&amp;quot;
export DBUS_SESSION_BUS_ADDRESS=&amp;quot;${DBUS_SESSION_BUS_ADDRESS:-unix:path=$XDG_RUNTIME_DIR/bus}&amp;quot;
test -S &amp;quot;$XDG_RUNTIME_DIR/bus&amp;quot;
systemctl --user is-active default.target
DEMO_ROOT=$(mktemp -d &amp;quot;${TMPDIR:-/tmp}/starter-continuity.XXXXXXXX&amp;quot;)
export DEMO_ROOT
export DEMO_SCREEN=84
.venv/bin/python - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
from pathlib import Path
import hashlib, json, os, socket, subprocess, uuid
def check(condition, reason):
    if not condition:
        raise SystemExit(reason)
root = Path(os.environ[&amp;#x27;DEMO_ROOT&amp;#x27;]).resolve()
check(root.is_dir() and not list(root.iterdir()), &amp;#x27;workspace_not_empty&amp;#x27;)
check(not any(k.startswith((&amp;#x27;ORION_BROWSER_&amp;#x27;, &amp;#x27;AGENT_BROWSER_&amp;#x27;)) for k in os.environ), &amp;#x27;inherited_browser_override&amp;#x27;)
screen = int(os.environ[&amp;#x27;DEMO_SCREEN&amp;#x27;])
check(10 &amp;lt;= screen &amp;lt;= 99, &amp;#x27;screen_range&amp;#x27;)
check(not Path(f&amp;#x27;/tmp/.X{screen}-lock&amp;#x27;).exists(), &amp;#x27;screen_lock_exists&amp;#x27;)
check(not Path(f&amp;#x27;/tmp/.X11-unix/X{screen}&amp;#x27;).exists(), &amp;#x27;screen_socket_exists&amp;#x27;)
for port in (5900 + screen, 6080 + screen):
    with socket.socket() as probe:
        probe.bind((&amp;#x27;127.0.0.1&amp;#x27;, port))
candidate = Path.cwd().resolve()
binary = candidate / &amp;#x27;.venv/bin&amp;#x27;
def save(path, value):
    path.write_text(json.dumps(value) + &amp;#x27;\n&amp;#x27;)
    path.chmod(0o600)
def call(argv):
    result = subprocess.run(list(map(str, argv)), check=True, capture_output=True, text=True)
    value = json.loads(result.stdout)
    check(value[&amp;#x27;ok&amp;#x27;] is True, &amp;#x27;component_setup_refused&amp;#x27;)
    return value[&amp;#x27;data&amp;#x27;]
save(root / &amp;#x27;projects.json&amp;#x27;, {&amp;#x27;schema_version&amp;#x27;: 1, &amp;#x27;projects&amp;#x27;: [{&amp;#x27;id&amp;#x27;: &amp;#x27;sample&amp;#x27;}]})
pm = [binary / &amp;#x27;orion-pm&amp;#x27;, &amp;#x27;--json&amp;#x27;, &amp;#x27;--home&amp;#x27;, root / &amp;#x27;pm&amp;#x27;]
call([*pm, &amp;#x27;init&amp;#x27;, &amp;#x27;--projects&amp;#x27;, root / &amp;#x27;projects.json&amp;#x27;])
task = call([*pm, &amp;#x27;add&amp;#x27;, &amp;#x27;--id&amp;#x27;, &amp;#x27;continuity-demo&amp;#x27;, &amp;#x27;--title&amp;#x27;, &amp;#x27;Read the synthetic page twice&amp;#x27;,
             &amp;#x27;--project&amp;#x27;, &amp;#x27;sample&amp;#x27;, &amp;#x27;--status&amp;#x27;, &amp;#x27;todo&amp;#x27;])
call([binary / &amp;#x27;orion-handoff&amp;#x27;, &amp;#x27;--store&amp;#x27;, root / &amp;#x27;handoff&amp;#x27;, &amp;#x27;--json&amp;#x27;, &amp;#x27;init&amp;#x27;])
config = (&amp;#x27;[paths]\nstate = &amp;#x27; + json.dumps(str(root / &amp;#x27;browser-state&amp;#x27;)) +
          &amp;#x27;\nprofiles = &amp;#x27; + json.dumps(str(root / &amp;#x27;browser-profiles&amp;#x27;)) +
          &amp;#x27;\n[[browser]]\nname = &amp;quot;contdemo&amp;quot;\nscreen = &amp;#x27; + str(screen) + &amp;#x27;\nrestore_session = false\n&amp;#x27;)
(root / &amp;#x27;browser.toml&amp;#x27;).write_text(config)
(root / &amp;#x27;browser.toml&amp;#x27;).chmod(0o600)
save(root / &amp;#x27;agent.json&amp;#x27;, {})
digest = lambda raw: hashlib.sha256(raw).hexdigest()
definition = {k: task[&amp;#x27;task&amp;#x27;].get(k) for k in (&amp;#x27;id&amp;#x27;, &amp;#x27;project&amp;#x27;, &amp;#x27;title&amp;#x27;, &amp;#x27;description&amp;#x27;, &amp;#x27;next_action&amp;#x27;)}
selection = {
    &amp;#x27;selection_version&amp;#x27;: 1, &amp;#x27;run_id&amp;#x27;: str(uuid.uuid4()), &amp;#x27;workspace&amp;#x27;: str(root),
    &amp;#x27;pm&amp;#x27;: {&amp;#x27;executable&amp;#x27;: str(binary / &amp;#x27;orion-pm&amp;#x27;), &amp;#x27;home&amp;#x27;: str(root / &amp;#x27;pm&amp;#x27;), &amp;#x27;store_id&amp;#x27;: task[&amp;#x27;store_id&amp;#x27;],
           &amp;#x27;task_id&amp;#x27;: &amp;#x27;continuity-demo&amp;#x27;, &amp;#x27;task_definition_sha256&amp;#x27;: digest(json.dumps(
               definition, sort_keys=True, ensure_ascii=True, separators=(&amp;#x27;,&amp;#x27;, &amp;#x27;:&amp;#x27;)).encode())},
    &amp;#x27;handoff&amp;#x27;: {&amp;#x27;executable&amp;#x27;: str(binary / &amp;#x27;orion-handoff&amp;#x27;), &amp;#x27;store&amp;#x27;: str(root / &amp;#x27;handoff&amp;#x27;)},
    &amp;#x27;browser&amp;#x27;: {&amp;#x27;executable&amp;#x27;: str(binary / &amp;#x27;orion-browser&amp;#x27;), &amp;#x27;config&amp;#x27;: str(root / &amp;#x27;browser.toml&amp;#x27;),
                &amp;#x27;config_sha256&amp;#x27;: digest((root / &amp;#x27;browser.toml&amp;#x27;).read_bytes()), &amp;#x27;name&amp;#x27;: &amp;#x27;contdemo&amp;#x27;},
    &amp;#x27;client&amp;#x27;: {&amp;#x27;executable&amp;#x27;: str(candidate / &amp;#x27;driver/node_modules/.bin/agent-browser&amp;#x27;),
               &amp;#x27;config&amp;#x27;: str(root / &amp;#x27;agent.json&amp;#x27;), &amp;#x27;config_sha256&amp;#x27;: digest((root / &amp;#x27;agent.json&amp;#x27;).read_bytes())}}
save(root / &amp;#x27;selection.json&amp;#x27;, selection)
print(&amp;#x27;Created isolated selection; no browser has started.&amp;#x27;)
PY
ORION_BROWSER_CONFIG=&amp;quot;$DEMO_ROOT/browser.toml&amp;quot; .venv/bin/orion-browser --json setup
.venv/bin/python examples/continuity_starter.py --selection &amp;quot;$DEMO_ROOT/selection.json&amp;quot; inspect&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The final inspect reports selected task and context state. It does not claim a task or make browser lifecycle calls. The explicit browser setup prepares only the selected directories; a later lease starts this anonymous browser&amp;#x27;s transient resources.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The selection binds the PM store ID, task identity and a digest of its definition. A changed task goal cannot reuse the old context. Handoff has no public store ID, so this recipe binds an explicitly selected store path and run identity without claiming to authenticate a store restored at the same path.&lt;/p&gt;&lt;h2 id=&quot;let-the-producer-observe-and-yield&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Let the producer observe and yield&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;.venv/bin/python examples/continuity_starter.py --selection &amp;quot;$DEMO_ROOT/selection.json&amp;quot; produce
.venv/bin/orion-pm --json --home &amp;quot;$DEMO_ROOT/pm&amp;quot; show continuity-demo&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expect &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;state: yielded&lt;/code&gt;, PM task &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;todo&lt;/code&gt; and claim &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;absent&lt;/code&gt;. The producer has read the public test page, proved clean native browser release and client close, saved and verified an exact Handoff revision, then guarded-released its PM claim. Saving a record alone would not establish a successful yield.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The private &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;yield.json&lt;/code&gt; identifies the intended record and digest. Context observation time, synthetic acceptance claims and resource cleanup are recorded separately. Those claims simulate the recipe&amp;#x27;s accepted baseline; they are not human approval for another action.&lt;/p&gt;&lt;h2 id=&quot;continue-under-new-ownership&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Continue under new ownership&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In another terminal, select the same extracted candidate and explicitly set &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;DEMO_ROOT&lt;/code&gt; to the synthetic directory you created. Review the current request and task goal. Do not copy the producer&amp;#x27;s holder or generation.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
.venv/bin/python examples/continuity_starter.py --selection &amp;quot;$DEMO_ROOT/selection.json&amp;quot; \
  continue --yield-receipt &amp;quot;$DEMO_ROOT/yield.json&amp;quot;
.venv/bin/orion-pm --json --home &amp;quot;$DEMO_ROOT/pm&amp;quot; show continuity-demo
if ORION_BROWSER_CONFIG=&amp;quot;$DEMO_ROOT/browser.toml&amp;quot; .venv/bin/orion-browser --json status contdemo; then
  echo &amp;#x27;Unexpected running browser; inspect before proceeding.&amp;#x27; &amp;gt;&amp;amp;2
  exit 1
else
  test &amp;quot;$?&amp;quot; -eq 6
fi&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expect &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;completed&lt;/code&gt;, PM task &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;done&lt;/code&gt; with claim &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;absent&lt;/code&gt;, and the browser&amp;#x27;s expected exit 6: &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BROWSER_DOWN&lt;/code&gt;, state down/no holder. The consumer&amp;#x27;s task evidence comes from its own page observation and clean release.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The record is checked before and after the new PM claim. A newer revision is not followed silently, and an older revision is not substituted when the selected one fails. Browser ownership uses a new holder/session, independent of PM&amp;#x27;s generation. Native status reports holder, expiry and health; the session ID comes from the lease grant.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two consumers started together have one PM winner. The losing claimant makes no browser lifecycle/navigation calls. A version preflight is not evidence of resource ownership. The verification receipt includes this refusal separately from the successful continuation.&lt;/p&gt;&lt;h2 id=&quot;treat-missing-and-unknown-results-differently&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Treat missing and unknown results differently&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Profile exit&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What it establishes&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Only the named inspected, yielded or completed state&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;2&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Invalid invocation or selection&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;3&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;An established refusal&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;7&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Reconciliation is required&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Each component keeps its own result envelope and exit meanings. Handoff&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;context_available&lt;/code&gt; still carries &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;authority: none&lt;/code&gt;. Stale, incomplete, ambiguous, conflicting or mismatched context cannot authorize a browser action or mark a PM task done.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A timeout or lost result does not establish that an action was never sent. Preserve the workspace and its bounded private operation receipts. Inspect PM with its explicit home, Handoff with its explicit store and the browser with its selected configuration. Follow the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/blob/v0.2.0-rc.1/docs/runbooks/starter-continuity.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;starter recovery runbook&lt;/a&gt; before another intentional attempt. Request IDs correlate operations; they do not make them idempotent.&lt;/p&gt;&lt;h2 id=&quot;clean-up-and-keep-the-limits-visible&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Clean up and keep the limits visible&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Normal success leaves the browser down, its client closed and the expected PM claim absent. Retain any private receipts you want, then remove only the selected disposable workspace and this candidate&amp;#x27;s environments. Reconcile unknown ownership or cleanup before removal. Other profiles, accounts, task stores and OS packages remain separately managed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;PM claims coordinate cooperating clients on one host. Expiry does not stop an old process, and sequential checks do not create an atomic transaction across components or isolate hostile same-user processes. This recipe installs no hooks, scheduler, approval broker or automatic runtime migration.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-starter/blob/v0.2.0-rc.1/profiles/continuity/README.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;versioned profile walkthrough&lt;/a&gt;, MIT source and exact release artifacts remain available independently of this guide. The earlier RC2 archive is preserved rather than rewritten to fit the new profile.&lt;/p&gt;</content:encoded></item>
<item><title>Hand off a local task between agent sessions</title><link>https://www.danmercede.com/guides/hand-off-local-agent-tasks</link><guid isPermaLink="true">https://www.danmercede.com/guides/hand-off-local-agent-tasks</guid><pubDate>Sat, 17 Oct 2026 07:00:00 +0000</pubDate><description>Save explicit local task context, refuse ambiguous pickup, and preserve uncertainty with Orion Handoff.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A useful handoff says which task it belongs to, what was observed, what remains unfinished, and where its claims came from. It also lets the next session say that the information is stale or ambiguous.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;a href=&quot;https://www.danmercede.com/works/orion-handoff/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion Handoff&lt;/a&gt; is a small local CLI for that boundary. It stores immutable JSON revisions in a directory you choose. It does not install agent hooks, inspect conversations, open references, or execute recorded next steps. Every response includes &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;authority: none&lt;/code&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This walkthrough uses synthetic tasks. Its acceptance claims simulate a prior review; they are not human approval. The receiver still checks the current request, evidence, and permission to act.&lt;/p&gt;&lt;h2 id=&quot;install-a-verified-wheel&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Install a verified wheel&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use Bash, Python 3.11 or newer, and a local Linux filesystem on an x86_64 host. The demonstrated matrix is CPython 3.11 and 3.13 on WSL2 with ext4. Native Windows, network filesystems, cross-host fencing, and protection against a hostile process running as your user are outside this version&amp;#x27;s scope.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Download &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion_handoff-0.1.0-py3-none-any.whl&lt;/code&gt; from the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-handoff/releases/tag/v0.1.0&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;v0.1.0 release&lt;/a&gt; into a new directory. Start the commands below from that directory. The pinned checksum binds this guide to that wheel; stop if it differs. The wheel contains the CLI, and the generator below supplies the entire example without a source checkout.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
printf &amp;#x27;%s  %s\n&amp;#x27; \
  &amp;#x27;e1f3e1e43839cfd2896cfc553bef9366867c1cf50bce1e4d4762cdbec9977e41&amp;#x27; \
  &amp;#x27;orion_handoff-0.1.0-py3-none-any.whl&amp;#x27; | sha256sum -c -
DEMO_ROOT=$(mktemp -d &amp;quot;${TMPDIR:-/tmp}/handoff-guide.XXXXXXXX&amp;quot;)
python3 -m venv &amp;quot;$DEMO_ROOT/venv&amp;quot;
&amp;quot;$DEMO_ROOT/venv/bin/python&amp;quot; -m pip install --no-deps --no-index \
  ./orion_handoff-0.1.0-py3-none-any.whl
CLI=&amp;quot;$DEMO_ROOT/venv/bin/orion-handoff&amp;quot;
STORE=&amp;quot;$DEMO_ROOT/store&amp;quot;
PYTHON=&amp;quot;$DEMO_ROOT/venv/bin/python&amp;quot;
export DEMO_ROOT CLI STORE PYTHON
&amp;quot;$CLI&amp;quot; --json --version
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json init
printf &amp;#x27;A synthetic draft heading\n&amp;#x27; &amp;gt; &amp;quot;$DEMO_ROOT/draft.txt&amp;quot;
printf &amp;#x27;DEMO_ROOT=%q\nCLI=%q\nSTORE=%q\nPYTHON=%q\nexport DEMO_ROOT CLI STORE PYTHON\n&amp;#x27; \
  &amp;quot;$DEMO_ROOT&amp;quot; &amp;quot;$CLI&amp;quot; &amp;quot;$STORE&amp;quot; &amp;quot;$PYTHON&amp;quot; &amp;gt; &amp;quot;$DEMO_ROOT/session.env&amp;quot;
chmod 600 &amp;quot;$DEMO_ROOT/session.env&amp;quot;
printf &amp;#x27;For the second session, run: source %q\n&amp;#x27; &amp;quot;$DEMO_ROOT/session.env&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--version&lt;/code&gt; reports package &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;0.1.0&lt;/code&gt; and interface/store/record version &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;1&lt;/code&gt;. Initialization returns &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;code: initialized&lt;/code&gt;, exit 0. The explicit store is new and private; this does not select any agent&amp;#x27;s existing state. Leave this terminal open for the producer steps.&lt;/p&gt;&lt;h2 id=&quot;session-one-record-an-observation&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Session one: record an observation&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The generator actually reads and hashes the synthetic draft each time it runs, then records that observation time. It does not refresh timestamps on old evidence. The &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;sample://&lt;/code&gt; references are labels for this demonstration; the CLI never follows them.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;cat &amp;gt; &amp;quot;$DEMO_ROOT/make-record.py&amp;quot; &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
from datetime import datetime, timezone
import hashlib
import json
import os
from pathlib import Path
import sys

task = sys.argv[1]
predecessor = sys.argv[2] if len(sys.argv) &amp;gt; 2 else None
status = sys.argv[3] if len(sys.argv) &amp;gt; 3 else &amp;quot;active&amp;quot;
draft = (Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;]) / &amp;quot;draft.txt&amp;quot;).read_bytes()
observed = datetime.now(timezone.utc).isoformat().replace(&amp;quot;+00:00&amp;quot;, &amp;quot;Z&amp;quot;)
print(json.dumps({
    &amp;quot;record_version&amp;quot;: 1, &amp;quot;task_key&amp;quot;: task, &amp;quot;project_key&amp;quot;: &amp;quot;sample-project&amp;quot;,
    &amp;quot;predecessor&amp;quot;: predecessor, &amp;quot;title&amp;quot;: &amp;quot;Synthetic draft &amp;quot; + task,
    &amp;quot;status&amp;quot;: status, &amp;quot;actor&amp;quot;: &amp;quot;demo-producer&amp;quot;, &amp;quot;request_id&amp;quot;: &amp;quot;demo-&amp;quot; + task,
    &amp;quot;context_as_of&amp;quot;: observed,
    &amp;quot;last_observed_outcome&amp;quot;: &amp;quot;Read the synthetic heading&amp;quot;,
    &amp;quot;unfinished_step&amp;quot;: &amp;quot;Review the remaining paragraphs&amp;quot;,
    &amp;quot;recorded_next_step&amp;quot;: &amp;quot;Check the current request before editing&amp;quot;,
    &amp;quot;remaining_authority&amp;quot;: &amp;quot;None granted by this record&amp;quot;,
    &amp;quot;acceptance_claims&amp;quot;: [{&amp;quot;baseline&amp;quot;: &amp;quot;synthetic-baseline-&amp;quot; + task,
        &amp;quot;reference&amp;quot;: &amp;quot;sample://simulated-review/&amp;quot; + task, &amp;quot;accepted_at&amp;quot;: observed}],
    &amp;quot;evidence&amp;quot;: [{&amp;quot;source&amp;quot;: &amp;quot;synthetic draft&amp;quot;, &amp;quot;artifact&amp;quot;: hashlib.sha256(draft).hexdigest(),
        &amp;quot;observed_at&amp;quot;: observed, &amp;quot;scope&amp;quot;: &amp;quot;Heading bytes only&amp;quot;,
        &amp;quot;reference&amp;quot;: &amp;quot;sample://draft/heading&amp;quot;}],
    &amp;quot;body&amp;quot;: &amp;quot;Synthetic context. Recheck the draft before editing.&amp;quot;
}))
PY
&amp;quot;$PYTHON&amp;quot; &amp;quot;$DEMO_ROOT/make-record.py&amp;quot; alpha &amp;gt; &amp;quot;$DEMO_ROOT/alpha.json&amp;quot;
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json record --input - \
  &amp;lt; &amp;quot;$DEMO_ROOT/alpha.json&amp;quot; &amp;gt; &amp;quot;$DEMO_ROOT/alpha-receipt.json&amp;quot;
&amp;quot;$PYTHON&amp;quot; - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json, os
from pathlib import Path
receipt = json.loads((Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;]) / &amp;quot;alpha-receipt.json&amp;quot;).read_text())
assert receipt[&amp;quot;code&amp;quot;] == &amp;quot;recorded&amp;quot; and receipt[&amp;quot;authority&amp;quot;] == &amp;quot;none&amp;quot;
print(&amp;quot;Saved alpha:&amp;quot;, receipt[&amp;quot;data&amp;quot;][&amp;quot;record_id&amp;quot;])
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A successful write exits 0 and returns the generated &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;record_id&lt;/code&gt; and the stored byte hash. Task key, record ID, producer identity, request ID, and project key are separate fields. A later revision must name the current record as its predecessor.&lt;/p&gt;&lt;h2 id=&quot;session-two-pick-the-exact-task&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Session two: pick the exact task&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In another terminal, run the &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;source&lt;/code&gt; command printed during setup. It restores only variables from the file this walkthrough created. You can also continue in the first terminal. Keep using that same &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;CLI&lt;/code&gt; and absolute &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;STORE&lt;/code&gt; path in either session.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;set -euo pipefail
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json pickup --task alpha &amp;gt; &amp;quot;$DEMO_ROOT/pickup.json&amp;quot;
&amp;quot;$PYTHON&amp;quot; - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json, os
from pathlib import Path
root = Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;])
picked = json.loads((root / &amp;quot;pickup.json&amp;quot;).read_text())
written = json.loads((root / &amp;quot;alpha-receipt.json&amp;quot;).read_text())
assert picked[&amp;quot;code&amp;quot;] == &amp;quot;context_available&amp;quot;
assert picked[&amp;quot;data&amp;quot;][&amp;quot;selected_record_id&amp;quot;] == written[&amp;quot;data&amp;quot;][&amp;quot;record_id&amp;quot;]
assert picked[&amp;quot;authority&amp;quot;] == &amp;quot;none&amp;quot;
assert picked[&amp;quot;data&amp;quot;][&amp;quot;reference_check&amp;quot;] == &amp;quot;not_performed&amp;quot;
print(&amp;quot;Exact task selected; references unchecked; authority:&amp;quot;, picked[&amp;quot;authority&amp;quot;])
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Within the default 24-hour age window, this fresh complete example exits 0 with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;match: task&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;integrity: valid&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;recency: within_window&lt;/code&gt;, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;acceptance: recorded&lt;/code&gt;. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;context_available&lt;/code&gt; means the record meets those checks. Its baseline is still a recorded claim. It does not grant approval, validate a reference, reserve a browser or phone, or claim a PM task. Those remain separate checks at their owning tools.&lt;/p&gt;&lt;h2 id=&quot;add-a-second-task-and-refuse-ambiguity&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Add a second task and refuse ambiguity&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A project is a grouping, not a task selector. Two active tasks in the same project must not silently choose whichever was saved most recently.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;&amp;quot;$PYTHON&amp;quot; &amp;quot;$DEMO_ROOT/make-record.py&amp;quot; beta &amp;gt; &amp;quot;$DEMO_ROOT/beta.json&amp;quot;
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json record --input - &amp;lt; &amp;quot;$DEMO_ROOT/beta.json&amp;quot;
status=0
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json pickup --project sample-project --resume \
  &amp;gt; &amp;quot;$DEMO_ROOT/ambiguous.json&amp;quot; || status=$?
test &amp;quot;$status&amp;quot; -eq 11
&amp;quot;$PYTHON&amp;quot; - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json, os
from pathlib import Path
result = json.loads((Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;]) / &amp;quot;ambiguous.json&amp;quot;).read_text())
assert result[&amp;quot;code&amp;quot;] == &amp;quot;ambiguous&amp;quot; and result[&amp;quot;data&amp;quot;][&amp;quot;record&amp;quot;] is None
print(&amp;quot;Ambiguous project refused; exit 11&amp;quot;)
PY
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json pickup --task alpha&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The project pickup exits 11 and returns no selected record. The final exact-task pickup still selects alpha. The shell captures the expected nonzero exit instead of stopping under &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;set -e&lt;/code&gt;.&lt;/p&gt;&lt;h2 id=&quot;record-a-stale-successor&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Record a stale successor&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A successor is a complete new record. Marking it stale does not revive the earlier fresh context.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ALPHA_ID=$(&amp;quot;$PYTHON&amp;quot; -c &amp;#x27;import json,sys; print(json.load(open(sys.argv[1]))[&amp;quot;data&amp;quot;][&amp;quot;record_id&amp;quot;])&amp;#x27; \
  &amp;quot;$DEMO_ROOT/alpha-receipt.json&amp;quot;)
&amp;quot;$PYTHON&amp;quot; &amp;quot;$DEMO_ROOT/make-record.py&amp;quot; alpha &amp;quot;$ALPHA_ID&amp;quot; stale &amp;gt; &amp;quot;$DEMO_ROOT/stale.json&amp;quot;
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json record --input - \
  &amp;lt; &amp;quot;$DEMO_ROOT/stale.json&amp;quot; &amp;gt; &amp;quot;$DEMO_ROOT/stale-receipt.json&amp;quot;
status=0
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json pickup --task alpha \
  &amp;gt; &amp;quot;$DEMO_ROOT/stale-pickup.json&amp;quot; || status=$?
test &amp;quot;$status&amp;quot; -eq 10
&amp;quot;$PYTHON&amp;quot; - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json, os
from pathlib import Path
root = Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;])
picked = json.loads((root / &amp;quot;stale-pickup.json&amp;quot;).read_text())
written = json.loads((root / &amp;quot;stale-receipt.json&amp;quot;).read_text())
assert picked[&amp;quot;code&amp;quot;] == &amp;quot;inspect_only&amp;quot;
assert picked[&amp;quot;data&amp;quot;][&amp;quot;selected_record_id&amp;quot;] == written[&amp;quot;data&amp;quot;][&amp;quot;record_id&amp;quot;]
assert picked[&amp;quot;data&amp;quot;][&amp;quot;continuation&amp;quot;] is None
print(&amp;quot;Stale successor selected; no continuation; exit 10&amp;quot;)
PY
&amp;quot;$CLI&amp;quot; --store &amp;quot;$STORE&amp;quot; --json show &amp;quot;$ALPHA_ID&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Pickup exits 10. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;show&lt;/code&gt; can inspect the older alpha record, but reports &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;current: false&lt;/code&gt;. Unknown or future observation times, incomplete or conflicting acceptance claims, and insufficient evidence also prevent continuation. A corrupt committed record blocks selection with exit 74; it does not cause an older-record fallback.&lt;/p&gt;&lt;h2 id=&quot;back-up-and-validate-a-restored-copy&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Back up and validate a restored copy&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Stop all cooperating readers and writers before copying a store. In this walkthrough, wait for both terminals&amp;#x27; commands to finish and leave them idle. Copy the whole directory, including the version marker and lock file, preserving modes and hard links. Do not delete a lock file to break an active lock.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;cp -a &amp;quot;$STORE&amp;quot; &amp;quot;$DEMO_ROOT/backup&amp;quot;
cp -a &amp;quot;$DEMO_ROOT/backup&amp;quot; &amp;quot;$DEMO_ROOT/restored&amp;quot;
&amp;quot;$PYTHON&amp;quot; - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import hashlib, os, stat
from pathlib import Path
root = Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;])
def snapshot(folder):
    return {str(p.relative_to(folder)): (stat.S_IMODE(p.stat().st_mode),
        hashlib.sha256(p.read_bytes()).hexdigest() if p.is_file() else None)
        for p in [folder, *folder.rglob(&amp;quot;*&amp;quot;)]}
assert snapshot(Path(os.environ[&amp;quot;STORE&amp;quot;])) == snapshot(root / &amp;quot;restored&amp;quot;)
print(&amp;quot;Restored bytes and modes match&amp;quot;)
PY
status=0
&amp;quot;$CLI&amp;quot; --store &amp;quot;$DEMO_ROOT/restored&amp;quot; --json pickup --task alpha \
  &amp;gt; &amp;quot;$DEMO_ROOT/restored-pickup.json&amp;quot; || status=$?
test &amp;quot;$status&amp;quot; -eq 10
&amp;quot;$PYTHON&amp;quot; - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json, os
from pathlib import Path
root = Path(os.environ[&amp;quot;DEMO_ROOT&amp;quot;])
original = json.loads((root / &amp;quot;stale-pickup.json&amp;quot;).read_text())
restored = json.loads((root / &amp;quot;restored-pickup.json&amp;quot;).read_text())
assert restored[&amp;quot;data&amp;quot;][&amp;quot;selected_record_id&amp;quot;] == original[&amp;quot;data&amp;quot;][&amp;quot;selected_record_id&amp;quot;]
assert restored[&amp;quot;data&amp;quot;][&amp;quot;continuation&amp;quot;] is None
print(&amp;quot;Restored pickup preserves the stale successor&amp;quot;)
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the original until the restored copy is validated. If a write returns &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;commit_unknown&lt;/code&gt; with exit 74, preserve its &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;candidate_record_id&lt;/code&gt;, inspect it with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;show&lt;/code&gt; and inspect the current task with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;pickup&lt;/code&gt; before considering another write. A failed acknowledgement can follow a committed record. Do not blindly resend.&lt;/p&gt;&lt;h2 id=&quot;keep-the-boundary-small&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep the boundary small&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The store retains historical, stale, and completed records. There is no automatic deletion or migration. Version 0.1 limits committed records to 512, input records to 64 KiB, and body text to 16 KiB; a reached limit refuses work rather than silently removing history. Preserve a complete store before retiring it and deliberately starting another one.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Uninstalling the package leaves the selected store in place. To end the demonstration, stop its processes and retain or remove only the scratch directory printed during setup. Existing agent configuration and stores were never selected.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use &lt;a href=&quot;https://www.danmercede.com/works/orion-pm/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Orion PM&lt;/a&gt; for task coordination and the &lt;a href=&quot;https://www.danmercede.com/works/orion-browser/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;browser pool&lt;/a&gt; or &lt;a href=&quot;https://www.danmercede.com/works/orion-phone/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;phone pool&lt;/a&gt; for resource leases. Handoff supplies recorded context; each executor still checks its own current request and action authority. The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-handoff/blob/main/docs/runbooks/local-handoff-store.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;source and recovery runbook&lt;/a&gt; describe the supported store and recovery boundaries.&lt;/p&gt;</content:encoded></item>
<item><title>Give your AI agent its own Android phone</title><link>https://www.danmercede.com/guides/agent-android-phones</link><guid isPermaLink="true">https://www.danmercede.com/guides/agent-android-phones</guid><pubDate>Thu, 15 Oct 2026 07:00:00 +0000</pubDate><description>How to give AI agents Android phones of their own with the MIT-licensed orion-phone CLI and MCP server: one agent per phone, a screen read as text, an audit record of every action, and a locked tier that waits for unlock on a trusted host.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two agents were taking turns with one browser, badly. One navigated away while the other filled a form. And some of the work had nowhere to go at all: the app only existed on a phone.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The obvious fix was the wrong one. Give an agent your own phone and everything on it is in reach: every account, every code, every message.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our answer was &lt;strong class=&quot;font-semibold text-white&quot;&gt;orion-phone&lt;/strong&gt;: a CLI and an MCP server that run Android phones (emulators) for agents. An agent leases a phone, reads its screen as text, taps, types and opens apps, and every action leaves an audit record with a screenshot. The phones are signed in to the accounts you choose. A phone in the locked tier does nothing until you unlock it yourself.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This guide walks through that setup with neutral apps: Settings and Clock. The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-phone-oss&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;MIT-licensed source&lt;/a&gt; carries the implementation, the tests, the example config, the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-phone-oss/blob/main/SECURITY.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;security model&lt;/a&gt; and the operations runbook. The &lt;a href=&quot;https://www.danmercede.com/works/orion-phone/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Works page&lt;/a&gt; is the short version, and the &lt;a href=&quot;https://www.danmercede.com/guides/multi-agent-browser-pool&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;browser pool guide&lt;/a&gt; covers the sibling problem for Chrome.&lt;/p&gt;&lt;h2 id=&quot;what-does-an-agent-get-when-it-leases-a-phone&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does an agent get when it leases a phone?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In orion-phone 0.2.0, a lease gives one agent session sole use of one phone for 30 minutes by default, renewed by each lease call and action. A second agent asking for the same phone is told who holds it and until when. Every action the holder takes writes an audit line, and every successful one a screenshot.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A &lt;strong class=&quot;font-semibold text-white&quot;&gt;phone&lt;/strong&gt; is a named Android emulator, such as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;a&lt;/code&gt;. Its &lt;strong class=&quot;font-semibold text-white&quot;&gt;tier&lt;/strong&gt; decides how it runs. An &lt;strong class=&quot;font-semibold text-white&quot;&gt;open&lt;/strong&gt; phone runs in the background as a systemd user service, started at login and restarted after a crash, ready for any agent that leases it. A &lt;strong class=&quot;font-semibold text-white&quot;&gt;locked&lt;/strong&gt; phone never starts on its own; a lease boots it, and it does nothing until its owner unlocks it on its own screen. A &lt;strong class=&quot;font-semibold text-white&quot;&gt;holder&lt;/strong&gt; is the agent session that owns the current &lt;strong class=&quot;font-semibold text-white&quot;&gt;lease&lt;/strong&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;What that means in practice:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Different phones work in parallel, one holder each.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two holders asking for the same phone are serialized by the lease.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Releasing an open phone leaves it running for the next holder. Releasing a locked phone shuts it down.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/agent-android-phones/architecture.webp&quot; alt=&quot;Cooperating agents reach phones through orion-phone, which holds the leases and writes the audit trail; open phones run as services, a locked phone boots only for a lease.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Leases and the audit trail live in orion-phone. The MCP server calls the same CLI an agent can run from a shell.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The CLI is the single authority: the MCP server mirrors its commands and calls it. The boundary matters, so the README says it plainly: &lt;strong class=&quot;font-semibold text-white&quot;&gt;leases coordinate agents; they are not a sandbox.&lt;/strong&gt; An agent that holds an open phone can do there whatever its accounts allow.&lt;/p&gt;&lt;h2 id=&quot;what-do-you-need-before-the-first-phone-boots&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What do you need before the first phone boots?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;orion-phone 0.2.0 runs on Linux with systemd user services (version 250 or later) and KVM, or on Windows through WSL2 with nested virtualization. It needs Python 3.11 or later, Java 17 or later, and Google&amp;#x27;s Android command-line tools version 23 or later; setup downloads the system image and the rest of the SDK.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Unzip the command-line tools so that &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/Android/Sdk/cmdline-tools/latest/bin/sdkmanager&lt;/code&gt; exists. Then:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;uv tool install &amp;#x27;orion-phone==0.2.0&amp;#x27;  # or: pipx install orion-phone
orion-phone init                      # writes ~/.config/orion-phone/config.toml
# read and accept the Android SDK License yourself before setup:
#   https://developer.android.com/studio/terms
orion-phone setup                     # SDK packages, phones, systemd user units; starts open phones
orion-phone status a                  # exits 0 once the first boot finishes&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;setup&lt;/code&gt; from a desktop shell: a locked phone needs a display, because its owner unlocks it in its own window. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;init&lt;/code&gt; writes the example config, owner-only, and refuses to replace anything already at that path. This excerpt shows one phone of each tier:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;toml&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-toml&quot;&gt;[android]
system_image = &amp;quot;system-images;android-36;google_apis_playstore;x86_64&amp;quot;
device = &amp;quot;pixel_7&amp;quot;
ram_mb = 4096

[lease]
ttl_minutes = 30

[phones.a]
tier = &amp;quot;open&amp;quot;
console_port = 5554

[phones.b]
tier = &amp;quot;locked&amp;quot;
console_port = 5556
session_cap_minutes = 120&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Edit it between &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;init&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;setup&lt;/code&gt; to add, remove or rename phones. Each phone&amp;#x27;s data lives in the Android tools&amp;#x27; AVD home, outside any Git repository; orion-phone refuses a config, state directory or AVD home inside one.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Sign in to accounts by hand, on the phone&amp;#x27;s own screen, and keep credentials out of agent messages and files. Text an agent types is stored verbatim in the audit trail on success, so an agent should never type a password.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-connect-claude-code-or-codex&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you connect Claude Code or Codex?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;orion-phone 0.2.0 ships an MCP server, the &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-phone-mcp&lt;/code&gt; command, over stdio. Its tools mirror the CLI: status, lease, release, ui, shot, tap, type, swipe, key and open. Each server process is one lease holder, which decides how subagents should share phones.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;claude mcp add --scope user orion-phone -- orion-phone-mcp&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For Codex, add it to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.codex/config.toml&lt;/code&gt;:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;toml&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-toml&quot;&gt;[mcp_servers.orion-phone]
command = &amp;quot;orion-phone-mcp&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Any other MCP client takes the same command.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The ownership detail: &lt;strong class=&quot;font-semibold text-white&quot;&gt;everything that talks through one server process is one holder.&lt;/strong&gt; Two subagents leasing the same phone through it share that lease; neither gets &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BUSY&lt;/code&gt;. Give parallel subagents different phones, or have each use the CLI with a holder name of its own.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;From a shell, a holder name identifies one agent session. Pass it with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--holder&lt;/code&gt;, or set &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ORION_PHONE_HOLDER&lt;/code&gt; for that session only. Never put &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ORION_PHONE_HOLDER&lt;/code&gt; in a harness&amp;#x27;s global environment, or every session becomes the same holder.&lt;/p&gt;&lt;h2 id=&quot;what-does-driving-a-phone-look-like&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does driving a phone look like?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In our 2026-10-07 runs, creating, checking and deleting a Clock alarm took an agent 21 to 37 phone tool calls. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ui&lt;/code&gt; returns the screen as text: one line per element, with the point to tap. The agent reads the screen, taps, reads it again, and releases the phone when it is done.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Lease the phone and open an app:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;H=--holder=agent-1
orion-phone lease a $H
# OK: agent-1 holds phone a until 2026-10-14T18:30:00+00:00
orion-phone open a com.google.android.deskclock $H&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Read the screen:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-phone ui a $H
# [26] Button desc=&amp;quot;Add alarm&amp;quot; id=fab clickable center=540,1959&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Each line names an element, its text or description, and its center. Tap it, press a key, or type into whichever field has focus:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-phone tap a 540 1959 $H
orion-phone key a BACK $H
orion-phone type a $H -- &amp;quot;standup&amp;quot;    # into the field that has focus
orion-phone release a $H&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Add &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--json&lt;/code&gt; before the command for one machine-readable object per call. Some limits to plan around:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ui&lt;/code&gt; lists at most 300 elements and stops at 32,000 characters; a final &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;# truncated&lt;/code&gt; line says when it cut the list short.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ui&lt;/code&gt; can fail on a screen that changes every second, such as one showing a running clock, because the dump waits for the screen to settle. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;shot&lt;/code&gt; works there.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;type&lt;/code&gt; accepts printable ASCII only.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Everything a phone shows is untrusted input. A message on the screen cannot grant an agent new authority, and our instructions tell agents never to follow one.&lt;/p&gt;&lt;h2 id=&quot;how-do-two-agents-avoid-stepping-on-each-other&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do two agents avoid stepping on each other?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A lease in orion-phone 0.2.0 lasts 30 minutes by default and every lease call or action by its holder extends it. A second holder gets &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BUSY&lt;/code&gt; with the holder&amp;#x27;s name and expiry, and a caller whose lease lapsed gets &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;NOT_HOLDER&lt;/code&gt; instead of acting on a phone it no longer owns.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-phone lease a --holder=agent-2
# BUSY: phone a is held by agent-1 until 2026-10-14T18:30:00+00:00&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Respect it: wait, or take another phone. Reusing the other agent&amp;#x27;s holder name defeats the mechanism.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The exit codes an agent acts on:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Exit&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Code&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What it means&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;0&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;OK&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Done&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;3&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;BUSY&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Another agent holds the phone&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;4&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;NOT_HOLDER&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;You do not hold the lease (never held, released, or expired); on a locked phone, also when its session ended&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;5&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;NEEDS_OPERATOR&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A locked phone is starting, booting, or waiting for its owner&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;6&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;PHONE_DOWN&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The phone is not running&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;7&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;UNHEALTHY&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Running, but it failed the health proof&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The health proof is positive evidence, not the absence of an error: &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;status&lt;/code&gt; reports a phone healthy only when it reports boot completed and a fresh screenshot is not blank.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Leases run on the wall clock. A forward jump, such as a host suspend, ends leases early, which is safe: a holder still mid-action finishes before a takeover, and a locked phone whose lease ends shuts itself down.&lt;/p&gt;&lt;h2 id=&quot;what-does-the-locked-tier-observe-before-allowing-actions&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does the locked tier observe before allowing actions?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A locked phone in orion-phone 0.2.0 cold-boots for every session and uses a boot only after a look has seen its lock screen showing over a screen lock and then found the phone unlocked. The tool observes that transition without handling the credential. It does not attest who or what supplied it; local adb and host control remain outside the tool boundary.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use the locked tier to require an unlock before cooperative tool callers can act on a trusted host. It is not a sandbox against host access:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It never starts on its own. A lease boots it, and the reply is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;NEEDS_OPERATOR&lt;/code&gt; with a state: &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;starting&lt;/code&gt; or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;booting&lt;/code&gt; (lease again shortly, and do not unlock yet), &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;locked&lt;/code&gt; (the owner unlocks it on its screen), &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;no-screen-lock&lt;/code&gt; (the owner sets a PIN first), &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;restart-needed&lt;/code&gt; (lease again, which restarts the phone), or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;unknown&lt;/code&gt; (its lock state could not be read: lease again).&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It shuts down when its session is released, about 45 seconds after its lease lapses (later by up to 3 minutes if an action is still running), and at a hard session cap (&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;session_cap_minutes&lt;/code&gt;, 120 in the example).&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It runs only a Google Play image whose build reports file-based encryption and is not debuggable, and it shuts down any other.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Its emulator runs with core dumps off, so a crash leaves no copy of the phone&amp;#x27;s memory on disk.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/agent-android-phones/locked-tier.webp&quot; alt=&quot;A locked phone&amp;#x27;s boot is used only after a look has seen its lock screen over a screen lock and then found the phone unlocked.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;The sighting at the lock screen is the evidence. A boot seen with no screen lock is never used, even after a PIN is set during it.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The first boot shows the rule at work. The first lease answers &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;starting&lt;/code&gt;; lease again until the reply is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;no-screen-lock&lt;/code&gt;, because a new phone has no screen lock. The owner sets a PIN in the phone&amp;#x27;s own window. The next lease does not use that boot: that boot was already unlocked when the PIN was set, and it had previously been seen with no screen lock. It restarts the phone and answers &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;starting&lt;/code&gt; again. Lease again until the reply is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;locked&lt;/code&gt;, and then the owner unlocks it by hand.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Independent verification that credential-encrypted storage remains sealed before first unlock on the pinned image is still open as Q2. Android also has device-encrypted storage that can be available during Direct Boot. The synthetic lock-screen test proves tool refusals and transitions, not storage sealing. See the &lt;a href=&quot;https://source.android.com/docs/security/features/encryption/file-based&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Android encryption documentation&lt;/a&gt; and the tool&amp;#x27;s &lt;a href=&quot;https://github.com/OrionArchitekton/orion-phone-oss/blob/main/SECURITY.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;security model&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The tool gates when a cooperative holder can act, not what it can read afterwards. A &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ui&lt;/code&gt; dump reads every screen&amp;#x27;s text, including one an app marks as secure and a screenshot shows black. Keep off a locked phone what you would not let the holder of an unlocked session read.&lt;/p&gt;&lt;h2 id=&quot;what-does-every-action-leave-behind&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What does every action leave behind?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Every action by a lease holder in orion-phone 0.2.0 writes an audit line to an owner-only state directory outside any repository, and every successful one a screenshot. A caller without the lease is refused before anything reaches the phone or the record, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ui&lt;/code&gt; also keeps the screen&amp;#x27;s UI dump.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The record is built so that it does not become a second leak. Text an agent types is stored verbatim only when the action succeeds; a refused or failed action keeps only the text&amp;#x27;s length, so a PIN tried at a lock screen never reaches disk. A refusal that waits for the owner records its state, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;locked&lt;/code&gt; or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;no-screen-lock&lt;/code&gt; among them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The audit trail explains who held a phone and what they did. It does not judge whether what they did was right.&lt;/p&gt;&lt;h2 id=&quot;what-did-it-cost-an-agent-to-do-real-tasks&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What did it cost an agent to do real tasks?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-07 we ran six fresh Claude Code sessions on Claude Opus 5.5, three per task, and published every run. Reading the Android version and storage used in Settings cost $0.20 to $0.38 a run; creating, checking and deleting a labeled alarm in Clock cost $0.33 to $0.46. All six succeeded.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;These are the six source measurements recorded on 2026-10-07, not results from the later synthetic acceptance test. The details that move the numbers:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Cost is the whole session as Claude Code reports it, its own system prompt and tool definitions included. The runs went back to back, so the prompt cache was warm; a run with a cold cache costs about $0.18 more.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Settings&amp;#x27; About page shows a running uptime counter, so &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ui&lt;/code&gt; failed there in two of the three runs and the agent switched to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;shot&lt;/code&gt;, about 25 seconds per failed call.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The costliest alarm run spent 15 of its 37 calls typing a time that did not take, before it used the clock dial.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An earlier batch the same day lost one alarm run to the crash described in the next section; the published batch ran after the fix. The README lists every run.&lt;/p&gt;&lt;h2 id=&quot;what-breaks-and-how-do-you-keep-phones-running&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What breaks, and how do you keep phones running?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On 2026-10-07 an open phone crashed mid-task: the WSL2 desktop&amp;#x27;s compositor aborted in its clipboard bridge, a known WSLg bug, and took every Linux window with it. The phone came back from a quick-boot snapshot that also rolled its disk back. orion-phone 0.2.0 cold-boots every phone so that cannot happen.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The chain, from the host&amp;#x27;s logs, is worth knowing if you run phones under WSL2:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;WSLg&amp;#x27;s compositor hit an assertion in its clipboard code (&lt;a href=&quot;https://github.com/microsoft/wslg/issues/1407&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;microsoft/wslg#1407&lt;/a&gt;), which the emulator&amp;#x27;s clipboard sharing sets off. The display server went with it.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The emulator lost its display and crashed.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It wrote a multi-gigabyte core dump of the phone&amp;#x27;s memory before its service could restart it.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;It restarted from its quick-boot snapshot, which holds the phone&amp;#x27;s disks as well as its memory, so work done since that save was gone.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The fixes, in order of who owns them. Turn off the emulator&amp;#x27;s clipboard sharing with no phone running: &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;clipboardSharing=false&lt;/code&gt; in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.config/Android Open Source Project/Emulator.conf&lt;/code&gt;. orion-phone 0.2.0 starts every phone without snapshots, deletes old ones at launch, and sets the core limit that keeps a crash from dumping the phone&amp;#x27;s memory. After an upgrade, run &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-phone setup&lt;/code&gt; (or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;install-units&lt;/code&gt;) and then restart each open phone once, so the running emulator picks that up.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;To watch a phone over Remote Desktop or WSL2, mirror it with scrcpy rather than relying on the emulator&amp;#x27;s own window. The runbook&amp;#x27;s &amp;quot;Viewing a phone&amp;quot; section has the setup. Never close a phone&amp;#x27;s window: the window is the emulator.&lt;/p&gt;&lt;h2 id=&quot;where-are-the-limits&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Where are the limits?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;orion-phone 0.2.0 coordinates cooperative agents on a host you trust; it does not defend against a malicious process on that host. The Android debug bridge&amp;#x27;s server on loopback port 5037 takes commands from any local process without a lease, so such a process can do to a phone what orion-phone does, with no audit record.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-phone-oss/blob/main/SECURITY.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;security model&lt;/a&gt; lists what is defended and what is not. The items that matter most before signing in to anything:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An agent that reads untrusted content and holds an open phone&amp;#x27;s lease can post or send as you. orion-phone records it; it does not prevent it.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;What an agent may publish is a decision outside the lease. Our agents may post or send only when the request for that session asks for it, after the same redaction and style checks we run before any post.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The emulator shares your host clipboard with every phone unless you turn that off.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Real Android devices, iPhone and macOS hosts are on the roadmap, and open to contributors.&lt;/p&gt;&lt;h2 id=&quot;how-do-you-verify-a-setup-before-giving-it-real-work&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;How do you verify a setup before giving it real work?&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;From a checkout, create and activate a Python 3.11+ virtual environment. Run &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;python -m pip install --require-hashes --force-reinstall -r bootstrap-requirements.txt&lt;/code&gt;, then &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;python -m pip install -e &amp;#x27;.[dev]&amp;#x27;&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;python -m pytest -q&lt;/code&gt;. The full suite has over 2,500 tests in 0.2.0, against fake adb and systemd: no emulator, no accounts. Then prove each phone end to end with one small task, and read its audit record afterwards.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-phone status a
H=--holder=setup-check
orion-phone lease a $H
orion-phone open a com.google.android.deskclock $H
orion-phone ui a $H
orion-phone release a $H&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The audit record is one file per UTC day, under &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.local/state/orion-phone/audit/&amp;lt;phone&amp;gt;/&lt;/code&gt;. For a locked phone, follow &amp;quot;First boot of a locked phone&amp;quot; in the runbook before signing in to anything. Then run one small task per phone: confirm the right phone and account, verify the result on the screen, and release the lease. That last check is what turns a running emulator into finished work.&lt;/p&gt;</content:encoded></item>
<item><title>Coordinate two local agents with Orion PM</title><link>https://www.danmercede.com/guides/coordinate-local-agents-with-orion-pm</link><guid isPermaLink="true">https://www.danmercede.com/guides/coordinate-local-agents-with-orion-pm</guid><pubDate>Thu, 15 Oct 2026 07:00:00 +0000</pubDate><description>A practical Orion PM tutorial: run two workers against one local task store, retain claim generations and revisions, attach evidence, and hand unfinished work back safely.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Separate chats do not create separate ownership. Two agents can read the same task list, decide the work is available, and both begin editing. A status field that says &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;in_progress&lt;/code&gt; tells you what the record says. It does not tell you which worker can still change it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Orion PM&lt;/strong&gt; is a small, local coordination CLI for cooperating agents. A worker claims a task before doing the work, keeps the exact claim generation and task revision, and uses those handles to attach evidence, finish, or hand the task back. A later worker receives a different generation, even when it reuses the same holder name.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The core uses only the Python standard library at runtime and is prepared under MIT. The &lt;a href=&quot;https://www.danmercede.com/works/orion-pm/&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Works overview&lt;/a&gt; gives the short explanation. Download the v0.1.1 wheel and matching &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;SHA256SUMS&lt;/code&gt; from the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-pm-oss/releases/tag/v0.1.1&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;GitHub release&lt;/a&gt;. The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-pm-oss&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;orion-pm-oss source&lt;/a&gt; includes the core contract, examples and local-store runbook. You do not need a hosted PM service or a package-index download.&lt;/p&gt;&lt;h2 id=&quot;three-owners-three-different-jobs&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Three owners, three different jobs&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A &lt;strong class=&quot;font-semibold text-white&quot;&gt;task claim&lt;/strong&gt; coordinates which cooperating worker owns a piece of work. A &lt;strong class=&quot;font-semibold text-white&quot;&gt;resource lease&lt;/strong&gt; coordinates a browser, phone, or another tool&amp;#x27;s resource. &lt;strong class=&quot;font-semibold text-white&quot;&gt;Permission&lt;/strong&gt; determines whether an action such as publishing, deploying, merging, spending, or using an account is allowed.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/orion-pm/ownership-boundaries.webp&quot; alt=&quot;Two workers compete for one PM task claim; the winner separately uses a native resource lease and follows the caller&amp;#x27;s action permissions.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;PM coordinates the task. Each tool keeps its resource lease. The caller retains the action-permission boundary.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;PM does the first job. It does not replace the other two. Finishing a PM task does not approve a deployment. Releasing a PM task does not close Chrome. An expired claim does not stop a process that is still running.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That separation keeps the core useful on its own and lets it fit into a larger system later. A command-line coding agent, a browser workflow, or a supervised desktop tool can use the same PM interface without adopting a shared daemon or a new permissions broker.&lt;/p&gt;&lt;h2 id=&quot;start-in-an-isolated-local-folder&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Start in an isolated local folder&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The observed support row is CPython 3.11.14 on WSL2 Linux with ext4. The package accepts Python 3.11+, but other interpreter and operating-system combinations need their own installed-artifact validation. Native Windows/macOS, network or synchronized storage, cross-host fencing, and hostile processes running as the same OS user are outside the established support boundary.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Place the reviewed &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion_pm-0.1.1-py3-none-any.whl&lt;/code&gt; and its matching &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;SHA256SUMS&lt;/code&gt; in an empty working folder. The first commands check the manifest against the recorded v0.1.1 digest, select its exact wheel entry, and verify the wheel bytes. A missing wheel entry or failed check stops the install before creating the environment. The check must report the wheel as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;OK&lt;/code&gt;; pip checks that selected digest again during installation. A version label alone does not identify the artifact bytes.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run the following commands in one shell, from that folder:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;umask 077
printf &amp;#x27;%s\n&amp;#x27; &amp;#x27;1aa321ef138359e8fe6cff11d9ed43c3950ca559a5bda91e854144a4908be92b  SHA256SUMS&amp;#x27; | sha256sum --strict --check - &amp;amp;&amp;amp;
awk &amp;#x27;$2 == &amp;quot;orion_pm-0.1.1-py3-none-any.whl&amp;quot; {print; found=1} END {exit !found}&amp;#x27; SHA256SUMS &amp;gt; wheel.sha256 &amp;amp;&amp;amp;
sha256sum --strict --check wheel.sha256 &amp;amp;&amp;amp;
awk &amp;#x27;{print &amp;quot;./&amp;quot; $2 &amp;quot; --hash=sha256:&amp;quot; $1}&amp;#x27; wheel.sha256 &amp;gt; wheel.requirements &amp;amp;&amp;amp;
python3 -m venv .venv &amp;amp;&amp;amp;
.venv/bin/python -m pip install --no-index --no-deps --require-hashes -r wheel.requirements
export PM_DEMO_HOME=&amp;quot;$(mktemp -d)/pm-store&amp;quot;
pm() { .venv/bin/orion-pm --json --home &amp;quot;$PM_DEMO_HOME&amp;quot; &amp;quot;$@&amp;quot;; }
pm version&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The virtual environment prevents the example from replacing another &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-pm&lt;/code&gt; command. The temporary absolute store path keeps synthetic work separate from an existing board. The shell function puts global options before the subcommand, which is part of this CLI&amp;#x27;s argument contract.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;version&lt;/code&gt; reports the package version, API version, store-format version, and capabilities. A caller should check the capabilities it needs before mutating anything. The initial contract is API 1 and store format 1. Request IDs correlate calls; they do not make repeated mutations idempotent.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Create a neutral project configuration and initialize the store:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;cat &amp;gt; projects.json &amp;lt;&amp;lt;&amp;#x27;JSON&amp;#x27;
{&amp;quot;schema_version&amp;quot;:1,&amp;quot;projects&amp;quot;:[{&amp;quot;id&amp;quot;:&amp;quot;sample&amp;quot;}]}
JSON
pm init --projects projects.json
pm add --id draft-guide --title &amp;quot;Prepare a local guide example&amp;quot; --project sample --status todo
pm probe draft-guide&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Initialization is explicit. The core refuses legacy or unmarked stores rather than silently importing them. Without an explicit store, it uses &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;$XDG_DATA_HOME/orion-pm&lt;/code&gt; or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.local/share/orion-pm&lt;/code&gt;. The explicit &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--home&lt;/code&gt; takes precedence over &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;ORION_PM_HOME&lt;/code&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Probe before starting overlapping work. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;clear&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;matches&lt;/code&gt; describe coverage; inspect the returned matches and claim classifications. An unknown result is not a clear board. A live holder means coordinate with that worker rather than starting a competing edit. The atomic claim below remains the final ownership decision because the world can change after a probe.&lt;/p&gt;&lt;h2 id=&quot;let-two-workers-compete&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Let two workers compete&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This small Python launcher starts two separate installed CLI processes together. It uses two threads only to release the subprocess calls from the same barrier. The workers share the store and task ID; each has its own holder name.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;.venv/bin/python - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
from concurrent.futures import ThreadPoolExecutor
import json
import os
from pathlib import Path
import subprocess
import threading

executable = str(Path(&amp;#x27;.venv/bin/orion-pm&amp;#x27;).resolve())
barrier = threading.Barrier(2)

def claim(holder):
    barrier.wait()
    process = subprocess.run(
        [executable, &amp;#x27;--json&amp;#x27;, &amp;#x27;--home&amp;#x27;, os.environ[&amp;#x27;PM_DEMO_HOME&amp;#x27;],
         &amp;#x27;claim&amp;#x27;, &amp;#x27;draft-guide&amp;#x27;, &amp;#x27;--holder&amp;#x27;, holder],
        capture_output=True, text=True, timeout=10,
    )
    return process.returncode, json.loads(process.stdout)

with ThreadPoolExecutor(max_workers=2) as pool:
    results = list(pool.map(claim, [&amp;#x27;agent-a&amp;#x27;, &amp;#x27;agent-b&amp;#x27;]))
assert sorted(code for code, _ in results) == [0, 3], results
winner = next(reply for code, reply in results if code == 0)
loser = next(reply for code, reply in results if code == 3)
assert winner[&amp;#x27;ok&amp;#x27;] is True and winner[&amp;#x27;data&amp;#x27;][&amp;#x27;claim&amp;#x27;][&amp;#x27;state&amp;#x27;] == &amp;#x27;live&amp;#x27;
assert loser[&amp;#x27;ok&amp;#x27;] is False and loser[&amp;#x27;error&amp;#x27;][&amp;#x27;code&amp;#x27;] in (&amp;#x27;held&amp;#x27;, &amp;#x27;not_claimable&amp;#x27;)
Path(&amp;#x27;winner.json&amp;#x27;).write_text(json.dumps(winner) + &amp;#x27;\n&amp;#x27;)
print(&amp;#x27;winner:&amp;#x27;, winner[&amp;#x27;data&amp;#x27;][&amp;#x27;claim&amp;#x27;][&amp;#x27;holder&amp;#x27;])
print(&amp;#x27;loser:&amp;#x27;, loser[&amp;#x27;error&amp;#x27;][&amp;#x27;code&amp;#x27;], &amp;#x27;(exit 3)&amp;#x27;)
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Either holder may win. Exactly one receives a live claim in this controlled example; the other gets exit 3. The error can be &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;not_claimable&lt;/code&gt; once the winner has promoted the task to progress, or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;held&lt;/code&gt; for a present claim on a claimable task. The losing worker must make no work or resource call. It cannot treat a busy claim as permission to create a second task for the same outcome.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The core uses exclusive local acquisition and serializes task/claim mutations on the supported filesystem. These are coordination guarantees for cooperating clients, not protection against another process bypassing the CLI or against a worker running on another host.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Inspect the result and retain the handles:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;pm show draft-guide
HOLDER=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;winner.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;claim&amp;quot;][&amp;quot;holder&amp;quot;])&amp;#x27;)
GENERATION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;winner.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;claim&amp;quot;][&amp;quot;generation&amp;quot;])&amp;#x27;)
REVISION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;winner.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;task&amp;quot;][&amp;quot;revision&amp;quot;])&amp;#x27;)
pm renew draft-guide --holder &amp;quot;$HOLDER&amp;quot; --generation &amp;quot;$GENERATION&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The &lt;strong class=&quot;font-semibold text-white&quot;&gt;holder&lt;/strong&gt; is a session label. The &lt;strong class=&quot;font-semibold text-white&quot;&gt;generation&lt;/strong&gt; identifies this acquisition. The &lt;strong class=&quot;font-semibold text-white&quot;&gt;revision&lt;/strong&gt; identifies the task content that the worker observed. Keep all three, along with the task and store identity. Knowing only a task ID or holder name is insufficient.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Renew before the claim expires during long work. The default claim window is four hours; &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--ttl-hours&lt;/code&gt; accepts an integer from 1 to 24. This tutorial does not change the host clock or wait for expiry. An expired worker cannot renew or complete through its old handle.&lt;/p&gt;&lt;h2 id=&quot;attach-evidence-then-complete&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Attach evidence, then complete&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a synthetic local example, create a small result file and a scoped evidence record. The artifact hash binds its bytes. The evidence tells a reader exactly what was observed; it does not claim a deployment, a browser action, or an approved publication.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;printf &amp;#x27;Synthetic local guide result.\n&amp;#x27; &amp;gt; result.txt
.venv/bin/python - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
from datetime import datetime, timezone
import hashlib
import json
from pathlib import Path

evidence = {
    &amp;#x27;id&amp;#x27;: &amp;#x27;local-guide-result&amp;#x27;,
    &amp;#x27;source&amp;#x27;: &amp;#x27;tutorial-worker&amp;#x27;,
    &amp;#x27;artifact&amp;#x27;: &amp;#x27;sha256:&amp;#x27; + hashlib.sha256(Path(&amp;#x27;result.txt&amp;#x27;).read_bytes()).hexdigest(),
    &amp;#x27;observed_at&amp;#x27;: datetime.now(timezone.utc).isoformat(),
    &amp;#x27;scope&amp;#x27;: &amp;#x27;Created and hashed the synthetic local result.txt file.&amp;#x27;,
    &amp;#x27;ref&amp;#x27;: &amp;#x27;artifact:result.txt&amp;#x27;,
}
Path(&amp;#x27;evidence.json&amp;#x27;).write_text(json.dumps(evidence) + &amp;#x27;\n&amp;#x27;)
PY
pm evidence attach draft-guide --input evidence.json --holder &amp;quot;$HOLDER&amp;quot; --generation &amp;quot;$GENERATION&amp;quot; --expect-revision &amp;quot;$REVISION&amp;quot; &amp;gt; attached.json
REVISION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;attached.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;task&amp;quot;][&amp;quot;revision&amp;quot;])&amp;#x27;)
pm transition draft-guide done --holder &amp;quot;$HOLDER&amp;quot; --generation &amp;quot;$GENERATION&amp;quot; --expect-revision &amp;quot;$REVISION&amp;quot;
pm show draft-guide &amp;gt; completed.json
.venv/bin/python - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json
reply = json.load(open(&amp;#x27;completed.json&amp;#x27;))
assert reply[&amp;#x27;data&amp;#x27;][&amp;#x27;task&amp;#x27;][&amp;#x27;status&amp;#x27;] == &amp;#x27;done&amp;#x27;
assert reply[&amp;#x27;data&amp;#x27;][&amp;#x27;claim&amp;#x27;][&amp;#x27;state&amp;#x27;] == &amp;#x27;absent&amp;#x27;
assert reply[&amp;#x27;data&amp;#x27;][&amp;#x27;task&amp;#x27;][&amp;#x27;evidence&amp;#x27;][0][&amp;#x27;id&amp;#x27;] == &amp;#x27;local-guide-result&amp;#x27;
print(&amp;#x27;Observed done, no claim, and the scoped evidence reference.&amp;#x27;)
PY&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Attaching evidence changes the task revision, so the completion uses the new revision returned by that command. Reusing the older revision should fail instead of overwriting another observed change. Completing the task clears the claim; the final &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;show&lt;/code&gt; establishes the persisted result rather than relying only on the mutation&amp;#x27;s response.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The event log is a separate convenience surface. It is bounded, best effort, and non-authoritative. Event timestamps describe completed-operation observations, not an exact serialization journal. Use the task and validated claim for ownership and durable state; do not build an undo or approval system on PM events.&lt;/p&gt;&lt;h2 id=&quot;hand-unfinished-work-back-safely&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Hand unfinished work back safely&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An interrupted worker should not mark work done just to clear its claim. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;release&lt;/code&gt; returns unfinished &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;in_progress&lt;/code&gt; work to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;todo&lt;/code&gt; and removes that exact claim. It does not stop the worker or release resources in other tools.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This example releases a task, reclaims it with the same holder name, and proves that the old generation cannot renew the replacement:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;pm add --id handoff-example --title &amp;quot;Unfinished work to hand back&amp;quot; --project sample --status todo
pm claim handoff-example --holder agent-a &amp;gt; first-claim.json
OLD_GENERATION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;first-claim.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;claim&amp;quot;][&amp;quot;generation&amp;quot;])&amp;#x27;)
FIRST_REVISION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;first-claim.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;task&amp;quot;][&amp;quot;revision&amp;quot;])&amp;#x27;)
pm release handoff-example --holder agent-a --generation &amp;quot;$OLD_GENERATION&amp;quot; --expect-revision &amp;quot;$FIRST_REVISION&amp;quot;
pm claim handoff-example --holder agent-a &amp;gt; second-claim.json
if pm renew handoff-example --holder agent-a --generation &amp;quot;$OLD_GENERATION&amp;quot; &amp;gt; stale-result.json; then
  printf &amp;#x27;Unexpected stale-handle success. Stop and inspect.\n&amp;#x27; &amp;gt;&amp;amp;2
  exit 1
else
  .venv/bin/python - &amp;lt;&amp;lt;&amp;#x27;PY&amp;#x27;
import json
reply = json.load(open(&amp;#x27;stale-result.json&amp;#x27;))
assert reply[&amp;#x27;ok&amp;#x27;] is False and reply[&amp;#x27;error&amp;#x27;][&amp;#x27;code&amp;#x27;] == &amp;#x27;stale_claim&amp;#x27;
print(&amp;#x27;Old generation refused; the replacement claim stays intact.&amp;#x27;)
PY
fi
NEW_GENERATION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;second-claim.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;claim&amp;quot;][&amp;quot;generation&amp;quot;])&amp;#x27;)
SECOND_REVISION=$(.venv/bin/python -c &amp;#x27;import json; print(json.load(open(&amp;quot;second-claim.json&amp;quot;))[&amp;quot;data&amp;quot;][&amp;quot;task&amp;quot;][&amp;quot;revision&amp;quot;])&amp;#x27;)
pm release handoff-example --holder agent-a --generation &amp;quot;$NEW_GENERATION&amp;quot; --expect-revision &amp;quot;$SECOND_REVISION&amp;quot;
pm show handoff-example&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The holder string is identical across both acquisitions. The generation is different. This is why a delayed process holding yesterday&amp;#x27;s arguments cannot mutate today&amp;#x27;s replacement claim through the supported interface.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;After an unexpected termination, begin with read commands:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;pm overdue
pm triage handoff-example
pm audit
pm surface&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Triage is report-only. Takeover requires the exact observed generation, expiry and task revision, plus an explicit reason; it is not a universal force operation. A task that is in progress with a verifiably absent claim has a separate explicit recovery path. Unknown or corrupted authority calls for offline containment and inspection, not blanket claim deletion or a hand-edited status.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A maintenance-admission lease can prevent new claims while existing holders drain. It is a distinct lease from a task claim. Existing holders retain their own exact handles; maintenance does not turn the board into execution authority.&lt;/p&gt;&lt;h2 id=&quot;compose-a-browser-workflow-without-merging-the-contracts&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Compose a browser workflow without merging the contracts&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Browser use is optional. It needs the separately installed browser tool, its documented system prerequisites, and a task that actually calls for it. PM installation does not create browser profiles, install a service, sign in, or give the worker permission to use an account.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The composition order is:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Probe and acquire the PM task through the installed CLI.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Only the winner acquires the browser&amp;#x27;s native lease with a unique native holder.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Attach a driver to the returned endpoint and observe the requested result.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Release the browser through its own interface and establish cleanup.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Attach narrowly scoped PM evidence, complete with current guards, and read back.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The private PM core 0.1.0 candidate check observed that sequence using the released orion-browser 0.1.0 wheel, agent-browser 0.25.4, Chrome 155.0.8059.39, and an empty anonymous profile on the tested Linux host. The page was &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;https://example.com/&lt;/code&gt;; the result was its &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Example Domain&lt;/code&gt; title. The losing PM process made zero native browser calls. The winning process completed after a clean native release, and cleanup checks found no remaining profile process or live endpoint.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That proves one synthetic read, not signed-in platform workflows or other tool versions. The source package&amp;#x27;s browser composition note and starter example define the caller-supplied adapter seam. The Python callback names are example-local, not new browser API commands.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Timeouts and unreadable responses remain unknown. Do not repeat an external action merely because its caller failed to receive a result. Reconcile the task and the native resource separately. A request ID, claim generation, or evidence record is not an approval token or a general duplicate-send guard.&lt;/p&gt;&lt;h2 id=&quot;keep-state-ownership-clear-when-you-upgrade&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep state ownership clear when you upgrade&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Normal core operations are local and offline. Optional future integrations do not change that default. Installing the wheel modifies the chosen Python environment; it does not enable hooks, schedulers, observers, recurring work, or legacy-store migration.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before a backup or upgrade, drain or stop writers and reconcile their native resources. Keep an owner-private offline backup bound to the package and store-format version. A live copied claim is not transferable ownership. Restore compatible task/configuration state into a separate inactive store, establish empty claim authority, audit it, and use sanctioned recovery before admitting work.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Uninstalling the package leaves user state for deliberate retention. Keep the previous artifact and a known-compatible backup if rollback might be needed. Never run two restored copies as one cross-host coordination domain.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;At the end of this tutorial, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;draft-guide&lt;/code&gt; is done with an absent claim, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;handoff-example&lt;/code&gt; is todo with an absent claim. The temporary store and local receipts are synthetic. Retain or remove that exact tutorial folder and store deliberately; do not run a broad cleanup against another board.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;To connect another agent, use the installed JSON interface, retain its claim and revision handles, and read back the final task state. Keep browser lifecycle, request delivery, and action permission in the tool or caller that owns them.&lt;/p&gt;</content:encoded></item>
<item><title>Operating AI agents across Windows, WSL, and Linux nodes</title><link>https://www.danmercede.com/guides/operating-ai-agents-windows-wsl-linux</link><guid isPermaLink="true">https://www.danmercede.com/guides/operating-ai-agents-windows-wsl-linux</guid><pubDate>Thu, 15 Oct 2026 07:00:00 +0000</pubDate><description>Build a practical Windows, WSL2, and Linux workflow for several coding agents: place files and processes, connect a remote worker, coordinate worktrees, verify results, and recover from failures.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I use Windows for desktop applications, WSL2 for most command-line development, and separate Linux machines for persistent workloads, storage, and heavier compute. Claude Code, Codex, and Cursor provide different ways into that environment. A task can start in a desktop chat, edit a Linux repository, execute remotely, and return an artifact that I inspect on Windows.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That arrangement became useful as I learned to locate failures. A command can exist in one shell and disappear in another. A Windows application can reject a file that Linux can read. An agent can hang before its first response because authentication is waiting on a desktop prompt. Two capable agents can each produce a reasonable change while interfering with the same checkout.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The operating skill is knowing which boundary you are crossing and how to verify it. This guide follows a smaller version of my setup: &lt;strong class=&quot;font-semibold text-white&quot;&gt;one Windows workstation, one WSL2 distribution, one remote Linux worker, and two agent harnesses.&lt;/strong&gt; Additional service or GPU machines are extensions of the same model.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The examples use synthetic data and invented names. They assume you already have WSL2, Git, Python 3, and SSH, and have arranged authorized SSH access to a Linux machine. They do not install an agent, provision a server, or configure a public service. The configuration excerpts are individual choices to evaluate, rather than a replacement for your existing files.&lt;/p&gt;&lt;h2 id=&quot;1-draw-the-execution-map-first&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;1. Draw the execution map first&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A &lt;strong class=&quot;font-semibold text-white&quot;&gt;harness&lt;/strong&gt; is the application around a model: its terminal, tools, context handling, permissions, and session lifecycle. Two harnesses using the same model can behave differently because those surrounding systems differ.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Separate the interface you are looking at from the process doing the work:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Place&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Typical responsibility&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What to establish&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Windows&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Desktop editor, browser, native applications&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Which application and Windows identity are active?&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;WSL2&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Linux repositories, command-line agents, local validation&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Which distribution, Linux user, directory, and executable?&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Remote Linux worker&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A job that needs another machine&amp;#x27;s resources&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Which host, user, environment, and input version?&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Optional service or compute node&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Persistent services, shared storage, GPU workloads&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Who owns the resource, and what else depends on it?&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/windows-wsl-linux/execution-map.webp&quot; alt=&quot;A Windows workstation contains desktop applications and a WSL2 development environment. WSL2 sends a bounded job over SSH to a Linux worker and receives a result for local verification.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Follow the execution path: desktop interface, WSL development, remote job, local verification. Each arrow crosses a boundary you can test.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In a WSL terminal, establish your context before debugging a tool:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;uname -s
pwd
id -un
command -v python3 git ssh&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In Windows PowerShell, inspect the WSL installation separately:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;powershell&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-powershell&quot;&gt;wsl.exe --version
wsl.exe --list --verbose&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Record the distribution and WSL version with your own setup notes. A desktop editor connected to WSL can use Linux tools; another window of that editor may be running against Windows files. The window title alone is insufficient evidence. Check the terminal and workspace connection.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For every recurring workflow, I want a short answer to four questions: &lt;strong class=&quot;font-semibold text-white&quot;&gt;Where does it run? Where does its input live? What can it change? Where will I inspect the result?&lt;/strong&gt; Answer those before adding another machine or agent.&lt;/p&gt;&lt;h2 id=&quot;2-give-files-a-clear-home&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;2. Give files a clear home&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep Linux development repositories in the WSL Linux filesystem, such as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/src&lt;/code&gt;. Use a WSL-aware editor connection to work there. Microsoft recommends placing files alongside the operating system tools that use them for performance. &lt;a href=&quot;https://learn.microsoft.com/en-us/windows/wsl/filesystems&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Microsoft&amp;#x27;s filesystem guidance&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A useful starting layout inside WSL is:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;~/src/                 reference checkouts
~/worktrees/           isolated task checkouts
~/artifacts/           results to inspect or hand to another application&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Each has a different lifecycle. A checkout tracks reviewed source. A worktree holds a specific task. An artifact is an output with an identifiable input and owner. Putting everything in a downloads folder makes those distinctions harder to recover later.&lt;/p&gt;&lt;h3 id=&quot;one-file-can-have-two-path-names&quot; class=&quot;mt-8 mb-3 scroll-mt-24 text-xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;One file can have two path names&lt;/h3&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A Windows path such as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;C:\Users\developer\Downloads\report.json&lt;/code&gt; appears in WSL as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/mnt/c/Users/developer/Downloads/report.json&lt;/code&gt;. A file inside WSL can be exposed to Windows through a &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;\\wsl.localhost\...&lt;/code&gt; path. Convert paths instead of constructing them by hand:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;wslpath -w &amp;quot;$PWD/report.json&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run that after creating the report later in this guide. Pass a Windows-visible path to a Windows application. Test that the receiving application supports that location; some need a copy in a Windows folder. Changing the spelling of a path does not transfer a file to a remote machine.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In one of my desktop bridges, the Windows application wrote results into a shared folder while the WSL reader used its Linux path. The reader also had to account for byte-order marks and line endings. The two processes needed an agreed file format as well as a common location.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a new text-oriented repository, an explicit &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;.gitattributes&lt;/code&gt; is a useful baseline:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;gitattributes&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-gitattributes&quot;&gt;* text=auto eol=lf&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Review an existing repository&amp;#x27;s policy before changing it. For generated interchange files, specify UTF-8 in the writer and parser. Python&amp;#x27;s &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;encoding=&amp;quot;utf-8-sig&amp;quot;&lt;/code&gt; can accept an optional UTF-8 byte-order mark; it does not decode an arbitrary legacy encoding.&lt;/p&gt;&lt;h3 id=&quot;resolve-the-executable-as-well-as-the-path&quot; class=&quot;mt-8 mb-3 scroll-mt-24 text-xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Resolve the executable as well as the path&lt;/h3&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My WSL environment deliberately limits inherited Windows paths. That makes tool selection more predictable, but Windows executables may require an explicit location. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;command -v&lt;/code&gt; tells you whether a shell can resolve a tool. It does not establish that another harness launches with the same environment.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We also encountered a desktop launch that remained attached to its calling interop process. That taught me to check process ownership and inherited streams when an application opens but the launcher never returns. Desktop launching belongs in a bridge with a deliberate detach strategy, such as PowerShell &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Start-Process&lt;/code&gt;, and a separate check that the application actually started.&lt;/p&gt;&lt;h2 id=&quot;3-treat-networking-as-a-sequence-of-checks&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;3. Treat networking as a sequence of checks&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;localhost&lt;/code&gt; is interpreted in the environment making the connection. It cannot identify a service on an arbitrary remote node.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;WSL adds another detail. Its default NAT mode generally lets Windows reach Linux services through localhost, while Linux reaches Windows services using the Windows host address. Mirrored mode supports the Windows-to-WSL and WSL-to-Windows IPv4 loopback paths. Microsoft documents mirrored networking for Windows 11 22H2 and later. &lt;a href=&quot;https://learn.microsoft.com/en-us/windows/wsl/networking&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;WSL networking&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My workstation uses mirrored networking. On a supported installation, the relevant choice in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;%UserProfile%\.wslconfig&lt;/code&gt; is:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;ini&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-ini&quot;&gt;[wsl2]
networkingMode=mirrored&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Merge the setting into the existing section. Keep firewall protections in place and test the specific listener you need. Mirrored networking does not authenticate a connection or approve access to a signed-in application.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Changes to WSL configuration require a restart of the relevant environment. Plan that around active work: &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;wsl.exe --shutdown&lt;/code&gt; stops all running distributions. Microsoft distinguishes this Windows-side configuration from the per-distribution &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;/etc/wsl.conf&lt;/code&gt;. &lt;a href=&quot;https://learn.microsoft.com/en-us/windows/wsl/wsl-config&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;WSL configuration&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When a connection fails, narrow it in order:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Name:&lt;/strong&gt; does the intended name resolve from the calling environment?&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Transport:&lt;/strong&gt; can the caller reach the intended listener?&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Protocol:&lt;/strong&gt; does that listener speak the protocol and route the client expects?&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Identity and action:&lt;/strong&gt; is this the right account, with permission for the requested operation?&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We hit a useful example with a Windows browser debugging connection. Its conventional HTTP discovery URL returned 404, but the browser&amp;#x27;s current WebSocket endpoint worked. The 404 established that an HTTP server answered; it did not prove that the debugging transport was unavailable. The fix was to discover the endpoint through the browser&amp;#x27;s supported mechanism and use a client capable of connecting to it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That is an observed behavior of that browser configuration. Recheck your own browser and client version. Debugging access to a signed-in browser can grant extensive account access; use a dedicated profile for experiments, keep endpoints private, and treat session routes as sensitive. My &lt;a href=&quot;https://www.danmercede.com/guides/multi-agent-browser-pool&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;browser-pool guide&lt;/a&gt; covers ownership when agents share browser resources.&lt;/p&gt;&lt;h3 id=&quot;make-the-remote-worker-explicit&quot; class=&quot;mt-8 mb-3 scroll-mt-24 text-xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Make the remote worker explicit&lt;/h3&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An SSH alias keeps the tutorial readable. Adapt this example in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.ssh/config&lt;/code&gt; to your own hostname and user:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;sshconfig&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-sshconfig&quot;&gt;Host worker
    HostName worker.example.net
    User developer
    ForwardAgent no&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;worker.example.net&lt;/code&gt; is a placeholder. Use your machine&amp;#x27;s private DNS name or another address you control. Establish host-key trust and authentication through your normal setup; do not suppress host-key checking to make an agent proceed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then probe from the same WSL environment the agent will use:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ssh -o BatchMode=yes -o ConnectTimeout=5 worker &amp;#x27;uname -s&amp;#x27;
ssh -o BatchMode=yes -o ConnectTimeout=5 worker &amp;#x27;command -v python3&amp;#x27;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expect &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Linux&lt;/code&gt; and a Python executable path. A successful mesh ping would establish reachability; these checks additionally exercise SSH authentication and the remote command environment. A noninteractive SSH command can have a different environment from an interactive login shell.&lt;/p&gt;&lt;h2 id=&quot;4-coordinate-agents-at-three-separate-boundaries&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;4. Coordinate agents at three separate boundaries&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Claude Code, Codex, and Cursor do not automatically share instructions, permissions, memory, or session state. Make the repository&amp;#x27;s operating instructions explicit and verify how each harness loads them. Give every task a target directory, allowed scope, verification step, and stopping point.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Three boundaries matter when several agents work at once:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Boundary&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What it answers&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What it does not provide&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Task ownership&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Who is working on this outcome?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Permission to publish or deploy&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Worktree or resource ownership&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Which checkout, browser, port, or GPU may this worker use?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Exclusive ownership of every shared dependency&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Action permission&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Which outward or consequential actions are authorized?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Proof that the action succeeded&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I use task claims before overlapping work and separate worktrees for edits. A worktree isolates the checked-out files; an exclusive task claim coordinates intent. Either one alone leaves gaps. My &lt;a href=&quot;https://www.danmercede.com/guides/coordinate-local-agents-with-orion-pm&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;local-agent coordination tutorial&lt;/a&gt; demonstrates claims on a supported local filesystem. That local coordination mechanism does not establish fencing between machines.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;From a clean reference checkout of a repository whose default branch is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main&lt;/code&gt;, fetch and create task worktrees:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;git fetch origin
git worktree add -b task/worker-report ../report-worker origin/main
git worktree add -b task/report-review ../report-review origin/main
git worktree list&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Adapt &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;main&lt;/code&gt; if your repository uses another default branch. Git manages linked worktrees and normally prevents checking out the same branch in two of them. &lt;a href=&quot;https://git-scm.com/docs/git-worktree&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Git worktree documentation&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Assign one worker a bounded change. Give the reviewer the resulting diff or commit after it exists. The two new worktrees initially contain the same base, so the reviewer must explicitly receive the worker&amp;#x27;s result. Worktrees also share repository metadata and may still contend for ports, caches, browsers, or remote machines.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A task brief can stay small:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;Outcome: produce a report from the supplied synthetic input.
Workspace: the assigned worktree only.
Allowed: inspect, edit the report tool, run its checks.
Remote: run the bounded computation on the configured worker.
Completion: independently verified result and a reviewable diff.
Stop before: merge, deployment, publication, account changes.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This is a coordination instruction. Actual harness permissions and operating-system access must support the intended boundary. Text in a repository cannot prevent a process with broader access from touching other files.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before a handoff, record the branch or commit, dirty files, exact artifact, verification performed, and remaining step. A session label is too weak: the next process may reuse it while running with different code or permissions.&lt;/p&gt;&lt;h2 id=&quot;5-follow-one-job-through-the-whole-system&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;5. Follow one job through the whole system&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before giving agents a complicated remote workflow, make one small job observable end to end. This example sends JSON from WSL to a Python process over SSH. The worker returns a report; a separate local check compares it with the original request.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;There is no remote installation or output file. The input and result travel through standard streams. This is a bounded demonstration with no remote side effects, rather than a durable job scheduler.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Create a fresh folder in WSL and keep using the same shell:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;DEMO_ROOT=&amp;quot;$(mktemp -d)&amp;quot;
cd &amp;quot;$DEMO_ROOT&amp;quot;
printf &amp;#x27;{&amp;quot;job_id&amp;quot;:&amp;quot;demo-001&amp;quot;,&amp;quot;values&amp;quot;:[2,3,5]}\n&amp;#x27; &amp;gt; request.json&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Create &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;run_job.py&lt;/code&gt; there:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;import json
from pathlib import Path
import shlex
import subprocess

REMOTE_PROGRAM = r&amp;#x27;&amp;#x27;&amp;#x27;
import hashlib
import json
import platform
import sys

raw = sys.stdin.buffer.read()
request = json.loads(raw)
values = request[&amp;quot;values&amp;quot;]
report = {
    &amp;quot;schema_version&amp;quot;: 1,
    &amp;quot;job_id&amp;quot;: request[&amp;quot;job_id&amp;quot;],
    &amp;quot;input_sha256&amp;quot;: hashlib.sha256(raw).hexdigest(),
    &amp;quot;count&amp;quot;: len(values),
    &amp;quot;total&amp;quot;: sum(values),
    &amp;quot;executor_os&amp;quot;: platform.system(),
}
print(json.dumps(report, sort_keys=True))
&amp;#x27;&amp;#x27;&amp;#x27;

request_bytes = Path(&amp;quot;request.json&amp;quot;).read_bytes()
# SSH passes its command through a remote shell. Quote that boundary too.
command = &amp;quot;python3 -c &amp;quot; + shlex.quote(REMOTE_PROGRAM)
result = subprocess.run(
    [&amp;quot;ssh&amp;quot;, &amp;quot;-o&amp;quot;, &amp;quot;BatchMode=yes&amp;quot;, &amp;quot;-o&amp;quot;, &amp;quot;ConnectTimeout=5&amp;quot;,
     &amp;quot;worker&amp;quot;, command],
    input=request_bytes,
    capture_output=True,
    check=True,
    timeout=30,
)
# Reject non-JSON output before replacing the result file.
json.loads(result.stdout)
pending = Path(&amp;quot;report.json.pending&amp;quot;)
pending.write_bytes(result.stdout)
pending.replace(&amp;quot;report.json&amp;quot;)
print(&amp;quot;Received report.json; independent verification is next.&amp;quot;)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run it:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;python3 run_job.py&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Stop if it fails. A failed SSH call or invalid response must not be interpreted as a completed job because a previous report happens to exist. The timeout bounds the local wait; it does not guarantee termination of arbitrary remote work after disconnect. That distinction matters when you later introduce jobs with side effects.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Create &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;verify_report.py&lt;/code&gt; in the same folder:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;import hashlib
import json
from pathlib import Path

raw = Path(&amp;quot;request.json&amp;quot;).read_bytes()
request = json.loads(raw)
report = json.loads(Path(&amp;quot;report.json&amp;quot;).read_bytes())
expected = {
    &amp;quot;schema_version&amp;quot;: 1,
    &amp;quot;job_id&amp;quot;: request[&amp;quot;job_id&amp;quot;],
    &amp;quot;input_sha256&amp;quot;: hashlib.sha256(raw).hexdigest(),
    &amp;quot;count&amp;quot;: len(request[&amp;quot;values&amp;quot;]),
    &amp;quot;total&amp;quot;: sum(request[&amp;quot;values&amp;quot;]),
    &amp;quot;executor_os&amp;quot;: &amp;quot;Linux&amp;quot;,
}
if report != expected:
    raise SystemExit(&amp;quot;Report failed verification; inspect the input and result.&amp;quot;)
print(
    f&amp;quot;Verified: {request[&amp;#x27;job_id&amp;#x27;]}, {len(request[&amp;#x27;values&amp;#x27;])} values, &amp;quot;
    f&amp;quot;total {sum(request[&amp;#x27;values&amp;#x27;])}, matching input bytes.&amp;quot;
)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then inspect it from the consumer side:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;python3 verify_report.py
cat report.json
wslpath -w &amp;quot;$PWD/report.json&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The expected verification message is &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;Verified: demo-001, 3 values, total 10, matching input bytes.&lt;/code&gt; Open the converted path in a Windows application that supports WSL paths. You have now followed input in Linux, execution on another Linux machine, a returned artifact, independent checking, and consumption on Windows.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a concrete Windows check, replace the placeholder below with the path printed by &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;wslpath&lt;/code&gt;, then run this in Windows PowerShell:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;powershell&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-powershell&quot;&gt;Get-Content -Raw -LiteralPath &amp;#x27;PASTE-THE-CONVERTED-PATH&amp;#x27; |
    ConvertFrom-Json |
    Format-List job_id, count, total&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expect &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;demo-001&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;3&lt;/code&gt;, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;10&lt;/code&gt;. This exercises a Windows consumer separately from the Linux verifier.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The hash ties the report to specific input bytes. It does not prove the worker is trustworthy, that a real business calculation is correct, or that a public deployment occurred. SSH host authentication and the independent calculation establish different parts of this demonstration. For a real workload, choose a verification method appropriate to its output.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Try a deliberate failure: edit &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;total&lt;/code&gt; in the report to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;11&lt;/code&gt;, then run the verifier again. It should refuse the report. Run the job again to obtain a clean result. Changing the request after execution should also invalidate the returned input hash.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/windows-wsl-linux/job-evidence.webp&quot; alt=&quot;A local request crosses an SSH boundary to a Linux computation, returns as a report, and passes through an independent local verifier before a Windows application consumes it.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Keep the request and the returned bytes. Verify the result before accepting it, then inspect it where it will be used.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Now give one agent a bounded extension, such as adding a minimum value to the report. Give another agent the diff and ask it to test an incorrect total, a changed input, and an empty list. Use the task and worktree boundaries from the previous section. The exercise should produce an explainable result even if you replace either harness.&lt;/p&gt;&lt;h2 id=&quot;6-separate-service-health-from-machine-lifetime&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;6. Separate service health from machine lifetime&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My WSL environment uses systemd. A missed timer once looked like a scheduling problem, but the underlying issue was the WSL VM&amp;#x27;s idle lifetime. The VM shut down while catch-up work was still relevant. Changing its idle policy addressed that situation; it did not make the workstation an always-on server.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Microsoft explicitly notes that systemd services do not, by themselves, keep a WSL instance alive. A service manager and the Windows host&amp;#x27;s lifecycle are separate layers. &lt;a href=&quot;https://learn.microsoft.com/en-us/windows/wsl/systemd&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Systemd in WSL&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On a distribution using systemd, inspect both service scopes:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;systemctl --failed
systemctl --user --failed
systemctl --user list-timers --all&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A listed timer establishes configuration or scheduling state. Inspect the service invocation, its logs, and the expected output to establish whether the work ran. Windows sleep, shutdown, and WSL termination remain outside that timer&amp;#x27;s control.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;I place workloads that need continuous availability on the remote Linux machines. WSL stays useful for supervised development and explicitly managed local automation. If you choose to keep unattended work there, document how Windows starts the distribution, what happens after a missed run, and how you detect an absent result.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Apply the same reasoning to GPU work. An SSH connection establishes access, not an available GPU. Check resident workloads, coordinate use, and verify any required restoration before accepting a benchmark or render. A second agent should not evict another task&amp;#x27;s model simply because it can issue the command.&lt;/p&gt;&lt;h2 id=&quot;7-diagnose-authentication-before-reinstalling-the-agent&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;7. Diagnose authentication before reinstalling the agent&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;One of the more instructive failures happened before an agent produced its first response. Several entry points into the same harness stalled. The common dependency was an MCP OAuth credential store backed by a locked desktop keyring. Its unlock prompt depended on WSLg, and the GUI path was failing.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The process could start, but its startup dependency could not complete. Retrying the model request or reinstalling an editor would have targeted the wrong layer.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For that environment, we deliberately selected file-backed MCP credential persistence. Codex exposes this choice separately from model login and action permissions:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;toml&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-toml&quot;&gt;mcp_oauth_credentials_store = &amp;quot;file&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This is a top-level setting in the Codex configuration. The documented alternatives are &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;auto&lt;/code&gt; and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;keyring&lt;/code&gt;. &lt;a href=&quot;https://developers.openai.com/codex/config-reference/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Codex configuration reference&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Treat this as a tradeoff to evaluate after diagnosis. File-backed credentials become sensitive local files. Restrictive permissions limit access by other users, but do not encrypt the contents or protect against every process running as your user. Keep them out of Git, logs, screenshots, and unprotected backups. Repairing the keyring or GUI path may be the better answer in your environment.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My diagnostic sequence is to identify the shared failing startup dependency, check whether it needs an interactive prompt, and test a narrowly scoped remedy. Recheck behavior after a restart. Avoid dumping the process environment or credential files into an agent conversation to investigate a hang.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Authentication state also does not transfer merely because two harnesses share a computer. Establish which process, OS user, and credential store each one actually uses.&lt;/p&gt;&lt;h2 id=&quot;8-make-recovery-part-of-the-setup&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;8. Make recovery part of the setup&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two recovery lessons changed how I operate this environment.&lt;/p&gt;&lt;h3 id=&quot;monitor-the-host-disk-as-well-as-the-linux-filesystem&quot; class=&quot;mt-8 mb-3 scroll-mt-24 text-xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Monitor the host disk as well as the Linux filesystem&lt;/h3&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Large crash dumps filled my Windows system volume and broke WSL exports. A Linux-side free-space check did not describe the whole backup path. The producer, its destination, and the volume that hosts them all mattered.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In WSL, inspect the Linux and mounted Windows filesystems separately:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;df -h / /mnt/c&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;In Windows PowerShell, inspect the host volume:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;powershell&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-powershell&quot;&gt;Get-Volume -DriveLetter C&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;My configuration limits the retained WSL crash-dump count. &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;maxCrashDumpCount&lt;/code&gt; is a count limit, so a small number of large files can still consume substantial space. Inspect storage use and keep a deliberate retention policy. &lt;a href=&quot;https://learn.microsoft.com/en-us/windows/wsl/wsl-config&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;WSL configuration settings&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A backup process returning successfully is one piece of evidence. Check that the expected export was produced recently, then perform an isolated restore exercise. Keep source code, recoverable machine state, and sensitive credentials under appropriate, distinct backup policies.&lt;/p&gt;&lt;h3 id=&quot;restore-copies-without-creating-a-second-live-operator&quot; class=&quot;mt-8 mb-3 scroll-mt-24 text-xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Restore copies without creating a second live operator&lt;/h3&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An exported distribution can carry scheduled jobs, service enablement, credentials, and files that permit live actions. A restored copy may therefore have the ability to send, deploy, or mutate shared state. Our clone procedure explicitly keeps those capabilities inactive until promotion.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Before an export or restore exercise, inventory the mechanisms that can write outside the machine. Prepare the image and first-boot procedure so they remain inactive before normal user services start; inspect inherited configuration and action-enable state. Establish that only the intended instance can act before reconnecting those capabilities.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Do not assume disabling a timer removes every path to an action. The service can still be started manually, another scheduler may invoke it, and copied credentials may remain usable. The exact controls depend on your setup. The invariant is that a recovery test must not quietly become a second production writer.&lt;/p&gt;&lt;h2 id=&quot;a-troubleshooting-map-to-keep-beside-the-terminal&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;A troubleshooting map to keep beside the terminal&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Symptom&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;First boundary to inspect&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Useful distinction&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Tool works in one harness but not another&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Executable, user, directory, environment&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Same computer can contain different launch environments.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Windows application cannot open an artifact&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Path and filesystem visibility&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Path conversion and file transfer are different operations.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;WSL cannot reach a Windows listener&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Networking mode, listener, firewall&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Establish the actual Windows/WSL connection path.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A discovery URL returns 404&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Protocol and endpoint discovery&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;An HTTP response can coexist with a working different endpoint.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Several agent entry points stall at startup&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Shared authentication or tool dependency&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A hidden interactive prompt can block a headless workflow.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Timer is enabled but no result appears&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;VM lifetime, service invocation, output&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A schedule is insufficient evidence of execution.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Two agents overwrite or duplicate work&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Task claim, worktree, shared resource&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Separate chats alone provide no exclusive ownership.&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Export is old or missing&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Producer, destination, host disk&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Backup configuration does not establish a usable restore.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;h2 id=&quot;build-fluency-one-boundary-at-a-time&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Build fluency one boundary at a time&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start by locating your shell, repository, executable, and output. Make a Windows application consume an artifact produced in WSL. Add one remote computation and independently check its result. Then introduce a second agent with explicit ownership and a separate worktree. Exercise a failed connection, a rejected result, and a handoff before adding unattended work.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That sequence gives each new layer an observable purpose. My larger setup grew around real workloads and the problems they exposed. The durable skill is being able to trace a task across the system, recognize what each observation proves, and leave the next operator enough evidence to continue.&lt;/p&gt;</content:encoded></item>
<item><title>Quality video on local hardware: the Elsewhere Unfolds workflow</title><link>https://www.danmercede.com/guides/quality-video-on-local-hardware</link><guid isPermaLink="true">https://www.danmercede.com/guides/quality-video-on-local-hardware</guid><pubDate>Tue, 13 Oct 2026 07:00:00 +0000</pubDate><description>A practical local video workflow drawn from Elsewhere Unfolds: plan a coherent world, animate with Wan, score with ACE-Step, edit with FFmpeg, and review the finished film.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An early Elsewhere Unfolds cut had an attractive world, a complete timeline, and a successful render. It also had water that barely moved and clouds that stayed fixed while the camera drifted past them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The shot manifest was satisfied. The scene did not feel alive.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That correction changed how we produced the next passages. We separated camera movement from environmental movement, tested short motion clips at normal speed, and watched them before committing to the rest of the film. The improvement came from a clearer creative requirement and a smaller review loop.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;a href=&quot;https://www.youtube.com/@ElsewhereUnfolds&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Elsewhere Unfolds&lt;/a&gt; makes fantasy and cosmic visual journeys with instrumental music. This guide explains the reusable production method behind that work, from the first visual promise to a finished master and vertical excerpts.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The boundary matters:&lt;/strong&gt; our established motion, music, editing, and finishing pipeline uses local resources. Some starting images were made with a hosted image tool. That makes those productions hybrid. For an entirely local version, supply your own photographs, drawings, local 3D renders, or images from a model running on your machine. The workflow below starts with those local image files. It does not require a hosted video generator.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The examples use the Wan 2.2 TI2V-5B and ACE-Step v1 stack from our production recipes. They are a concrete baseline, not a claim that every newer model has been evaluated or that these settings suit every GPU.&lt;/p&gt;&lt;h2 id=&quot;the-production-loop&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;The production loop&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Work in three sizes: one shot, one short sequence, then the complete film. Each answers a different question.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Size&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What you are learning&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What to review&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;One native motion take&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Can the intended action work?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Geometry, feet, motion direction, unwanted objects&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;A 30 to 60 second sequence&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Do the shots and music belong together?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Orientation, pacing, transitions, emotional tone&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The complete film&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Does the experience hold up over time?&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Repetition, later continuity, score joins, ending&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/local-video/production-loop.webp&quot; alt=&quot;Production proceeds from a brief and local artwork to a short motion test, an opening sequence, and a full film. Review separates each expansion; music joins the opening and the final edit.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Prove the shot, then the sequence, then the film. Keep accepted work when expanding the next stage.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our longer episodes have used an 8:01 format. That is an editorial choice, not a recommended starting assignment. Begin with a 30-second film you can finish, inspect, and revise. Padding a weak minute into eight minutes only gives you more weak material to fix.&lt;/p&gt;&lt;h2 id=&quot;what-needs-to-run-locally&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What needs to run locally&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;You do not need a cluster. You need a machine that can run the chosen model, space for its weights and intermediate files, and a way to edit and review the result.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Job&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Our established tool or method&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Output to keep&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;World and shot planning&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Written brief, storyboard, reference images&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Selected brief and shot list&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Starting artwork&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Approved image files; source can vary&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Original plate and provenance&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Image-to-video motion&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Wan 2.2 TI2V-5B&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Native take, prompt, seed, settings&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Instrumental music&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;ACE-Step v1 3.5B&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Raw WAVs and selected arrangement&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Assembly and finishing&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Python orchestration and FFmpeg&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Edit decisions, review copy, final master&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Inspection&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;FFprobe, frame samples, normal playback&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Technical results and review decisions&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Wan&amp;#x27;s documented single-GPU TI2V-5B example targets at least 24 GB of VRAM with model offloading and the text encoder on CPU. Treat that as the reference for that command, not a universal minimum or a guarantee of success. CPU RAM, free VRAM, software versions, and the selected settings still matter. Check the &lt;a href=&quot;https://github.com/Wan-Video/Wan2.2#run-text-image-to-video-generation&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;official Wan setup instructions&lt;/a&gt; against your hardware before downloading a large checkpoint.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a first project, keep motion generation and music generation sequential. A background model can consume memory that a video job needs. If the GPU is shared, agree on an available window; do not terminate somebody else&amp;#x27;s work to make room. A waiting job is cheaper than losing an accepted take or disrupting another workload.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Initial installation and model downloads need network access. Local inference means the generation runs on your equipment. It does not make electricity, storage, setup time, or retakes free.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Record the model revision, source revision, environment, settings, and input image for each run. A seed helps repeat an experiment, but it does not guarantee identical output across different software and hardware.&lt;/p&gt;&lt;h2 id=&quot;1-write-the-experience-before-writing-prompts&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;1. Write the experience before writing prompts&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A useful brief explains what the viewer will experience and what will change. “Beautiful cinematic fantasy, ultra detailed” cannot do that work.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Here is an illustrative brief for a small film:&lt;/p&gt;&lt;blockquote class=&quot;my-5 border-l-2 border-copper-500/50 pl-5 text-slate-300&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We board a floating garden before it leaves a quiet dock. A gardener crosses the terrace. The gap behind us widens, and a pale arch appears at our destination. Copper, emerald, and pearl remain the visual palette. The mood is calm anticipation. The final image resolves the journey rather than introducing another location.&lt;/p&gt;&lt;/blockquote&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Turn it into a few fixed decisions:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The promise:&lt;/strong&gt; a garden really leaves one place for another.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The route:&lt;/strong&gt; boarding terrace, departure view, onboard path, destination.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The continuity anchors:&lt;/strong&gt; the same moon placement, architecture, clothing, and direction of travel.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The movement:&lt;/strong&gt; leaves and water move; the dock recedes; a person performs one readable action.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;The exclusions:&lt;/strong&gt; no crowds, complicated hand exchanges, or unexplained new landmarks.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Make the thumbnail and first shot agree about the film&amp;#x27;s promise. If the packaging promises a moving island, establish that island and its departure early. A long logo introduction spends attention before delivering the thing the viewer selected.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For Elsewhere, a recognizable route matters more than a collection of unrelated beautiful locations. Each shot should tell us where we are, what has changed, or where we are going.&lt;/p&gt;&lt;h2 id=&quot;2-build-a-world-that-survives-the-next-camera-angle&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;2. Build a world that survives the next camera angle&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Call the approved starting image for a shot its &lt;strong class=&quot;font-semibold text-white&quot;&gt;plate&lt;/strong&gt;. Keep a small set of reference plates that establish materials, light, landmarks, and any recurring people.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Review the plates together before animating them. A contact sheet makes inconsistencies easier to see: a second moon appears, the destination moves behind the traveler, or a bridge no longer connects to the same terrace.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We have caught all of those classes of problem during production. One reverse view placed another complete moon outside a doorway even though the camera was already inside that moon. Another reference combination duplicated the sun. Attractive individual images can still describe an impossible route.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use a compact shot table:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Shot&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Purpose&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Action&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Must remain stable&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Terrace wide&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Establish the world&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Water ripples and leaves move&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Island silhouette, moon position&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Gardener profile&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Establish habitation&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;One walk from left to right&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Clothing, ground contact, path&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Stern view&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Prove departure&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The distant dock recedes&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Foreground rail, open gap&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Bow view&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Reveal destination&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Gentle camera reveal&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Travel direction, destination arch&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Simplify a plate when it asks too much of motion generation. Give a walking person visible feet, clear ground, and empty space ahead. Separate actions that would otherwise compete. A close hand exchange, turning crowd, and moving camera in the same five seconds create several opportunities for failure.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If you want the whole process to stay local, this is where you choose your image source. A scene rendered in a local 3D application or a drawing you made yourself is a valid plate. A local image model is another option, but it is a separate tool to qualify. We are not claiming that substituting one reproduces our hosted artwork automatically.&lt;/p&gt;&lt;h2 id=&quot;3-generate-one-motion-take-with-a-clear-job&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;3. Generate one motion take with a clear job&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For image-to-video work, let the plate describe the appearance. Use the motion prompt to describe the action, camera, and things that must stay stable.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An illustrative prompt:&lt;/p&gt;&lt;blockquote class=&quot;my-5 border-l-2 border-copper-500/50 pl-5 text-slate-300&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Locked medium-wide side view. One gardener walks naturally from left to right along the level stone path. Both feet remain visible and contact the ground. Leaves move gently in the background. Preserve the copper railing, architecture, clothing, and lighting. No additional people, no camera orbit, no cuts.&lt;/p&gt;&lt;/blockquote&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;After following the upstream installation instructions and downloading the TI2V-5B checkpoint, this is the shape of a run from the Wan source directory. Replace the example input and checkpoint paths with your local files. Use a new output filename for each attempt.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;python generate.py \
  --task ti2v-5B \
  --size &amp;#x27;1280*704&amp;#x27; \
  --ckpt_dir ./Wan2.2-TI2V-5B \
  --image ./inputs/gardener.png \
  --prompt &amp;#x27;Locked side view. One gardener walks left to right on a level path. Feet remain visible. Leaves move gently. Preserve the railing and clothing. No extra people or cuts.&amp;#x27; \
  --frame_num 121 \
  --sample_steps 50 \
  --sample_solver unipc \
  --sample_shift 5.0 \
  --sample_guide_scale 5.0 \
  --base_seed 42 \
  --offload_model True \
  --convert_model_dtype \
  --t5_cpu \
  --save_file ./gardener-take-01.mp4&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;These controls follow the &lt;a href=&quot;https://github.com/Wan-Video/Wan2.2/blob/main/generate.py&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;upstream command-line interface&lt;/a&gt; and our established recipe. This is an adapted example, not a fresh performance benchmark. It does not enable a hosted prompt-expansion service.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;At 24 fps, 121 encoded frames occupy about 5.04 seconds. An exact five-second edit uses 120 frames. Check the generated file&amp;#x27;s actual dimensions and timing: our image-conditioned production outputs have included 1248 × 704, despite the &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;1280*704&lt;/code&gt; size setting. Do not infer the output raster from the command alone.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Watch the native take before slowing, enlarging, or stitching it. Check the start, middle, and end, then play the entire clip. Look for foot sliding, changing faces, bending rails, sudden foreground figures, and movement in the wrong direction. If the action fails, simplify the action or repair the plate before launching a large batch.&lt;/p&gt;&lt;h2 id=&quot;4-treat-three-kinds-of-motion-separately&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;4. Treat three kinds of motion separately&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;&lt;strong class=&quot;font-semibold text-white&quot;&gt;Camera motion&lt;/strong&gt; changes the viewpoint. &lt;strong class=&quot;font-semibold text-white&quot;&gt;Environmental motion&lt;/strong&gt; changes water, mist, foliage, light, and other scene elements. &lt;strong class=&quot;font-semibold text-white&quot;&gt;Performed action&lt;/strong&gt; is a person walking, turning, or doing something.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An image can have a convincing camera move while its waterfall remains frozen. A scene can have moving fog while its traveler slides without taking a step. Review each kind independently.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/local-video/three-kinds-of-motion.webp&quot; alt=&quot;Three separate review lanes distinguish camera movement, environmental movement, and performed action. Each names what should move and a characteristic failure to inspect.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;A moving camera cannot prove moving water. A changed pose cannot prove a convincing walk.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a calm environmental shot, forward slow motion can be useful if it still looks natural. For walking or other recognizable human actions, start with native speed. Watch any interpolation for doubled limbs, smeared edges, and unstable occlusions.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Five seconds of generated movement do not become twenty seconds of new action because the editor can repeat or slow them. A reverse loop can make a person walk backward; a repeated wave or bird can reveal the loop. If a passage needs more time, generate a distinct take, cut to another angle, or shorten the passage.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Continuing from the last frame of a previous take can help connect movement, but it can also carry defects forward. Inspect that frame before making it the next input. Stop a continuation when geometry starts to drift instead of extending the error through the film.&lt;/p&gt;&lt;h2 id=&quot;5-finish-a-short-opening-before-expanding-the-film&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;5. Finish a short opening before expanding the film&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Assemble a 30 to 60 second proof with real motion, representative music, and the intended edit rhythm. A slideshow of selected plates cannot answer whether the finished motion works.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The proof should contain the hard part. If departure is the central promise, include departure. If a recurring traveler makes the world feel inhabited, include a real walking shot. An easy landscape does not qualify a harder action later.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Review the sequence without pausing first. Does it make sense? Does the first shot deliver the promise? Is there a reason to keep watching? Then examine technical defects and individual transitions.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Once a sequence is accepted, keep its exact files and settings. Expand around it. We preserve accepted openings while generating later passages so a new render cannot silently replace the part that already worked.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep a simple project layout:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;film/
  brief.md
  shots.csv
  plates/
  motion/raw/
  motion/selected/
  music/raw/
  music/selected/
  edit/
  review/
  exports/&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The labels are less important than the separation. Raw sources stay intact; selected sources are explicit; review exports are disposable derivatives. Save a rejection reason beside a failed take so the next attempt changes something useful.&lt;/p&gt;&lt;h2 id=&quot;6-compose-and-review-the-soundtrack-as-a-whole&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;6. Compose and review the soundtrack as a whole&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our established music recipes use &lt;a href=&quot;https://huggingface.co/ACE-Step/ACE-Step-v1-3.5B&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;ACE-Step v1 3.5B&lt;/a&gt; locally. Keep the version explicit: a later release may have different installation, controls, and behavior. Use the &lt;a href=&quot;https://github.com/ace-step/ACE-Step&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;project&amp;#x27;s documentation&lt;/a&gt; for the environment matching your selected release.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A music brief should describe the experience and the arrangement. For this style, we ask for warm, spacious instrumental ambience, gradual harmony, and sparse melody. We also describe what would break the mood: lyrics, voice-like passages, a strong beat, abrupt motifs, or a trailer-style crescendo.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Start with a short audition against the opening. Choose where the cue enters and whether it leaves enough space for the imagery. Then review the full arrangement, including every join and the final tail. An attractive first minute does not establish a clean ending.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep lossless WAV sources. Build an arrangement from selected cues with measured overlaps, deliberate fades, and enough headroom. The finished duration is the sum of the cue durations minus their overlaps. The same arithmetic applies to overlapping video transitions.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Measure the generated audio rather than assuming a requested duration is exact. We encountered a cue that was roughly 73 milliseconds short because of the installed model&amp;#x27;s duration grid. The composition had succeeded. The useful response was to preserve it, diagnose the precise discrepancy, and make a small documented finishing correction. That is different from concealing a missing passage with silence.&lt;/p&gt;&lt;h3 id=&quot;check-the-playback-path-before-removing-noise&quot; class=&quot;mt-8 mb-3 scroll-mt-24 text-xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Check the playback path before removing noise&lt;/h3&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When static is reported, compare the original WAV, the finished export, and playback in another native player or device. In one later Elsewhere review, native Windows playback sounded correct while the WSL playback path did not. Filtering the accepted source would have changed music that was already satisfactory.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a different batch of Shorts, a gentle cleanup was accepted after direct comparison. This was the filter used for that case:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ffmpeg -n -i source.wav \
  -af &amp;#x27;afftdn=nr=6:nf=-48:tn=0:gs=8&amp;#x27; \
  -c:a pcm_s24le audition-clean.wav&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Treat this as an audition candidate, never an automatic mastering preset. FFmpeg documents these controls under &lt;a href=&quot;https://ffmpeg.org/ffmpeg-filters.html#afftdn&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;afftdn&lt;/a&gt;. Denoising can soften wanted texture. Compare original and cleaned versions at comparable listening levels, preserve both, and choose by listening. Waveform similarity and successful decoding cannot establish that something sounds good.&lt;/p&gt;&lt;h2 id=&quot;7-edit-to-a-timeline-not-a-requested-runtime&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;7. Edit to a timeline, not a requested runtime&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Give every shot an editorial purpose and an explicit frame allocation. At 24 fps, an 8:01 film contains 11,544 presentation frames. Resolve transitions and overlaps in that frame budget rather than rounding each shot independently.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a first 30-second exercise, prepare six accepted five-second shots at 24 fps, all with matching dimensions, codec settings, and no audio. Put the filenames in &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;edit/shots.txt&lt;/code&gt;, relative to that list:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;text&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-text&quot;&gt;file &amp;#x27;../motion/selected/shot-01.mp4&amp;#x27;
file &amp;#x27;../motion/selected/shot-02.mp4&amp;#x27;
file &amp;#x27;../motion/selected/shot-03.mp4&amp;#x27;
file &amp;#x27;../motion/selected/shot-04.mp4&amp;#x27;
file &amp;#x27;../motion/selected/shot-05.mp4&amp;#x27;
file &amp;#x27;../motion/selected/shot-06.mp4&amp;#x27;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;From the project root, assemble a straight-cut picture track:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ffmpeg -n -f concat -safe 0 -i edit/shots.txt \
  -map 0:v:0 -an -c:v copy edit/picture.mp4&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This simple stream-copy path requires compatible, independently prepared clips. Mixed time bases, encoders, or track layouts need normalization in your editing stage; a concat command is not a general repair tool. Keep crossfades out of the first exercise so its duration stays easy to audit. See the &lt;a href=&quot;https://ffmpeg.org/ffmpeg-formats.html#concat&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;concat demuxer documentation&lt;/a&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;After preparing a 30-second score with its entrance and ending already shaped, make a review export:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ffmpeg -n -i edit/picture.mp4 -i music/selected/score-30s.wav \
  -map 0:v:0 -map 1:a:0 \
  -c:v copy -c:a aac -b:a 320k -ar 48000 \
  -movflags +faststart exports/review-30s.mp4&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Both sources must cover the intended duration. Avoid adding &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;-shortest&lt;/code&gt; as a reflex: it can hide an unexpectedly short input by cutting the other track. Inspect the result and listen to its ending.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the native generation size distinct from the delivery size. A 3840 × 2160 export made from lower-resolution motion is an upscale. It can be a useful delivery format, but enlarging a warped railing makes a larger warped railing. Finish motion and continuity before paying for a high-resolution encode.&lt;/p&gt;&lt;h2 id=&quot;8-make-quality-control-answer-specific-questions&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;8. Make quality control answer specific questions&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Automated checks are useful when they tell you exactly what they established. Use &lt;a href=&quot;https://ffmpeg.org/ffprobe.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;FFprobe&lt;/a&gt; to inspect the exported file:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ffprobe -v error -count_frames \
  -show_entries &amp;#x27;stream=index,codec_type,codec_name,width,height,avg_frame_rate,nb_read_frames,duration,sample_rate,channels:format=duration&amp;#x27; \
  -of json exports/review-30s.mp4&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For the exercise, expect 720 video frames at 24 fps and the planned audio channels and sample rate. AAC/container timing can differ slightly from the exact picture duration; investigate meaningful mismatches instead of treating every reported duration as identical.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Decode the entire export, including audio:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;ffmpeg -v error -xerror -i exports/review-30s.mp4 \
  -map 0:v:0 -map 0:a:0 -f null -&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A clean decode establishes readable media. It does not establish pleasing images, good pacing, or acceptable sound. Complete three reviews:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Review&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Questions&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Technical&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Does it decode? Are the streams, dimensions, frame count, and duration correct?&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Visual&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Does the world stay coherent? Do feet, rails, water, and transitions behave?&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Listening&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Are cue joins, noise, dynamics, and the ending acceptable on real playback?&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Sample frames around transitions and at the middle of procedural effects, not just the first and last frames. We caught a highlight problem at the peak of a light treatment: an 8-bit color calculation exceeded its valid range and wrapped. The endpoints looked fine. The fix was in the finishing calculation, not another generation attempt.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When replacing one part of an accepted film, verify that the parts meant to stay unchanged did stay unchanged. File hashes identify exact copies. Decoded-frame comparisons can check preserved picture across a container change. Neither substitutes for watching the new result.&lt;/p&gt;&lt;h2 id=&quot;9-expand-recover-and-keep-the-good-work&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;9. Expand, recover, and keep the good work&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A long render has more than one kind of success. Generation can finish even if a later copy, collection, or resource-restoration step fails. Inspect the output before rerunning the expensive part.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Save completed takes as they arrive. Record the input plate, prompt, seed, model revision, native output, and selected derivative for each shot. If a job is interrupted, resume from the missing work instead of regenerating everything that already passed review.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On shared hardware, record what resource settings you changed and restore those settings after the run. Check that restoration separately from the video artifact. A good clip does not prove the machine was returned to its previous state.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Agents and scripts are helpful for preparing shot packets, tracking outputs, making contact sheets, checking files, and assembling review pages. Give them explicit limits on retries, durations, and replacement scope. Keep creative selection with the person watching and listening. A process reporting success cannot decide that a walk feels natural.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The useful efficiency measure is accepted footage per production session. A faster model that creates more unusable takes may cost more time overall. Track rejected takes and the reasons for rejection before changing models or increasing concurrency.&lt;/p&gt;&lt;h2 id=&quot;10-derive-shorts-from-the-accepted-film&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;10. Derive Shorts from the accepted film&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Choose excerpts that contain a complete visual idea: a reveal, an arrival, a short action, or a change in the world. Reframe deliberately for vertical output. A centered crop can remove the destination, the feet, or the object that makes the action understandable.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Elsewhere&amp;#x27;s vertical edits reuse the accepted picture and soundtrack. Review the new crop, text placement, entrance, and ending as a separate edit. Keep a clean version as well as any version carrying a short hook or invitation to the full film. Captions belong where there is speech or useful context; an instrumental film does not need invented narration.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Watch the export at phone size with the platform&amp;#x27;s interface area in mind. Keep the important action visible, and listen to the actual exported audio. A short excerpt can expose a rough music boundary that was unnoticeable inside a longer cue.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Publication adds another review: correct file, title, thumbnail, links, visibility, processing, and playback. Follow the platform&amp;#x27;s current disclosure requirements. Local generation and an original prompt do not settle every source or usage question; retain the provenance and applicable licenses for the material you use.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Measure the audience response separately from production quality. Compare retention and traffic sources at similar release ages where possible. A Short&amp;#x27;s views do not prove that viewers continued to the full film, and a small audience sample does not establish why one opening performed differently.&lt;/p&gt;&lt;h2 id=&quot;your-first-local-film&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Your first local film&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Make the first deliverable small enough to finish:&lt;/p&gt;&lt;ol class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-decimal&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Write one paragraph describing a place, an action, and an ending.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Select a small set of locally sourced plates that agree about the world.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Prove the hardest action in one native motion take.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Build six distinct five-second shots with consistent technical settings.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Select or compose a local 30-second soundtrack and shape its ending.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Assemble, probe, decode, watch, and listen to the complete export.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Preserve the accepted version before trying a longer film or a vertical cut.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The lasting part of the Elsewhere workflow is the ability to inspect and revise each decision. You can replace a model, change an editor, or improve the hardware while keeping that method: define the experience, test its hardest part, preserve what works, and judge the film that the viewer will actually see.&lt;/p&gt;</content:encoded></item>
<item><title>A browser pool for agents that stop taking each other&#39;s tabs</title><link>https://www.danmercede.com/guides/multi-agent-browser-pool</link><guid isPermaLink="true">https://www.danmercede.com/guides/multi-agent-browser-pool</guid><pubDate>Mon, 12 Oct 2026 07:00:00 +0000</pubDate><description>How to give cooperative agents persistent Chrome identities, exclusive leases, and independent screens with the MIT-licensed orion-browser CLI and MCP server.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Orion tools in this guide are part of &lt;a href=&quot;https://www.cosmocrat.ai/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Cosmocrat OS&lt;/a&gt;. &lt;a href=&quot;https://www.cosmocrat.ai/docs&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Start with one workflow&lt;/a&gt;, using the exact releases and environment stated below. Each tool keeps its own installation, state and support boundaries.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two agents can have separate conversations and still be fighting over the same browser. One navigates away while the other is filling a form. A tab changes identity halfway through a task. The operator moves another window in front of Chrome, and an editor stops behaving as expected.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The browser had become shared mutable state with no owner.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our answer was &lt;strong class=&quot;font-semibold text-white&quot;&gt;orion-browser&lt;/strong&gt;: a small CLI and MCP server that gives cooperative agents a pool of signed-in Chrome browsers. Each configured identity has a persistent profile and its own virtual screen. An agent takes a time-limited lease, connects its existing browser driver to the returned DevTools endpoint, does its work, and releases the browser.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This guide explains that setup using generic identities. The &lt;a href=&quot;https://github.com/OrionArchitekton/orion-browser-oss&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;MIT-licensed source&lt;/a&gt; includes the implementation, synthetic tests, example configuration, security model, and operations runbook. The &lt;a href=&quot;https://www.danmercede.com/works/orion-browser/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Works page&lt;/a&gt; is the shorter overview.&lt;/p&gt;&lt;h2 id=&quot;what-the-pool-separates&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What the pool separates&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A &lt;strong class=&quot;font-semibold text-white&quot;&gt;browser&lt;/strong&gt; is a named identity, such as &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;work&lt;/code&gt; or &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;anon&lt;/code&gt;. Its &lt;strong class=&quot;font-semibold text-white&quot;&gt;profile&lt;/strong&gt; holds cookies, settings, and sign-in state across runs. A &lt;strong class=&quot;font-semibold text-white&quot;&gt;session&lt;/strong&gt; is one running Chrome process. A &lt;strong class=&quot;font-semibold text-white&quot;&gt;holder&lt;/strong&gt; is the agent session that owns the browser&amp;#x27;s current &lt;strong class=&quot;font-semibold text-white&quot;&gt;lease&lt;/strong&gt;.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;These distinctions determine what can happen in parallel:&lt;/p&gt;&lt;ul class=&quot;my-5 space-y-2 pl-6 text-slate-300 marker:text-copper-500 list-disc&quot;&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Different identities can run at the same time, on different virtual screens.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Different holders asking for the same identity are serialized by the lease.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Tabs inside one browser still share that browser and its identity. Making another tab does not create another lease.&lt;/p&gt;&lt;/li&gt;&lt;li class=&quot;leading-relaxed&quot;&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Releasing a browser ends its running session; it keeps the profile for the next session.&lt;/p&gt;&lt;/li&gt;&lt;/ul&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/browser-pool/architecture.webp&quot; alt=&quot;Two independent agents lease separate browsers, each with its own Chrome session, virtual screen, and persistent profile.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Parallel work uses separate identities. The CLI owns leases and session lifecycle; existing drivers connect directly to Chrome.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;We use headful Google Chrome on a virtual display served by TigerVNC, with noVNC for the operator&amp;#x27;s view. A systemd user service owns each running session. The agent&amp;#x27;s command can exit without taking the browser down with it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The lease service does not forward clicks or interpret page actions. It returns a CDP endpoint; tools such as agent-browser or Playwright connect directly. That keeps the integration small, but it also defines the trust boundary: &lt;strong class=&quot;font-semibold text-white&quot;&gt;this is coordination for agents on a trusted host, not isolation between untrusted tenants.&lt;/strong&gt;&lt;/p&gt;&lt;h2 id=&quot;start-with-two-generic-identities&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Start with two generic identities&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The host needs Linux with a working systemd user instance, Python 3.11 or later, and Google Chrome stable installed from Google&amp;#x27;s package. WSL2 can provide the Linux environment when systemd is enabled. The browser driver runs on the same host as the loopback endpoint.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;On an Ubuntu-style host, the operator installs the supporting display packages:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;sudo apt install tigervnc-standalone-server novnc websockify x11-apps xdotool&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Install the tagged source in a virtual environment:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;git clone --branch v0.1.0 https://github.com/OrionArchitekton/orion-browser-oss.git
cd orion-browser-oss
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
mkdir -p ~/.config/orion-browser
cp config.example.toml ~/.config/orion-browser/config.toml&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Python package and commands are named &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-browser&lt;/code&gt;. The public GitHub repository is named &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-browser-oss&lt;/code&gt;. Chrome and the distribution packages are separate dependencies with their own licenses; the MIT release does not bundle them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The example configuration includes:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;toml&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-toml&quot;&gt;[chrome]
path = &amp;quot;/usr/bin/google-chrome&amp;quot;

[screen]
width = 1920
height = 1080

[lease]
ttl_minutes = 30
max_minutes = 240

[[browser]]
name = &amp;quot;anon&amp;quot;
screen = 20

[[browser]]
name = &amp;quot;work&amp;quot;
screen = 21&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;anon&lt;/code&gt; signed in to nothing. Give &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;work&lt;/code&gt; only the accounts needed for its tasks. Add more identities when independent account groups need concurrent use, not merely because there are more agents.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Browser names must be unique and contain 1 to 16 lowercase letters or digits. Screen numbers must be unique and between 10 and 99. Reserve browser name &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;smoke&lt;/code&gt; and screen 89 for the optional real-browser smoke test.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Run the setup check:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser setup
orion-browser --json status&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Setup checks dependencies and creates owner-only directories. It does not install packages or run as root. Profiles default to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.local/share/orion-browser/profiles&lt;/code&gt;; state defaults to &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;~/.local/state/orion-browser&lt;/code&gt;. Keep both outside Git repositories. Downloads also belong outside source control.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;These dedicated profiles matter independently of leases. Chrome&amp;#x27;s &lt;a href=&quot;https://developer.chrome.com/blog/remote-debugging-port&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;remote debugging guidance&lt;/a&gt; requires a non-default user-data directory for remote debugging of regular Chrome from version 136 onward. Do not point a pool browser at your everyday profile.&lt;/p&gt;&lt;h2 id=&quot;sign-in-once-as-the-operator&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Sign in once, as the operator&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The operator takes a lease before typing credentials. This prevents a cooperative agent from taking the same browser during sign-in.&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser lease work --holder operator --minutes 60
orion-browser view work --drive --holder operator&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Open the returned drive link and sign in on the site&amp;#x27;s own page. Keep credentials and second-factor codes out of agent messages and files. Decline Chrome account sync: syncing a personal browser account can copy more passwords and history into this agent-accessible profile than the task needs.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then release the browser:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser release work --holder operator&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Check that the result reports &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;stop: clean&lt;/code&gt;. Lease it again, open the drive view, and verify the needed site remains signed in. The persistence check is per platform; a saved profile cannot promise that every site will accept a session indefinitely.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If a platform depends on restoring its session, the browser&amp;#x27;s configuration supports &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;restore_session = true&lt;/code&gt;. Enable it deliberately and repeat the stop/start check. Keeping tabs open is a different decision from keeping a persistent profile.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For observation, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-browser view work&lt;/code&gt; returns a watch-only link. That is a viewer setting, not an access-control boundary against another local process.&lt;/p&gt;&lt;h2 id=&quot;give-every-independent-worker-an-owner&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Give every independent worker an owner&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a CLI-driven agent, use a holder name unique to that agent session:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser --json lease work --holder research-42&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A successful response contains &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;data.endpoint&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;data.expires_at&lt;/code&gt;, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;data.watch&lt;/code&gt;. Connect your existing browser driver to that endpoint. With agent-browser already installed:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;agent-browser --session research-42 connect &amp;quot;&amp;lt;data.endpoint&amp;gt;&amp;quot; || exit 1
agent-browser --session research-42 eval &amp;quot;navigator.userAgent&amp;quot;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The angle-bracket value above is a placeholder for the actual returned endpoint. After connecting, check the driver&amp;#x27;s active browser user agent is not headless and confirm the intended page and identity before acting. Keep &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--session research-42&lt;/code&gt; on every subsequent driver command. A failed attach must not send subsequent commands to a driver&amp;#x27;s fallback browser. Do not hard-code a port from an earlier session. A new session starts Chrome on a newly allocated debugging port and reads the endpoint Chrome writes into its dedicated profile.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;When another holder requests &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;work&lt;/code&gt; before the lease expires, the CLI returns &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BUSY&lt;/code&gt; with the holder and expiry. Respect it. Wait, or use an appropriate different identity. Reusing the other agent&amp;#x27;s holder name defeats the coordination mechanism.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The anonymous browser can be leased independently:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser --json lease anon --holder research-43&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Now the two workers have different profiles, different Chrome processes, different screens, and different endpoints. They can work in parallel without sharing a browser&amp;#x27;s focus or tabs.&lt;/p&gt;&lt;h2 id=&quot;connecting-playwright-without-losing-the-profile&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Connecting Playwright without losing the profile&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Playwright can attach through its &lt;a href=&quot;https://playwright.dev/python/docs/api/class-browsertype#browser-type-connect-over-cdp&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Chromium CDP connection API&lt;/a&gt;. Use the existing default context, which contains the persistent profile. Creating a new isolated context would not give you the same signed-in state.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Install the optional driver in your agent environment with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;python -m pip install playwright&lt;/code&gt;. The following short example assumes setup has completed and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;anon&lt;/code&gt; is available. It reads a public page and releases the browser even if navigation fails:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;python&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-python&quot;&gt;import json
import subprocess
import uuid
from playwright.sync_api import sync_playwright

holder = &amp;quot;example-&amp;quot; + uuid.uuid4().hex[:12]

def pool(*args):
    result = subprocess.run(
        [&amp;quot;orion-browser&amp;quot;, &amp;quot;--json&amp;quot;, *args],
        check=True, capture_output=True, text=True,
    )
    return json.loads(result.stdout)

lease = pool(&amp;quot;lease&amp;quot;, &amp;quot;anon&amp;quot;, &amp;quot;--holder&amp;quot;, holder)
try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(lease[&amp;quot;data&amp;quot;][&amp;quot;endpoint&amp;quot;])
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        assert &amp;quot;Headless&amp;quot; not in page.evaluate(&amp;quot;navigator.userAgent&amp;quot;)
        page.goto(&amp;quot;https://example.com&amp;quot;, timeout=30000)
        print(page.title())
finally:
    pool(&amp;quot;release&amp;quot;, &amp;quot;anon&amp;quot;, &amp;quot;--holder&amp;quot;, holder)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Let the pool perform the lifecycle close so it can verify shutdown and clear the lease. If release fails, retain the error and inspect status; do not report that the browser was freed.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Playwright documents that CDP attachment has lower fidelity than its native protocol. Test the driver features your workflow actually needs. This pool manages Chrome lifecycle; it does not guarantee every driver feature or website will work.&lt;/p&gt;&lt;h2 id=&quot;mcp-has-one-holder-per-server-process&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;MCP has one holder per server process&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Register &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;orion-browser-mcp&lt;/code&gt; as a local stdio server in your MCP client, using the executable&amp;#x27;s absolute path when the client does not inherit your virtual environment&amp;#x27;s PATH. The server exposes three tools: &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;status&lt;/code&gt;, &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;lease&lt;/code&gt;, and &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;release&lt;/code&gt;. They call the same CLI used above.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Give the client enough time for startup and cleanup. The project&amp;#x27;s example timings can take about 955 seconds in the worst case; its README recommends a tool timeout of at least 1000 seconds. If you raise the timing settings, revisit that client timeout too.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The important ownership detail is the server process. &lt;strong class=&quot;font-semibold text-white&quot;&gt;All agents using one MCP server share its holder, including subagents.&lt;/strong&gt; If two subagents lease &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;work&lt;/code&gt; through that server, the second call renews the same lease and receives the same endpoint. It does not return &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BUSY&lt;/code&gt; to distinguish them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Use different browsers for parallel subagents, or use the CLI with a distinct holder per worker. Separate MCP server processes also have separate holder identities. A centralized MCP connection does not create one lease owner per conversation automatically.&lt;/p&gt;&lt;h2 id=&quot;renew-before-expiry-and-release-when-finished&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Renew before expiry and release when finished&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Renew by leasing the same browser with the same holder:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser --json lease work --holder research-42&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Renew well before the returned expiry, allowing time for slow page operations. After any interruption, obtain a successful lease or renewal before continuing and use its current endpoint. If it changed, reconnect the driver.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Expiry is permission for another holder to take over. It is not an automatic kill timer. With no takeover, the old session can keep running, and the same holder may renew it. When a different holder takes over, the pool stops the old session, verifies it is gone, and starts another Chrome process. If it cannot prove the old session stopped, it refuses the handoff.&lt;/p&gt;&lt;figure class=&quot;my-8 lg:-mx-20 lg:w-[calc(100%+10rem)]&quot;&gt;&lt;img src=&quot;https://www.danmercede.com/assets/guides/browser-pool/lifecycle.webp&quot; alt=&quot;A lease lifecycle showing acquisition, renewal by the same holder, release, and takeover by a new holder after expiry.&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; class=&quot;h-auto w-full rounded-lg border border-white/10 bg-slate-900/40&quot;/&gt;&lt;figcaption class=&quot;mt-3 text-center text-sm text-slate-400&quot;&gt;Expiry permits takeover. A successful takeover replaces the old browser session; expiry alone does not stop it.&lt;/figcaption&gt;&lt;/figure&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Release as soon as the task ends:&lt;/p&gt;&lt;div class=&quot;my-6 overflow-hidden rounded-lg border border-white/10 bg-slate-950/90&quot;&gt;&lt;div class=&quot;flex items-center justify-between border-b border-white/10 bg-navy-deep/60 px-4 py-2&quot;&gt;&lt;span class=&quot;font-mono text-xs text-slate-400&quot;&gt;bash&lt;/span&gt;&lt;button type=&quot;button&quot; class=&quot;font-mono text-xs text-slate-400 hover:text-copper-400 transition-colors&quot; aria-label=&quot;Copy code block&quot;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre class=&quot;overflow-x-auto p-4 text-sm leading-relaxed&quot;&gt;&lt;code class=&quot;font-mono text-slate-300 language-bash&quot;&gt;orion-browser --json release work --holder research-42&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The normal path asks Chrome to close through DevTools before stopping the rest of the session. A forced signal or kill can lose recently written sign-in state. Read the stop result rather than assuming every termination persisted the profile.&lt;/p&gt;&lt;h2 id=&quot;diagnose-the-boundary-that-failed&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Diagnose the boundary that failed&lt;/h2&gt;&lt;div class=&quot;my-6 overflow-x-auto&quot;&gt;&lt;table class=&quot;w-full border-collapse text-left text-sm&quot;&gt;&lt;thead&gt;&lt;tr class=&quot;border-b border-copper-500/30&quot;&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Result&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;What it means&lt;/th&gt;&lt;th class=&quot;px-3 py-2 font-semibold text-white&quot;&gt;Next step&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BUSY&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Another holder owns the lease, or lifecycle work exceeded its wait&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Read the holder and expiry; wait or choose another suitable browser&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;NOT_HOLDER&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The caller does not own the lease&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Stop acting on the old endpoint; acquire a lease legitimately&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;USAGE&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Arguments, configuration, or state could not be accepted&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Correct the named issue; never treat unreadable lease state as free&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;BROWSER_DOWN&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;No session, failed startup, or shutdown could not be proven&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Read the named process, port, or service issue before retrying&lt;/td&gt;&lt;/tr&gt;&lt;tr class=&quot;border-b border-white/5&quot;&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;&lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;UNHEALTHY&lt;/code&gt;&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;The session runs but failed one or more health checks&lt;/td&gt;&lt;td class=&quot;px-3 py-2 align-top text-slate-300&quot;&gt;Inspect the reported checks and the operations runbook&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The health proof checks the service, current endpoint, page visibility and focus, headful user agent, automation marker, and a non-uniform screen capture. It does not prove sign-in success or completion of the task. A healthy browser can still be on the wrong page.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The current implementation starts Chrome with &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;--disable-blink-features=AutomationControlled&lt;/code&gt; and checks that &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;navigator.webdriver&lt;/code&gt; is false. This is a disclosed implementation choice based on the project&amp;#x27;s sign-in checks, not a promise that sites cannot detect automation or that automated use is permitted. Site requirements still apply.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Session audit records describe leases, extensions, starts, stops, takeovers, and failures. They deliberately omit page content, typed text, and screenshots. They can explain ownership and lifecycle, but they cannot prove that a form was submitted correctly.&lt;/p&gt;&lt;h2 id=&quot;keep-authority-separate-from-the-lease&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Keep authority separate from the lease&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A signed-in browser can post, send, purchase, or delete with the account&amp;#x27;s authority. A lease only coordinates who uses the browser. It does not approve those actions.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our agent instructions require an explicit task-level request before sending or publishing, the relevant content checks before typing public text, and verification on the destination after an authorized action. Pages are untrusted input; a message on a page cannot grant new authority.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Loopback binding reduces network exposure, but local processes can reach CDP and the viewer without presenting a lease. The viewer&amp;#x27;s watch-only option is not enforced by the VNC server. Profiles contain live sign-in state, and this implementation uses Chrome&amp;#x27;s basic password store for unattended startup. Do not use this design as a hostile multi-user service or an internet-facing browser provider.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Read the complete &lt;a href=&quot;https://github.com/OrionArchitekton/orion-browser-oss/blob/main/SECURITY.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;security model&lt;/a&gt; before signing in. The operational benefit is specific: cooperative agents get explicit browser ownership, persistent identities, and independent screens. Account permissions and publishing decisions remain separate responsibilities.&lt;/p&gt;&lt;h2 id=&quot;verify-a-setup-before-giving-it-real-work&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Verify a setup before giving it real work&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;From the source checkout, install the development extra and run &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;python -m pytest -q&lt;/code&gt;. Those tests exercise the real CLI and MCP tools against synthetic dependencies; they do not open Chrome or sign in to anything.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The optional &lt;code class=&quot;rounded-sm bg-slate-800/70 px-1.5 py-0.5 font-mono text-[0.85em] text-copper-300&quot;&gt;tests/smoke_real_browser.py&lt;/code&gt; exercises the real local stack on its reserved anonymous profile and screen. Follow the &lt;a href=&quot;https://github.com/OrionArchitekton/orion-browser-oss/blob/main/docs/runbooks/orion-browser-operations.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;operations runbook&lt;/a&gt; before running it. It checks a synthetic cookie across clean restarts and verifies that the previous endpoint stops answering. It does not verify your signed-in accounts.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then run one small authorized task per intended identity. Confirm the right account, verify the requested result at the destination, and release the browser. That last check is what turns a functioning browser pool into a completed piece of work.&lt;/p&gt;</content:encoded></item>
<item><title>The Transcript Looked Complete</title><link>https://www.danmercede.com/thoughts/2026-10-12-the-transcript-looked-complete</link><guid isPermaLink="true">https://www.danmercede.com/thoughts/2026-10-12-the-transcript-looked-complete</guid><pubDate>Mon, 12 Oct 2026 07:00:00 +0000</pubDate><description>Readable AI text does not establish coverage of its input; unresolved discrepancies require a source check before consequential claims become an accepted business record.</description><content:encoded>&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;If your team turns AI meeting notes into customer commitments, who checks what the record left out?&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Imagine an account manager leaving a call with notes that say a customer accepted a delivery date. The customer also made that acceptance conditional on a security review. If the condition disappears from the record, the next person sees a commitment the customer never made. The project owner inherits a promise they cannot safely rely on, and the cost is rework, an uncomfortable customer conversation, or a date the team should never have accepted.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That is a hypothetical customer example. The evidence behind this week&amp;#x27;s edition comes from a smaller, internal workflow: AI transcription for a video. It exposes the same ownership question. Before a record becomes something another person acts on, who is responsible for checking the consequential parts against their source?&lt;/p&gt;&lt;h2 id=&quot;two-records-of-one-take&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Two records of one take&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Two saved transcripts from the same recording disagreed. In the word-timed output from one model, a word ended at 54.48 seconds and the next started at 83.06 seconds. No word started inside that 28.58-second interval. The other output placed 54 word records there.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Those are 54 model-produced records, not 54 independently verified spoken words. A second transcription can be wrong too. The source interval also contains nonzero audio, but a waveform does not establish what was said. What these checks establish is a discrepancy that the text alone cannot settle.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Read without the timestamps or the comparison, the shorter transcript offers no way to distinguish a passage it did not capture from a passage that never existed. The missing information is absent from the thing the reviewer is reading.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;No customer relied on this recording. No missed deadline or financial loss is evidenced here. It is a video-editing case, and the retained outputs do not establish what appeared in every finished caption. The useful observation is narrower: two plausible records of one input leave materially different evidence available to the next step.&lt;/p&gt;&lt;h2 id=&quot;a-summary-inherits-the-record-s-limits&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;A summary inherits the record&amp;#x27;s limits&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Return to the hypothetical customer call. The summarizer receives the transcript and turns it into decisions, owners, and next actions. If a condition never reached the transcript, a summarizer working only from that transcript has no reliable way to recover it. Asking for a more careful summary does not supply the missing source.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The account manager can then check the summary against the transcript and find agreement. That agreement establishes that the summary reflects this record. It says nothing about whether this record captured the customer&amp;#x27;s condition.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The workflow now has several tidy outputs: a transcript, a meeting summary, a task, and perhaps a customer-record update. They all agree because they all depend on the same incomplete account. Adding another AI to check the summary against that account does not create independent evidence of the call.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This matters wherever AI turns an input into something with operational force. The question is not just whether the generated sentences are defensible. It is whether the information needed for the particular decision survived the handoff, and who accepts that judgment before the decision travels further.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Check the record against what it was meant to cover.&lt;/p&gt;&lt;h2 id=&quot;someone-has-to-accept-the-record&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Someone has to accept the record&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A transcript service produces text. The owner of the business workflow decides when that text is usable for the job. Those responsibilities meet at an acceptance step, and the step needs a named person with access to appropriate source evidence.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For the customer-call example, that person might be the account manager. Their acceptance criteria should identify what can change the team&amp;#x27;s obligations: conditions, dates, amounts, promised scope, who agreed, and what remains unresolved. These are claims to check, not a request to approve the prose&amp;#x27;s general quality.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A readable document should not automatically turn an uncertain commitment into an accepted one. If the owner cannot resolve a consequential discrepancy, the workflow needs a visible unresolved state and a route to clarification. The related task should remain provisional, or wait for confirmation, according to the business&amp;#x27;s rules.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;That does not require treating every spelling error like a customer promise. The acceptance effort belongs at the claims whose loss or distortion changes an obligation. A rough transcript for searching a personal recording and a record used to authorize a customer commitment have different consequences. Their owners should choose the bar explicitly.&lt;/p&gt;&lt;h2 id=&quot;what-the-engineering-checks-actually-establish&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;What the engineering checks actually establish&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Our local editing code transcribes the finished voice track rather than only transferring word times from the original take. That matters because the finished track is the input its captions need to cover. Comparing against an earlier version answers a different question.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The code divides transcription around detected silences and retries stretches with suspiciously few words. It also compares a piece&amp;#x27;s word count with another transcription of its source range. These checks can locate disagreement and bring a stretch back for examination. They cannot establish complete or accurate transcription.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Speech is uneven. A low word count can reflect a pause, a slow sentence, or a transcription problem. A higher count on a retry can include invented words. Two models can agree and still omit the same thing. A threshold is useful for deciding where to look; it is not evidence that every passage above it is correct.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For a business workflow, retain enough permitted source information to resolve the claims that matter. That can mean a recording and timestamps where recording is allowed, or confirmation of decisions by the people on the call. Consent, access, and retention limits still apply. If no appropriate source is available, the record should say what cannot be verified and seek confirmation before creating an obligation.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Keep the accepted record identifiable as well. The local code caches an initial transcription using the audio, prompt, and window settings, but later filters and corrections still apply. That cache alone does not prove the final captions are the reviewed text. A business acceptance step should identify the record it accepted and require material changes to be checked again.&lt;/p&gt;&lt;h2 id=&quot;try-one-consequential-passage&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Try one consequential passage&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Choose a recent workflow where an AI record supported an action. Pick one consequential claim: an agreed date, a qualification, or a condition attached to a promise. Use an input you are allowed to inspect.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Trace that claim from its source through the transcript, summary, and resulting task. Check what was preserved, what was shortened, and whether the resulting action carries the condition that makes it valid. If the source says a date depends on a review, the task should not quietly turn it into an unconditional date.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Then ask who accepted that claim and what happened to discrepancies. A reviewer initialling the summary proves little if they had no source reference and were checking only how the summary read. If the workflow has no place to record an unresolved condition, the next person can mistake missing evidence for an agreed answer.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;This is a small inspection, not a certificate for the workflow. Finding a discrepancy gives you a concrete repair to make. Finding none in this passage establishes only what you inspected. It does not demonstrate that every other passage or future call will survive the same handoffs.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;A named person accepts the consequential claims.&lt;/p&gt;&lt;h2 id=&quot;make-the-uncertainty-travel-too&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;Make the uncertainty travel too&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;An unresolved claim should remain unresolved in the next system. If a customer date still needs confirmation, a summary, task board, or customer record should carry that status and an owner for resolving it. Otherwise the handoff erases the warning while preserving the sentence.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Engineers can make this visible by recording the source reference, the accepted revision, the person accepting it, and any unresolved claims alongside the resulting action. The business owner chooses which unresolved claims prevent commitment and which allow a provisional next step. The software implements that choice; a model&amp;#x27;s confidence should not silently make it.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;For one workflow, name the input, the person accepting its consequential claims, the source they can check, and the action that waits when a claim remains unresolved. That gives a team something specific to operate and inspect. It also tells the person receiving the record what has been established and what still requires a decision.&lt;/p&gt;&lt;h2 id=&quot;if-your-team-relies-on-ai-records&quot; class=&quot;mt-12 mb-4 scroll-mt-24 text-2xl md:text-3xl font-bold text-white&quot; tabindex=&quot;-1&quot;&gt;If your team relies on AI records&lt;/h2&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The two saved transcripts did not give us a customer incident or a universal verdict on either model. They gave us a reason to question what the record covered. That question belongs before the record becomes a commitment, not only after someone notices a problem.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;Ask where an AI output first becomes something another person is expected to trust. Name who accepts it, what evidence they check, and what happens when they cannot resolve a consequential claim. If those answers are missing, the team has assigned the next person uncertainty without showing it to them.&lt;/p&gt;&lt;p class=&quot;my-4 leading-relaxed text-slate-300&quot;&gt;The Readiness Scan my agency offers maps one workflow, its failure modes, and who owns its handoffs. That includes the point where an AI-generated record becomes a business commitment. &lt;a href=&quot;https://www.orionintelligenceagency.com/readiness-scan?utm_source=linkedin&amp;amp;utm_medium=newsletter&amp;amp;utm_campaign=readiness_scan&amp;amp;utm_content=fcn_ed13&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot; class=&quot;text-copper-400 underline decoration-copper-500/40 underline-offset-2 hover:text-copper-300&quot;&gt;Work with OIA on one workflow&lt;/a&gt;.&lt;/p&gt;</content:encoded></item>
</channel>
</rss>
