shadok-ai 0.17.3 → 0.17.5

package/dist/live-handover.d.ts

@@ -0,0 +1,47 @@
+import type { WebSocket } from "ws";
+/**
+ * The subset of a `Live` that a handover reads and mutates. Kept structural so
+ * the server's full `Live` satisfies it with no cast, and a test can build a
+ * fake. It DELIBERATELY omits `pilot`, `cwd`, `id` and `transcriptHome`: the
+ * handover must never be able to kill the agent or clear the shared tail
+ * position, and leaving those fields out of the type makes that a compile-time
+ * guarantee rather than a comment someone can regress past.
+ */
+export interface HandoverLive {
+    clients: Set<WebSocket>;
+    rawClients?: Set<WebSocket>;
+    screenTimer: ReturnType<typeof setInterval> | null;
+    idleTimer: ReturnType<typeof setTimeout> | null;
+    retryTimer: ReturnType<typeof setTimeout> | null;
+    stopTail: (() => void) | null;
+    rawOff?: (() => void) | null;
+}
+/**
+ * Hand a superseded `Live`'s viewers onto the `Live` that replaced it, and quiet
+ * the old one WITHOUT touching the agent. Returns how many viewers moved.
+ *
+ * The bug (shared-ledger [5d8d]): when a session's pilot has exited but the
+ * channel still has web/Telegram viewers attached, a resume takes the
+ * `createSession` path and `sessions.set(id, newLive)` REPLACES the registry
+ * entry — leaving the old `Live`, with its clients, orphaned. Its tail keeps
+ * running on the same transcript, so those clients still see the agent's
+ * ANSWERS, but every `broadcast` now targets the new `Live`: they miss the other
+ * interfaces' prompt echoes (the reported symptom: Telegram messages invisible
+ * on the web until reload), dialogs, and working/turn-done. Two `Live` for one
+ * agent; "server code correct in isolation", the split is the cause.
+ *
+ * The cure is one `Live` per agent: hand the viewers over and tear the old one
+ * down. Teardown here is DELIBERATELY not `destroySession`. The new `Live` may
+ * have adopted the very same tmux pane — a `hasExited` that latched on a single
+ * transient probe (invariants 23/25) leaves the pane alive — so killing the old
+ * pilot would kill the live agent, and clearing the shared tail position would
+ * make the new tail replay the whole transcript from byte 0. So we stop the old
+ * `Live`'s own tail and timers and detach its raw pipe, and nothing else. (The
+ * type can't express `pilot.kill()` or `clearTailPos` anyway — see `HandoverLive`.)
+ *
+ * Raw terminal viewers are NOT re-wired onto the new pilot's pipe: the raw
+ * subscription is per-pilot and is rebuilt when the engine room is next opened.
+ * Moving the chat `clients` set is what the reported bug needs; the old raw pipe
+ * is simply turned off so the retired `Live` goes fully quiet.
+ */
+export declare function supersedeSession(old: HandoverLive, next: HandoverLive): number;

package/dist/live-handover.js

@@ -0,0 +1,58 @@
+/**
+ * Hand a superseded `Live`'s viewers onto the `Live` that replaced it, and quiet
+ * the old one WITHOUT touching the agent. Returns how many viewers moved.
+ *
+ * The bug (shared-ledger [5d8d]): when a session's pilot has exited but the
+ * channel still has web/Telegram viewers attached, a resume takes the
+ * `createSession` path and `sessions.set(id, newLive)` REPLACES the registry
+ * entry — leaving the old `Live`, with its clients, orphaned. Its tail keeps
+ * running on the same transcript, so those clients still see the agent's
+ * ANSWERS, but every `broadcast` now targets the new `Live`: they miss the other
+ * interfaces' prompt echoes (the reported symptom: Telegram messages invisible
+ * on the web until reload), dialogs, and working/turn-done. Two `Live` for one
+ * agent; "server code correct in isolation", the split is the cause.
+ *
+ * The cure is one `Live` per agent: hand the viewers over and tear the old one
+ * down. Teardown here is DELIBERATELY not `destroySession`. The new `Live` may
+ * have adopted the very same tmux pane — a `hasExited` that latched on a single
+ * transient probe (invariants 23/25) leaves the pane alive — so killing the old
+ * pilot would kill the live agent, and clearing the shared tail position would
+ * make the new tail replay the whole transcript from byte 0. So we stop the old
+ * `Live`'s own tail and timers and detach its raw pipe, and nothing else. (The
+ * type can't express `pilot.kill()` or `clearTailPos` anyway — see `HandoverLive`.)
+ *
+ * Raw terminal viewers are NOT re-wired onto the new pilot's pipe: the raw
+ * subscription is per-pilot and is rebuilt when the engine room is next opened.
+ * Moving the chat `clients` set is what the reported bug needs; the old raw pipe
+ * is simply turned off so the retired `Live` goes fully quiet.
+ */
+export function supersedeSession(old, next) {
+    let moved = 0;
+    for (const c of old.clients) {
+        next.clients.add(c);
+        moved++;
+    }
+    old.clients.clear();
+    // Quiet the retired Live: its own tail (so one transcript is not tailed
+    // twice — the "two tails share one pos file" side effect noted in [5d8d]),
+    // its timers, and its raw pipe. Never the pilot, never the tail position.
+    if (old.screenTimer) {
+        clearInterval(old.screenTimer);
+        old.screenTimer = null;
+    }
+    if (old.idleTimer) {
+        clearTimeout(old.idleTimer);
+        old.idleTimer = null;
+    }
+    if (old.retryTimer) {
+        clearTimeout(old.retryTimer);
+        old.retryTimer = null;
+    }
+    old.stopTail?.();
+    old.stopTail = null;
+    old.rawOff?.();
+    old.rawOff = null;
+    old.rawClients?.clear();
+    return moved;
+}
+//# sourceMappingURL=live-handover.js.map

package/dist/live-handover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-handover.js","sourceRoot":"","sources":["../src/live-handover.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAiB,EAAE,IAAkB;IACpE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,KAAK,EAAE,CAAC;IACV,CAAC;IACD,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAEpB,wEAAwE;IACxE,2EAA2E;IAC3E,0EAA0E;IAC1E,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC/B,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC;IACzB,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5B,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC;IACvB,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACnB,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC7B,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;IACjB,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC;IACpB,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;IACf,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC;IAClB,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC;IAExB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/selfrepo.d.ts

@@ -6,8 +6,16 @@
  * diff before connecting any GitHub account.
  */
 export declare const SELF_REPO_URL = "https://github.com/shadok-ai/shadok-ai.git";
-/** Our own copy, never the directory the running server was launched from. */
-export declare function selfRepoDir(): string;
+/**
+ * Our own copy, never the directory the running server was launched from.
+ * `stateHome` defaults to the server's own home (mono-tenant / commons before
+ * migration), but is the DROPPED agent's home (`/home/<user>`) once agents run
+ * as a non-root OS user: the server's `/root` is mode 0700 and un-traversable by
+ * that user, so a clone there strands the Tweak agent — same reason as
+ * `worktreeDir` in `worktree.ts`. The caller makes the clone writable by the
+ * drop user; this only fixes WHERE it lands.
+ */
+export declare function selfRepoDir(stateHome?: string): string;
 export type SelfRepoPlan = "clone" | "update" | "reclone";
 /** Pure: what to do with the checkout, given what is on disk. */
 export declare function selfRepoPlan(exists: boolean, isRepo: boolean): SelfRepoPlan;
@@ -26,4 +34,4 @@ export interface SelfRepoResult {
  * worktrees a tweak session owns are separate checkouts and are never touched —
  * refreshing under a live agent is how you lose its work.
  */
-export declare function ensureSelfRepo(): SelfRepoResult;
+export declare function ensureSelfRepo(stateHome?: string): SelfRepoResult;

package/dist/selfrepo.js

@@ -10,9 +10,17 @@ import path from "node:path";
  * diff before connecting any GitHub account.
  */
 export const SELF_REPO_URL = "https://github.com/shadok-ai/shadok-ai.git";
-/** Our own copy, never the directory the running server was launched from. */
-export function selfRepoDir() {
-    return path.join(os.homedir(), ".shadok-ai", "self", "shadok-ai");
+/**
+ * Our own copy, never the directory the running server was launched from.
+ * `stateHome` defaults to the server's own home (mono-tenant / commons before
+ * migration), but is the DROPPED agent's home (`/home/<user>`) once agents run
+ * as a non-root OS user: the server's `/root` is mode 0700 and un-traversable by
+ * that user, so a clone there strands the Tweak agent — same reason as
+ * `worktreeDir` in `worktree.ts`. The caller makes the clone writable by the
+ * drop user; this only fixes WHERE it lands.
+ */
+export function selfRepoDir(stateHome = os.homedir()) {
+    return path.join(stateHome, ".shadok-ai", "self", "shadok-ai");
 }
 /** Pure: what to do with the checkout, given what is on disk. */
 export function selfRepoPlan(exists, isRepo) {
@@ -48,8 +56,8 @@ function git(args, cwd) {
  * worktrees a tweak session owns are separate checkouts and are never touched —
  * refreshing under a live agent is how you lose its work.
  */
-export function ensureSelfRepo() {
-    const dir = selfRepoDir();
+export function ensureSelfRepo(stateHome = os.homedir()) {
+    const dir = selfRepoDir(stateHome);
     const plan = selfRepoPlan(fs.existsSync(dir), fs.existsSync(path.join(dir, ".git")));
     try {
         if (plan === "reclone")

package/dist/selfrepo.js.map

@@ -1 +1 @@
-{"version":3,"file":"selfrepo.js","sourceRoot":"","sources":["../src/selfrepo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"selfrepo.js","sourceRoot":"","sources":["../src/selfrepo.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -65,6 +65,7 @@ import { getProfile, profileArgs, permissionModeArgs, isPermissionMode, isEffort
 import { BOOTSTRAP_ADMIN, loadAccounts, verifyPassword, sessionSecret, signSession, readSessionFull, sessionAlive, saveAccounts, userWriteVerdict, newInvite, inviteVerdict, hashPassword, promptAuthor, signSessionKey, readSessionKey, signTalkHandle, readTalkHandle, } from "./accounts.js";
 import { admins2fa, authenticationOptions, enrollCodeVerdict, isInternalClient, keepsTwoAdminsVerdict, loginNext, newEnrollCode, publicPasskey, putChallenge, readPending, registrationOptions, resetVerdict, signPending, takeChallenge, twoFactorEnableVerdict, verifyAuthentication, verifyRegistration, PENDING_TTL_MS, } from "./twofactor.js";
 import { ensureSelfRepo } from "./selfrepo.js";
+import { supersedeSession } from "./live-handover.js";
 import { createWorktree, pruneWorktree, ensureWorktreeCheckout, gitDiff, isGitRepo, listPastSessions, } from "./worktree.js";
 import { latestVersion, update } from "./updater.js";
 import { resolveChannel } from "./update-channel.js";
@@ -1554,7 +1555,9 @@ app.get("/diff", (req, res) => {
 // Past worktree sessions of a repo (for reopening unfinished work).
 app.get("/recover", (req, res) => {
     const repo = String(req.query.repo ?? "").trim() || process.cwd();
-    const list = isGitRepo(repo) ? listPastSessions(repo) : [];
+    const list = isGitRepo(repo)
+        ? listPastSessions(repo, agentStateHome(commonsOsUser({ migrated: groupsMigrated, mode: DEPLOYMENT_MODE })))
+        : [];
     // `repo` is a caller-supplied path: a caller who knows another group's HOME
     // could enumerate that group's past worktree sessions (branch/commit metadata +
     // first-prompt preview). Filter each past session to the caller's visible
@@ -1617,10 +1620,18 @@ app.put("/mute", (req, res) => {
 // Materialises shadok-ai's own source for the "Tweak Shadok-AI" CTA, and hands
 // back the directory to start the agent in. Sits here so it inherits the same
 // password gate as its neighbours.
-app.post("/tweak/prepare", (_req, res) => {
-    const r = ensureSelfRepo();
+app.post("/tweak/prepare", async (_req, res) => {
+    // The tweak agent runs as the commons drop user; its self-repo clone must live
+    // in THAT user's home (reachable under 0700 /root) and be owned by it — same
+    // reason as the worktree created off it. `commonsOsUser → null` in mono-tenant
+    // makes `agentStateHome(null)` the server home and the chown a no-op, so
+    // nothing changes there.
+    const commonsUser = commonsOsUser({ migrated: groupsMigrated, mode: DEPLOYMENT_MODE });
+    const r = ensureSelfRepo(agentStateHome(commonsUser));
     if (r.error)
         return res.status(500).json({ error: r.error });
+    if (r.cwd)
+        await chownAgentStateToDropUser(r.cwd, commonsUser);
     res.json({ cwd: r.cwd });
 });
 // Running version + latest seen on npm (null if not yet polled / check disabled).
@@ -2120,11 +2131,16 @@ app.post("/groups/members", (req, res) => {
 // DEPLOYMENT_MODE gate and the honest-failure rules (T3/T4) all live here. ──────
 /** Where a group's HOME is created (`SHADOK_HOME_BASE` override, else `/home`). */
 const GROUP_HOME_BASE = (process.env.SHADOK_HOME_BASE ?? "").trim() || DEFAULT_HOME_BASE;
-/** The HOME whose `.claude/projects` holds a given agent's transcript: the drop
- *  user's own home when the agent is privilege-dropped (multi-tenant isolation),
- *  else the server's own home (commons / mono-tenant). The single answer the
- *  content tail and `loadHistory` must use so an isolated agent's reply streams. */
-function agentTranscriptHome(user) {
+/** The HOME that holds ALL of an agent's on-disk state: its transcript
+ *  (`.claude/projects`, read by the content tail and `loadHistory`) AND its
+ *  worktrees + self-repo clone (`.shadok-ai/worktrees`, `.shadok-ai/self`). The
+ *  drop user's own home when the agent is privilege-dropped (multi-tenant
+ *  isolation), else the server's own home (commons / mono-tenant). The single
+ *  answer every one of those paths must use: the server's `/root` is mode 0700
+ *  and un-traversable by a dropped user, so state created there is silently
+ *  unreachable — a reply that never streams, or a Tweak agent wedged on Claude
+ *  Code's invalid-settings screen (its worktree lived under `/root`). */
+function agentStateHome(user) {
     return user ? homeForUser(user, GROUP_HOME_BASE) : os.homedir();
 }
 /** The COMMONS tier for secret resolution: Main plus every PUBLIC non-Main group.
@@ -2138,11 +2154,13 @@ function commonsGroupIds() {
             ids.push(g.id);
     return ids;
 }
-/** The transcript HOME for a CHANNEL that may not be live (e.g. GET /download of
- *  a past session): a live session's own `transcriptHome` when we have it, else
- *  re-derived from the channel's group the same way a spawn's drop user is —
- *  the group's `sk-*` user, or the commons user when migrated, else the server. */
-function channelTranscriptHome(chan) {
+/** The state HOME for a CHANNEL that may not be live (e.g. GET /download of a
+ *  past session, or pruning a worktree as the session ends): a live session's
+ *  own `transcriptHome` when we have it, else re-derived from the channel's
+ *  group the same way a spawn's drop user is — the group's `sk-*` user, or the
+ *  commons user when migrated, else the server. Governs both the transcript and
+ *  the worktree location, so prune finds exactly what the spawn created. */
+function channelStateHome(chan) {
     const live = sessions.get(chan.sessionId);
     if (live)
         return live.transcriptHome;
@@ -2150,7 +2168,7 @@ function channelTranscriptHome(chan) {
         return os.homedir();
     const g = chan.group ? loadGroups().find((x) => x.id === chan.group) : null;
     const user = (g ? osUserFor(g) : null) ?? commonsOsUser({ migrated: groupsMigrated, mode: DEPLOYMENT_MODE });
-    return agentTranscriptHome(user);
+    return agentStateHome(user);
 }
 /** Task 12: the one shared pot every group HOME links as `~/shared`. */
 const SHARED_POT_PATH = (process.env.SHADOK_SHARED_POT_PATH ?? "").trim() || DEFAULT_SHARED_POT_PATH;
@@ -2171,6 +2189,43 @@ function runPrivileged(cmd, argv) {
         p.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${code}`))));
     });
 }
+/**
+ * Make a freshly-created worktree (or self-repo clone) usable by the DROP USER.
+ * The server creates it as ROOT, so the checkout AND git's own worktree admin
+ * dir (`<repo>/.git/worktrees/<name>`, where the agent's index/HEAD/logs live)
+ * are root-owned — and a dropped agent could neither write them nor, before this
+ * fix, even reach them under the 0700 server HOME. Now the checkout lives in the
+ * drop user's OWN home (`agentStateHome` → `worktreeDir`), so only ownership is
+ * left: chown BOTH the checkout and (for a worktree) its external admin dir to
+ * the user. Best-effort and logged — a chown failure degrades to the old symptom
+ * rather than failing the spawn, and the log names it. No-op with no drop user
+ * (mono-tenant, or commons-as-root before migration): ownership is already right.
+ */
+async function chownAgentStateToDropUser(checkout, user) {
+    if (!user)
+        return;
+    const owner = `${user}:${user}`;
+    try {
+        await runPrivileged("chown", ["-R", owner, checkout]);
+        // git's admin dir sits under the REPO's gitdir, not the checkout; resolve it
+        // from inside the checkout so a worktree `.git` FILE is followed to it. Only
+        // chown it when OUTSIDE the checkout (a worktree); for a plain clone it is
+        // `<checkout>/.git`, already covered by the recursive chown above.
+        let adminDir = "";
+        try {
+            adminDir = execFileSync("git", ["-C", checkout, "rev-parse", "--absolute-git-dir"], { encoding: "utf8", timeout: 10_000 }).trim();
+        }
+        catch {
+            /* not a git checkout: the recursive chown already covered it */
+        }
+        if (adminDir && !adminDir.startsWith(path.resolve(checkout) + path.sep)) {
+            await runPrivileged("chown", ["-R", owner, adminDir]);
+        }
+    }
+    catch (e) {
+        console.warn(`state chown to ${user} failed for ${checkout} (agent may be unable to write it): ${e?.message ?? e}`);
+    }
+}
 /** The shadok skills to install: [package source dir, installed name]. Mirrored
  *  into the SERVER HOME by `seedXxxSkill` and, for multi-user isolation, into the
  *  machine-wide ENTERPRISE tier by `seedSystemSkills`. */
@@ -4125,7 +4180,7 @@ app.get("/download", (req, res) => {
     if (!allowed) {
         let raw;
         try {
-            raw = fs.readFileSync(transcriptFilePath(chan.cwd, session, channelTranscriptHome(chan)), "utf8");
+            raw = fs.readFileSync(transcriptFilePath(chan.cwd, session, channelStateHome(chan)), "utf8");
         }
         catch {
             return res.status(403).type("text").send("that file was not sent by this agent");
@@ -5162,6 +5217,12 @@ async function endChannel(sessionId) {
     const s = sessions.get(sessionId);
     const worktreeBranch = s?.worktree?.branch ?? ch?.branch;
     const repo = s?.worktree?.repo ?? ch?.repo;
+    // Resolve the worktree's home WHILE the session is still live (its own
+    // `transcriptHome` is the exact home the spawn created it in); fall back to the
+    // channel's group-derived home once it is gone. Prune must look in the same
+    // place createWorktree wrote, or a dropped agent's checkout under /home/<user>
+    // would never be cleaned.
+    const worktreeHome = s?.transcriptHome ?? (ch ? channelStateHome(ch) : os.homedir());
     if (s) {
         broadcast(s, { type: "stopped" });
         await s.pilot.stop().catch(() => { });
@@ -5171,7 +5232,7 @@ async function endChannel(sessionId) {
     // merged), keep it if there's uncommitted or unmerged work. Stops the empty-
     // worktree pile-up while never discarding real work.
     if (repo && worktreeBranch) {
-        const outcome = pruneWorktree(repo, worktreeBranch);
+        const outcome = pruneWorktree(repo, worktreeBranch, worktreeHome);
         if (outcome !== "none")
             console.log(`worktree ${worktreeBranch}: ${outcome} on session end`);
     }
@@ -5270,8 +5331,8 @@ group = null) {
     const pilot = makePilot(id, cwd, args, profile, model, effort, user, group);
     // A dropped group agent writes its transcript under ITS OWN home, not the
     // server's — so the content tail / history must read from there (invariant:
-    // all content comes from the .jsonl). `agentTranscriptHome` is the one answer.
-    const transcriptHome = agentTranscriptHome(user);
+    // all content comes from the .jsonl). `agentStateHome` is the one answer.
+    const transcriptHome = agentStateHome(user);
     // Resumed sessions start with what the transcript already consumed.
     const seededUsage = scanUsage(sessionFilePath(cwd, id, transcriptHome));
     const backend = sessionBackend(profile, group);
@@ -6032,8 +6093,11 @@ wss.on("connection", (ws, req) => {
     // so a server updated underneath it refreshes the page automatically.
     send(versionMessage());
     ws.on("close", () => {
+        // Detach from the CURRENT Live for this id, not the closure's possibly
+        // retired one: a handover ([5d8d]) moved this ws onto the new Live, so
+        // detaching the old object would leak the ws in the live one's client set.
         if (session)
-            detach(ws, session);
+            detach(ws, sessions.get(session.id) ?? session);
         session = null;
     });
     ws.on("message", async (raw) => {
@@ -6045,6 +6109,16 @@ wss.on("connection", (ws, req) => {
             return fail("unreadable message");
         }
         try {
+            // This connection can outlive the Live it attached to: a resume that
+            // supersedes an exited-but-watched session (see `supersedeSession`,
+            // [5d8d]) moved this ws onto the NEW Live, but this closure still points
+            // at the retired one. Re-point it so every handler below — and the
+            // takeover/retry logic — acts on the single real Live for this id.
+            if (session) {
+                const current = sessions.get(session.id);
+                if (current && current !== session)
+                    session = current;
+            }
             // Any user takeover cancels a pending auto-retry and ends the streak.
             // "prompt" is settled inside its own case instead: a prompt refused on
             // pace grounds sends nothing, so it must not count as a takeover — it
@@ -6176,9 +6250,11 @@ wss.on("connection", (ws, req) => {
                         }
                         return m ?? null;
                     };
+                    // The drop user a NEW spawn will run as — same inputs as the isolation
+                    // resolution further down. Hoisted out of the MT-token guard because the
+                    // worktree below must land in (and be owned by) this same user's home.
+                    let earlyUser = null;
                     if (!resumed) {
-                        // A new spawn has no stored group; same inputs as the isolation
-                        // resolution further down.
                         const earlyIso = resolveSpawnIsolation({
                             mode: DEPLOYMENT_MODE,
                             resumed,
@@ -6187,15 +6263,22 @@ wss.on("connection", (ws, req) => {
                             storedGroupId: null,
                             requestedGroupId: typeof msg.group === "string" && msg.group.trim() ? msg.group.trim() : null,
                         });
-                        const earlyUser = earlyIso.user ?? commonsOsUser({ migrated: groupsMigrated, mode: DEPLOYMENT_MODE });
+                        earlyUser = earlyIso.user ?? commonsOsUser({ migrated: groupsMigrated, mode: DEPLOYMENT_MODE });
                         const earlyMsg = mtRefusal(earlyUser);
                         if (earlyMsg)
                             return fail(earlyMsg);
                     }
                     if (msg.worktree && !resumed && isGitRepo(cwd)) {
                         try {
-                            worktree = createWorktree(cwd, id.slice(0, 8));
+                            // Create the checkout under the DROP USER's own home (not the
+                            // server's `/root`, which that user cannot traverse) and hand it to
+                            // them, so a dropped agent — notably every Tweak agent — can
+                            // actually work in it instead of landing on the invalid-settings
+                            // screen. `agentStateHome(null)` is the server home, so mono-tenant
+                            // is byte-for-byte unchanged.
+                            worktree = createWorktree(cwd, id.slice(0, 8), agentStateHome(earlyUser));
                             effectiveCwd = worktree.path;
+                            await chownAgentStateToDropUser(worktree.path, earlyUser);
                         }
                         catch (e) {
                             return fail("worktree creation failed: " + (e instanceof Error ? e.message : String(e)));
@@ -6388,6 +6471,21 @@ wss.on("connection", (ws, req) => {
                     if (mtMsg)
                         return fail(mtMsg);
                     session = await createSession(id, effectiveCwd, args, worktree, profile, model, effort, spawnActor({ account: me?.name, origin: msg.origin, peer: callerPeer, parent: parentAtStart, agent: callerAgent?.name }), dropUser, agentGroupId);
+                    // One Live per agent (shared-ledger [5d8d]). We only reach here when
+                    // there was no live session to attach to — but `existing` may be a
+                    // RETIRED Live whose pilot has exited while viewers are still
+                    // attached (a web tab, a Telegram bridge). `createSession` has just
+                    // replaced it in the registry; without a handover those viewers are
+                    // orphaned on the old object — still fed the agent's answers by its
+                    // lingering tail, but cut off from every broadcast on the new Live
+                    // (the other interfaces' prompt echoes, dialogs, working/turn-done).
+                    // Move them onto the new Live and quiet the old one — without killing
+                    // the agent, which the new Live may now be driving on the same pane.
+                    if (existing && existing !== session) {
+                        const moved = supersedeSession(existing, session);
+                        if (moved)
+                            console.log(`session ${id.slice(0, 8)}: superseded a retired Live, moved ${moved} viewer(s)`);
+                    }
                     session.clients.add(ws);
                     if (resumed) {
                         const turns = historyWithOffers(loadHistory(effectiveCwd, id, session.transcriptHome), id);