Folder: the browser section explains how a page reaches the Operator, and the agent chooses the way (F38 addendum, base-instructions-44)

docs/decisions.md

@@ -5739,6 +5739,33 @@ from there:
 The "A personal browser" point now points to this one instead of repeating it. Template
 revision `base-instructions-42`.
 
+**Addendum 2026-10-12, asked for by the Organization Admin: the Folder explains how a page
+reaches the Operator, and the agent chooses the way.** A page reaches the Operator in
+several ways:
+- a plain link opens it in their own browser on their computer;
+- a link to a tab of the Environment shows that tab of the Environment browser, with the
+  Environment's sign-ins and network;
+- web T3 Code puts the thread's window in its right panel's strip by itself, and opens the
+  panel on it while the thread is in view on a wide screen; otherwise the tab waits in the
+  strip.
+
+Each client does something else with each of them: ChatGPT Desktop's built-in browser and
+the right panel of the T3 Code desktop app run on the Operator's computer. Rules for which
+way to take would miss combinations, such as a plain address the Operator opens in ChatGPT
+Desktop's browser while the agent is to work in that page. So the Folder manual's browser
+section now explains the ways and what each client does with them, and leaves the choice
+to the agent. The aim is that the Operator sees the page as simply as possible and the
+same way in every client. The section also says that people mostly like to see the pages
+an agent works with beside the chat, even without asking, and close what they do not want.
+
+The boundaries stay:
+- browser work happens in the Environment's browser;
+- only the Operator signs in;
+- a new page opens in a new tab;
+- a window is let go of, never closed for everyone.
+
+Template revision `base-instructions-44`.
+
 ## F39 — The people's view of the Environment browser: one tab of a person is one remote tab
 
 **Decided by Matěj 2026-10-06 after the pilot (root decision 0191 points 11–18, plan

src/folder/render.ts

@@ -41,7 +41,7 @@ import { ownDataValue, stateFields } from "./state-fields";
 // future persisted preference schemas. Every change of the generated bytes
 // moves it to the next number; tests/folder-template-revision.test.ts pins the
 // rendered digest of the current one (decision F14, addendum 2026-10-03).
-export const instructionTemplateRevision = "base-instructions-43";
+export const instructionTemplateRevision = "base-instructions-44";
 
 // Template revisions are ordered by their number. A Folder rendered by an
 // older revision is re-rendered by the next change of the generated Folder

tests/__snapshots__/folder-render.test.ts.snap

@@ -2,7 +2,7 @@
 
 exports[`rendered AGENTS.md snapshot: local / cs 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"local","profile":{"os":"macos","access":"local","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"local","profile":{"os":"macos","access":"local","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
 ## Tenhle Environment
 - Preset: \`local\` (verze 1).
 - Pracovní stanice Operátora bez handoveru; Owner i Operátor je přihlášený uživatel.
@@ -51,7 +51,7 @@ Používej nejdřív tahle CLI z katalogu Lazuria, jak je popisuje \`manual/this
 
 exports[`rendered AGENTS.md snapshot: local / en 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"local","profile":{"os":"macos","access":"local","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"local","profile":{"os":"macos","access":"local","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`local\` (version 1).
 - The Operator's own workstation, no handover; the signed-in user is both Owner and Operator.
@@ -100,7 +100,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`rendered AGENTS.md snapshot: hosted-personal / cs 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
 ## Tenhle Environment
 - Preset: \`hosted-personal\` (verze 1).
 - Název: \`example\` (personal-vm).
@@ -156,7 +156,7 @@ Používej nejdřív tahle CLI z katalogu Lazuria, jak je popisuje \`manual/this
 
 exports[`rendered AGENTS.md snapshot: hosted-personal / en 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-personal\` (version 1).
 - Name: \`example\` (personal-vm).
@@ -212,7 +212,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`rendered AGENTS.md snapshot: hosted-organization-personal / cs 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
 ## Tenhle Environment
 - Preset: \`hosted-organization-personal\` (verze 1).
 - Název: \`workspace\` (workspace-vm).
@@ -268,7 +268,7 @@ Používej nejdřív tahle CLI z katalogu Lazuria, jak je popisuje \`manual/this
 
 exports[`rendered AGENTS.md snapshot: hosted-organization-personal / en 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-organization-personal\` (version 1).
 - Name: \`workspace\` (workspace-vm).
@@ -324,7 +324,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`rendered AGENTS.md snapshot: hosted-organization-team / cs 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-team","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-team","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
 ## Tenhle Environment
 - Preset: \`hosted-organization-team\` (verze 1).
 - Název: \`workspace\` (workspace-vm).
@@ -381,7 +381,7 @@ Používej nejdřív tahle CLI z katalogu Lazuria, jak je popisuje \`manual/this
 
 exports[`rendered AGENTS.md snapshot: hosted-organization-team / en 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-team","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-team","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-organization-team\` (version 1).
 - Name: \`workspace\` (workspace-vm).
@@ -438,7 +438,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`rendered AGENTS.md snapshot: hosted-organization-steward / cs 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-steward","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-steward","profile":{"os":"linux","access":"remote","purpose":"human","locale":"cs","detail":"concise","coordination":"direct"}} -->
 ## Tenhle Environment
 - Preset: \`hosted-organization-steward\` (verze 1).
 - Název: \`workspace\` (workspace-vm).
@@ -499,7 +499,7 @@ Používej nejdřív tahle CLI z katalogu Lazuria, jak je popisuje \`manual/this
 
 exports[`rendered AGENTS.md snapshot: hosted-organization-steward / en 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-steward","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-steward","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-organization-steward\` (version 1).
 - Name: \`workspace\` (workspace-vm).
@@ -560,7 +560,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`relationships render only when the recorded binding carries them, one line per peer 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-personal\` (version 1).
 - Name: \`example\` (personal-vm).
@@ -620,7 +620,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`the Assignment line renders the handover's owner.assignment and nothing else 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-organization-personal\` (version 1).
 - Name: \`workspace\` (workspace-vm).
@@ -677,7 +677,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`the Assignment line renders the handover's owner.assignment and nothing else 2`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-team","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-team","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-organization-team\` (version 1).
 - Name: \`workspace\` (workspace-vm).
@@ -735,7 +735,7 @@ The complete agent manual for this Environment is in \`manual/\` (generated by t
 
 exports[`the Owner line names the Team only under hosted-organization-team 1`] = `
 "# Lazurio
-<!-- base-instructions-43; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
+<!-- base-instructions-44; {"preset":"hosted-organization-personal","profile":{"os":"linux","access":"remote","purpose":"human","locale":"en","detail":"concise","coordination":"direct"}} -->
 ## This Environment
 - Preset: \`hosted-organization-personal\` (version 1).
 - Name: \`workspace\` (workspace-vm).

tests/environment-browser.test.ts

@@ -661,6 +661,10 @@ test("a thread's window: the bound one while it is open, otherwise a new window
     targetId: "OPEN",
     created: false,
   });
+  // An address never moves the open window (the Folder manual says so).
+  expect(
+    await ensureThreadWindow("codex-a", "https://example.org", reused.seams),
+  ).toEqual({ session: "codex-a", targetId: "OPEN", created: false });
   expect(reused.calls).toEqual([]);
 
   // Bound but closed, or never bound: a new window in the default context
@@ -878,6 +882,88 @@ test("the Folder opens a new page in a new tab and names T3 Code's preview tools
   }
 });
 
+// How a page reaches the Operator is explained, not prescribed (F38 addendum of
+// 2026-10-12): a plain link, a link to a tab of the Environment, and what each
+// client does with them, with ChatGPT Desktop's own browser on the Operator's
+// computer, so the agent chooses the way.
+test("the Folder explains how a page reaches the Operator in each client and leaves the way to the agent", () => {
+  for (const locale of ["cs", "en"] as const) {
+    const text = renderManual({
+      preset: "hosted-organization-personal",
+      machine: bindings.organizationBrowser,
+      profile: presetProfile("hosted-organization-personal", "linux", {
+        locale,
+      }),
+    })["manual/this-machine.md"];
+    const section = text.slice(
+      text.indexOf(
+        locale === "cs"
+          ? "### Jak Operátor stránku uvidí"
+          : "### How the Operator sees a page",
+      ),
+      text.indexOf(
+        locale === "cs"
+          ? "### Práce v prohlížeči"
+          : "### Working in the browser",
+      ),
+    );
+    const ways =
+      locale === "cs"
+        ? [
+            "**Obyčejný odkaz**",
+            "**Odkaz na záložku Environmentu**",
+            "**Webové T3 Code**",
+            "**ChatGPT Desktop**",
+            "**Launchpad**",
+            "vyber tu, která mu dává největší smysl",
+            "rádi vidí rovnou vedle chatu",
+          ]
+        : [
+            "**A plain link**",
+            "**A link to a tab of the Environment**",
+            "**Web T3 Code**",
+            "**ChatGPT Desktop**",
+            "**The Launchpad**",
+            "choose the one that makes the most sense to them",
+            "right beside the chat",
+          ];
+    for (const way of ways) expect(section).toContain(way);
+    const bullet = (lead: string) =>
+      section.split("\n").find((line) => line.startsWith(`- **${lead}`)) ?? "";
+    // A plain address the Operator opens in ChatGPT Desktop runs on their
+    // computer: the agent opens it in a new tab of the Environment browser,
+    // never with `lazurio browser window --url`, which keeps a window it has.
+    const desktop = bullet("ChatGPT Desktop");
+    expect(desktop).toContain(
+      locale === "cs" ? "bod Nová záložka" : "the point A new tab",
+    );
+    expect(desktop).not.toContain("lazurio browser window");
+    // Web T3 opens the panel by itself only for a thread in view on a wide
+    // screen; otherwise the agent's tab waits in the strip.
+    expect(
+      bullet(locale === "cs" ? "Webové T3 Code" : "Web T3 Code"),
+    ).toContain(
+      locale === "cs"
+        ? "počká v liště panelu"
+        : "waits for them in the panel's strip",
+    );
+    const yourWindow =
+      text
+        .split("\n")
+        .find((line) =>
+          line.startsWith(
+            locale === "cs" ? "- **Tvoje okno.**" : "- **Your window.**",
+          ),
+        ) ?? "";
+    expect(yourWindow).toContain(
+      locale === "cs"
+        ? "Adresa z `--url` platí jen pro nové okno"
+        : "`--url` applies only to a new window",
+    );
+    expect(text).not.toMatch(/Pohled pro Operátora|The Operator's view\.\*\*/);
+  }
+});
+
 // Root decision 0191 point 28: an agent lets go of its window when its work
 // there is done, and the hub ends the tab once nothing holds or views it. It
 // never closes the tab for everyone with agent-browser's `tab close`.

tests/folder-template-revision.test.ts

@@ -21,8 +21,8 @@ import { bindings } from "./fixtures/machine-bindings";
 // `bun test -u` does not touch it. The fixtures in `tests/fixtures` feed the
 // compositions too.
 const pinned = {
-  revision: "base-instructions-43",
-  digest: "459a4c22e46ca232fa8687c00797ec74970d9d3e2d65b714cf97847316fdaae9",
+  revision: "base-instructions-44",
+  digest: "baba44d2bc9d107005c03a4bee7d73c012553eb5ec351c469dc7cd4aa35b35f0",
 } as const;
 
 const optionalTools = activatableTools()

tests/folder-tools.test.ts

@@ -719,7 +719,7 @@ test("a profile change and a handover refresh carry the enabled tools forward",
 });
 
 test("a Folder rendered by an older template revision is upgraded by a tools change", async () => {
-  expect(instructionTemplateRevision).toBe("base-instructions-43");
+  expect(instructionTemplateRevision).toBe("base-instructions-44");
   const { preferences, manifest } = await planned();
   const older = {
     ...manifest,
@@ -742,7 +742,7 @@ test("a Folder rendered by an older template revision is upgraded by a tools cha
       recorded,
     );
     if (upgrade.kind !== "profile-change") throw new Error("Expected upgrade");
-    expect(upgrade.manifest.templateRevision).toBe("base-instructions-43");
+    expect(upgrade.manifest.templateRevision).toBe("base-instructions-44");
     expect(upgrade.previous).toEqual(older.outputs);
     expect(enabledTools(upgrade.preferences)).toEqual(tools);
     expect(upgrade.files).toEqual(