symbio 0.7.1 → 0.8.0

package/dist/server/prompts.js

@@ -4,13 +4,18 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { docsPaths } from "./docs.js";
 import { PROCESS_RULES } from "./guard.js";
+import { listRepositories, projectRepositoriesSync } from "./repos.js";
 // Seen live: a coordinator read eight 2–4 MB images, its conversation reached 25 MB and the
 // provider gave up receiving it ("Timed out reading request body"), whatever the model.
 const KEEP_CONVERSATION_SMALL = `- Keep your conversation small: whatever you read stays in it and is sent to
   the model again on every turn, until it becomes too large to send. Look at
   images with Symbio's \`view_image\` tool (a scaled-down copy; ask for a crop to
-  see details) — reading image files directly is blocked. For a big file, read
-  the part you need. Reviewing many images is work for a helper.`;
+  see details) and read documents (PDF, Word, Excel, PowerPoint) with
+  \`read_document\` — reading images and PDFs directly is blocked. For a big file,
+  read the part you need. Reviewing many images is work for a helper.
+- Files the human attaches to a message arrive as full paths below it; open
+  them with the tools above. They're kept in the project, so you can come back
+  to them later.`;
 // OpenCode's code mode posts "tool catalog changed" notices that list only its own tools and
 // say the catalog is complete; Symbio's tools still work (seen live: a coordinator kept using
 // them after such a notice, another gave up without trying).
@@ -147,6 +152,9 @@ ${KEEP_CONVERSATION_SMALL}
 }
 /** Where helpers work, for the coordinator's tool list. */
 function helperFolders(project) {
+    const repos = projectRepositoriesSync(project);
+    if (repos.length)
+        return multiRepoFolders(project, repos);
     if (!existsSync(path.join(project.directory, ".git"))) {
         return "  Helpers work directly in the project folder, alongside you.";
     }
@@ -159,7 +167,44 @@ function helperFolders(project) {
   - **shared**: the project folder itself. What it writes is there at once for
     you and the next helper; nothing to merge, and it doesn't commit. For steps
     that produce or check files others use next (pipelines, reviews of outputs).
-    Helpers in the project folder claim the files they write as shared assets.`;
+    Helpers in the project folder claim the files they write as shared assets.${innerRepositories(project)}`;
+}
+/**
+ * Repositories inside a project that is a repository itself. Often an outer one was created on
+ * top of them (older Symbio versions did): their files aren't in it, so helpers' copies lack them.
+ */
+function innerRepositories(project) {
+    if (existsSync(path.join(project.directory, ".gitmodules")))
+        return "";
+    const inner = listRepositories(project.directory);
+    if (!inner.length)
+        return "";
+    return `
+  Note: inside the project are other git repositories (${inner.map((r) => `\`${r}\``).join(", ")}),
+  with their own history. Their files aren't part of the project's repository, so
+  helpers' own copies don't have them, and commits in them don't belong to it.
+  Symbio can work in each of these repositories instead (each helper its own copy
+  of one): check with sub_repositories. If the outer repository was created by
+  Symbio and has no remote, switch (action use) and tell the human; otherwise ask
+  them first.`;
+}
+/** A folder that isn't a repository itself but holds several (e.g. client/, server/, each with its own remote). */
+function multiRepoFolders(project, repos) {
+    const def = project.helperWorkspace === "shared" ? "shared" : "own";
+    return `  This project is made of **${repos.length} git repositories**, each with its own
+  history and remote: ${repos.map((r) => `\`${r}\``).join(", ")}. The project folder itself
+  ${project.subRepositories
+        ? "is a repository created on top of them earlier; leave it alone (don't commit\n  there)."
+        : "is not a repository; never create one on top of them (\`git init\` there)."}
+  Where a helper works (\`workspace\`; this project's default is **${def}**):
+  - **own** with \`repo\`: its own copy of that one repository, on its own branch.
+    It only sees that repository's **committed** files; you merge its work into
+    that repository with merge_work. One helper per repository at a time is
+    simplest; for a change across repositories, give each part to its own helper.
+  - **shared**: the project folder with every repository, nothing to merge. Give
+    it a \`repo\` too when its work is in one of them: git_push / git_pull then
+    default to it.
+  git_push and git_pull from the project folder take \`repo\` (which repository).`;
 }
 function onboarding(project) {
     if (project.origin === "new") {
@@ -268,14 +313,18 @@ assets. Your tasks come from the coordinator.
 - Stay within your purpose and task. If something outside it needs doing, tell
   the coordinator instead of doing it.
 - ${isolated
-        ? `You work in your own isolated copy of the project, on branch \`${agent.branch}\`.
+        ? `You work in your own isolated copy of ${agent.repo ? `the "${agent.repo}" repository (one of the project's several repositories)` : "the project"}, on branch \`${agent.branch}\`.
   Commit your work there with clear messages; never merge or push — the
   coordinator merges your work into the project.`
         : `You work directly in the project folder, alongside the coordinator and other
   agents: what you write is there for them at once, and theirs for you. Before
   writing files others may also write, claim them as a shared asset (below).
   Don't commit, merge or push unless the coordinator asks; don't touch files or
-  processes that aren't yours.`}
+  processes that aren't yours.${agent.repo
+            ? `
+  The project folder holds several git repositories; yours is \`${agent.repo}\`. Commit
+  inside it (never \`git init\` the project folder); git_push / git_pull use it by default.`
+            : ""}`}
 - When you finish a task, or are blocked, report it once: with \`update_task\`
   for plan tasks (see below), otherwise with \`send_message\` to the coordinator
   (what you did, where, anything they should know). Then end your turn; new

package/dist/server/remote.js

@@ -129,9 +129,9 @@ export class RemoteOps {
             case "remote_upload":
                 return `upload ${a.localPath} to ${conn.name}:${a.remotePath}`;
             case "git_push":
-                return `git push ${a.remote ?? "origin"} ${a.branch ?? "(current branch)"} from ${agent.name}'s workspace using ${conn.name}`;
+                return `git push ${a.remote ?? "origin"} ${a.branch ?? "(current branch)"} from ${a.repo ? `the ${a.repo} repository` : `${agent.name}'s workspace`} using ${conn.name}`;
             case "git_pull":
-                return `git pull ${a.remote ?? "origin"} ${a.branch ?? "(current branch)"} into ${agent.name}'s workspace using ${conn.name}`;
+                return `git pull ${a.remote ?? "origin"} ${a.branch ?? "(current branch)"} into ${a.repo ? `the ${a.repo} repository` : `${agent.name}'s workspace`} using ${conn.name}`;
             case "github_api":
                 return `GitHub API ${a.method.toUpperCase()} ${a.path} using ${conn.name}`;
             case "azure_devops_api":
@@ -179,19 +179,20 @@ export class RemoteOps {
                 const gitConn = conn;
                 const token = await this.connections.githubToken(gitConn);
                 const remote = a.remote ?? "origin";
-                const url = remote.startsWith("https://") ? remote : await gitOut(agent.directory, ["remote", "get-url", remote]);
+                const cwd = a.repo ? path.join(agent.directory, ...a.repo.split("/")) : agent.directory;
+                const url = remote.startsWith("https://") ? remote : await gitOut(cwd, ["remote", "get-url", remote]);
                 const auth = gitAuth(gitConn, url, token);
-                const branch = a.branch ?? (await gitOut(agent.directory, ["rev-parse", "--abbrev-ref", "HEAD"]));
+                const branch = a.branch ?? (await gitOut(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]));
                 // The agent controls this repository, so its config and hooks are untrusted: a hook
                 // would see the token, a proxy or URL rewrite would send it elsewhere.
-                await refuseRiskyGitConfig(agent.directory);
+                await refuseRiskyGitConfig(cwd);
                 const noHooks = path.join(os.tmpdir(), `symbio-no-hooks-${randomUUID()}`); // never exists
                 const safe = ["-c", `core.hooksPath=${noHooks}`, "-c", "http.proxy=", "-c", "http.sslVerify=true", "-c", "credential.helper="];
                 // The token goes in an HTTP header via environment-only git config: never in
                 // the command line, the repo config or the agent's view.
                 const { headerKey, header } = auth;
                 const git = (args, withToken) => run("git", [...safe, ...args], {
-                    cwd: agent.directory,
+                    cwd,
                     windowsHide: true,
                     timeout: 5 * 60_000,
                     env: {

package/dist/server/repos.js

@@ -0,0 +1,136 @@
+// Projects made of several git repositories: a folder (not itself a repository) whose subfolders
+// are, e.g. game/client, game/server, game/admin, each with its own remote. Symbio works inside
+// each of them instead of creating a repository of its own on top.
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { git } from "./git.js";
+// Never repositories of the project's own (tooling, dependencies, Symbio's data).
+const SKIP = new Set([".git", ".symbio", "node_modules", ".venv", "venv", "__pycache__", "bin", "obj", "dist", "build", "target", ".next", ".cache", ".idea", ".vs", ".vscode"]);
+/** Git repositories in subfolders (up to `depth` levels down), as relative paths with "/". A repository's own subfolders aren't searched. */
+export function listRepositories(dir, depth = 2) {
+    const found = [];
+    const walk = (abs, rel, left) => {
+        let entries = [];
+        try {
+            entries = readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || SKIP.has(e.name) || e.name.startsWith("."))
+                continue;
+            const childAbs = path.join(abs, e.name);
+            const childRel = rel ? `${rel}/${e.name}` : e.name;
+            if (existsSync(path.join(childAbs, ".git")))
+                found.push(childRel);
+            else if (left > 1)
+                walk(childAbs, childRel, left - 1);
+        }
+    };
+    walk(dir, "", depth);
+    return found.sort((a, b) => a.localeCompare(b));
+}
+export const findRepositories = async (dir, depth = 2) => listRepositories(dir, depth);
+export const isGitDir = (dir) => existsSync(path.join(dir, ".git"));
+/**
+ * The repositories a project works in, when there are several: the subfolders' repositories when
+ * the folder isn't one itself, or when the project was switched to them (subRepositories). Empty
+ * for a single repository, or no git.
+ */
+export function projectRepositoriesSync(project) {
+    if (isGitDir(project.directory) && !project.subRepositories)
+        return [];
+    return listRepositories(project.directory);
+}
+export const projectRepositories = async (project) => projectRepositoriesSync(project);
+/** The repository an agent's git work happens in: its chosen sub-repository, or the project folder. */
+export function repoRoot(project, agent) {
+    return agent.repo ? path.join(project.directory, ...agent.repo.split("/")) : project.directory;
+}
+/** A repository the agent named (relative to the project), checked to be one of the project's. */
+export async function resolveRepository(project, repo) {
+    const rel = repo.trim().replace(/\\/g, "/").replace(/^\.\/|\/+$/g, "");
+    const repos = await projectRepositories(project);
+    if (!repos.includes(rel)) {
+        throw new Error(repos.length
+            ? `"${repo}" isn't one of this project's repositories: ${repos.join(", ")}.`
+            : "This project isn't made of several repositories, so there's no repository to choose.");
+    }
+    return rel;
+}
+/**
+ * A repository at the top of the project that contains other repositories as bare pointers
+ * (gitlinks with no .gitmodules): typically one Symbio created over a folder of repositories,
+ * before it knew to look for them. Returns those inner repositories, or [] when it isn't the case.
+ */
+export async function swallowedRepositories(dir) {
+    if (!isGitDir(dir) || existsSync(path.join(dir, ".gitmodules")))
+        return { inner: [], createdBySymbio: false };
+    const inner = await findRepositories(dir);
+    if (!inner.length)
+        return { inner: [], createdBySymbio: false };
+    const first = await git(dir, "log", "--reverse", "--format=%s", "--max-count=1").catch(() => "");
+    const root = (await git(dir, "rev-list", "--max-parents=0", "HEAD").catch(() => "")).split("\n")[0];
+    const firstSubject = root ? await git(dir, "log", "-1", "--format=%s", root).catch(() => first) : first;
+    return { inner, createdBySymbio: firstSubject.trim() === "Initial snapshot (created by Symbio)" };
+}
+const samePath = (a, b) => {
+    const norm = (p) => (process.platform === "win32" ? path.resolve(p).toLowerCase() : path.resolve(p));
+    return norm(a) === norm(b);
+};
+/**
+ * Which repository git_push / git_pull act on, relative to the project folder (null = the
+ * agent's own folder). Helpers in their own copy push that copy. Agents in the project folder of
+ * a project made of several repositories name one (shared helpers default to the one they were given).
+ */
+export async function gitRepoFor(project, agent, repo) {
+    if (!samePath(agent.directory, project.directory)) {
+        if (repo)
+            throw new Error("You work in your own copy of a repository: push and pull apply to it, without repo.");
+        return null;
+    }
+    if (repo)
+        return resolveRepository(project, repo);
+    const repos = await projectRepositories(project);
+    if (!repos.length)
+        return null;
+    if (agent.repo)
+        return agent.repo;
+    throw new Error(`This project is made of several repositories (${repos.join(", ")}); say which one with repo.`);
+}
+/**
+ * What the coordinator needs to decide whether to switch a project to its inner repositories:
+ * who created the outer one, whether it has a remote, its history, and helpers working in copies of it.
+ */
+export async function describeOuterRepository(project) {
+    const dir = project.directory;
+    const { inner, createdBySymbio } = await swallowedRepositories(dir);
+    if (!inner.length) {
+        return project.subRepositories
+            ? "Symbio works in this project's inner repositories, but none were found now."
+            : "The project folder doesn't contain other git repositories (or tracks them as submodules): nothing to switch.";
+    }
+    const remotes = (await git(dir, "remote").catch(() => "")).split("\n").map((r) => r.trim()).filter(Boolean);
+    const count = Number(await git(dir, "rev-list", "--count", "HEAD").catch(() => "0")) || 0;
+    const recent = (await git(dir, "log", "-5", "--format=%s").catch(() => "")).split("\n").filter(Boolean);
+    const copies = project.agents.filter((a) => a.role === "worker" && a.status !== "stopped" && a.branch && !a.repo);
+    return [
+        `The project folder is a git repository that contains ${inner.length} other repositories (${inner.join(", ")}) without tracking ` +
+            "their files (bare pointers, not submodules).",
+        createdBySymbio
+            ? "The outer repository was created by Symbio when the project was added (its first commit is Symbio's snapshot)."
+            : "The outer repository was not created by Symbio: someone made it on purpose.",
+        remotes.length ? `Its remotes: ${remotes.join(", ")}.` : "It has no remote.",
+        `Its history: ${count} commit(s)${recent.length ? `; latest: ${recent.map((s) => `"${s}"`).join(", ")}` : ""}.`,
+        copies.length
+            ? `Helpers with their own copy of the outer repository: ${copies.map((a) => `${a.name} (${a.status})`).join(", ")}.`
+            : "No active helper has its own copy of the outer repository.",
+        project.subRepositories
+            ? "Now: Symbio works in the inner repositories and leaves the outer one alone."
+            : "Now: Symbio works in the outer repository, so helpers' own copies have the inner repositories as empty folders.",
+        "Switching (action use) changes nothing on disk: the outer .git and every file stay where they are. From then on a helper's own " +
+            "copy comes from one inner repository (spawn_agent repo), merges and pushes go to it, and the outer repository is left alone. " +
+            "Action stop switches back.",
+    ].join("\n");
+}

package/dist/server/team.js

@@ -5,7 +5,7 @@ import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { AssetRegister } from "./assets.js";
-import { AGENT_PERMISSIONS, imageReadRefusal, wildcardMatch } from "./guard.js";
+import { AGENT_PERMISSIONS, readRefusal, wildcardMatch } from "./guard.js";
 import { bus } from "./bus.js";
 import { privateDocsInstruction } from "./docs.js";
 import { parseModel } from "./opencode/client.js";
@@ -17,6 +17,7 @@ import { accountChildUsage, accountUsage, emptyUsage, sessionUsage } from "./cos
 import { AGENT_UPDATES, unseenUpdates, updatesNote } from "./updates.js";
 import { cleanBuildOutputs, dailyBackup, gb, helperFolders, lastBackup, unpushedWork } from "./housekeeping.js";
 import { coordinatorTools, workerTools } from "./tools.js";
+import { listRepositories, projectRepositories, repoRoot, resolveRepository } from "./repos.js";
 import { changedFiles, createWorkspace, inProjectFolder, isGitRepo, leaveWorkspace, mergeWorkspace, reattachWorkspace, removeWorkspace, restoreWorkspace, syncWorkspace } from "./workspaces.js";
 const STUCK_AFTER_MS = Number(process.env.SYMBIO_STUCK_MINUTES ?? 10) * 60_000;
 const WATCHDOG_INTERVAL_MS = 30_000;
@@ -151,9 +152,9 @@ export class Team {
         const buildBytes = folders.reduce((s, f) => s + f.buildBytes, 0);
         const parts = [];
         if (branches.length) {
-            parts.push(`Work that exists only on this machine (not on the remote "${remote}"):\n` +
+            parts.push(`Work that exists only on this machine (not on ${remote === "each repository's remote" ? "each repository's remote" : `the remote "${remote}"`}):\n` +
                 branches.map((b) => `- ${b.branch}: ${b.commits} commit(s), latest "${b.latest}"`).join("\n") +
-                `\nIf it's ready to share, push it (git push ${remote} <branch>); if a branch shouldn't go to the remote, tell the human.`);
+                `\nIf it's ready to share, push it (git_push; in a project of several repositories, with repo); if a branch shouldn't go to the remote, tell the human.`);
         }
         if (buildBytes > BUILD_ALERT_BYTES) {
             parts.push(`Helpers' folders hold ${gb(buildBytes)} of build outputs:\n` +
@@ -298,6 +299,40 @@ export class Team {
                 "project folder stay there.", false);
     }
     /** The human turned the rules register on or off; every brief mentions it, and core is told. */
+    /**
+     * Works in the inner repositories of a repository created over them (on), or back in the outer
+     * one (off). Refused while active helpers have copies of the repository being left: their work
+     * would have nowhere to be merged.
+     */
+    async useSubRepositories(project, on, by) {
+        if (!!project.subRepositories === on) {
+            return on ? "Symbio already works in the inner repositories." : "Symbio already works in the outer repository.";
+        }
+        if (on && !listRepositories(project.directory).length)
+            throw new Error("The project folder doesn't contain other git repositories.");
+        const leaving = project.agents.filter((a) => a.role === "worker" && a.status !== "stopped" && a.branch && (on ? !a.repo : !!a.repo));
+        if (leaving.length) {
+            throw new Error(`${leaving.map((a) => a.name).join(", ")} ${leaving.length === 1 ? "has its" : "have their"} own copy of ${on ? "the outer repository" : "an inner repository"}. ` +
+                `Merge their work, then move them to the project folder (${by === "the human" ? "from their chat" : "move_to_project_folder"}) or stop them, and switch again.`);
+        }
+        project.subRepositories = on;
+        await this.store.update(project);
+        bus.publish({ type: "project.updated", projectId: project.id });
+        for (const agent of project.agents.filter(active))
+            await this.refreshInstructions(project, agent).catch(() => { });
+        const repos = listRepositories(project.directory);
+        await this.log(project, {
+            from: "symbio",
+            to: "human",
+            kind: "system",
+            text: on
+                ? `Symbio now works in this project's repositories (${repos.join(", ")}) instead of the repository on top of them (switched by ${by}). Nothing on disk changed; Settings → Team switches back.`
+                : `Symbio works in the project folder's own repository again (switched by ${by}).`,
+        });
+        return on
+            ? `Done: helpers' own copies now come from one of ${repos.join(", ")} (spawn_agent repo), merges and pushes go there. Your instructions were updated.`
+            : "Done: Symbio works in the outer repository again. Your instructions were updated.";
+    }
     async setRulesRegister(project, on) {
         if (!!project.rulesRegister === on)
             return;
@@ -534,7 +569,15 @@ export class Team {
         if (!project.allowedModels.includes(model)) {
             throw new Error(`Model "${model}" is not allowed for this project. Allowed: ${project.allowedModels.join(", ")}`);
         }
-        const workspace = await createWorkspace(project, name, opts.workspace ?? project.helperWorkspace ?? "own");
+        // A folder of several repositories: an own copy comes from one of them, so it must be named.
+        const mode = opts.workspace ?? project.helperWorkspace ?? "own";
+        const repo = opts.repo?.trim() ? await resolveRepository(project, opts.repo) : undefined;
+        const repos = await projectRepositories(project);
+        if (repos.length && mode === "own" && !repo) {
+            throw new Error(`This project is made of several repositories (${repos.join(", ")}). Say which one the helper works in with repo ` +
+                "(it gets its own copy of that repository), or use workspace \"shared\" to have it work in the project folder.");
+        }
+        const workspace = await createWorkspace(project, name, mode, repo);
         const client = this.client();
         await this.registerTools(project, workspace.directory);
         const session = await client.createSession({
@@ -550,6 +593,7 @@ export class Team {
             purpose: opts.purpose,
             sessionId: session.id,
             directory: workspace.directory,
+            ...(repo ? { repo } : {}),
             branch: workspace.branch,
             base: workspace.base,
             workSince: Date.now(),
@@ -567,8 +611,8 @@ export class Team {
         else
             await this.deliver(project, coordinator, agent, "request", opts.task, { protocol: true });
         const where = workspace.branch
-            ? `It works in its own copy of the project on branch ${workspace.branch} (${workspace.directory}); merge its work with merge_work.`
-            : (await isGitRepo(project.directory))
+            ? `It works in its own copy of ${repo ? `the "${repo}" repository` : "the project"} on branch ${workspace.branch} (${workspace.directory}); merge its work with merge_work.`
+            : (await isGitRepo(project.directory)) || repos.length
                 ? "It works in the project folder itself, alongside you: what it writes is there at once, and there is nothing to merge. " +
                     "Shared-asset grants keep it from colliding with others; it doesn't commit unless you ask."
                 : "It works directly in the project folder (no git), so rely on shared-asset grants to avoid conflicts.";
@@ -783,7 +827,9 @@ export class Team {
     async mergeWork(project, agent, force) {
         const { committed, uncommitted } = await changedFiles(agent);
         const reg = await this.assets(project);
-        const violations = reg.violations([...committed, ...uncommitted], agent.id, agent.workSince ?? agent.createdAt);
+        // Asset patterns are relative to the project folder; a sub-repository's paths are relative to it.
+        const inProject = (f) => (agent.repo ? `${agent.repo}/${f}` : f);
+        const violations = reg.violations([...committed, ...uncommitted].map(inProject), agent.id, agent.workSince ?? agent.createdAt);
         if (violations.length && !force) {
             const list = violations.map((v) => `- "${v.asset.name}": ${v.files.join(", ")}`).join("\n");
             return `Not merged: ${agent.name} changed shared assets it was not granted:\n${list}\nReview the changes, then grant the asset and merge again, ask ${agent.name} to revert them, or merge with force=true.`;
@@ -983,7 +1029,9 @@ export class Team {
         }
         if (project.agents.some((a) => a.branch)) {
             await fs.rm(path.join(globalDir, "worktrees", project.id), { recursive: true, force: true }).catch(() => { });
-            await git(project.directory, "worktree", "prune").catch(() => { });
+            const roots = new Set(project.agents.filter((a) => a.branch).map((a) => repoRoot(project, a)));
+            for (const root of roots)
+                await git(root, "worktree", "prune").catch(() => { });
         }
         this.registers.delete(project.id);
         this.plans.delete(project.id);
@@ -1002,7 +1050,7 @@ export class Team {
         const action = String(req.action ?? "");
         const resources = Array.isArray(req.resources) ? req.resources.map(String) : [];
         // Image files: refused at once, with what to use instead (never a question for the human).
-        const refusal = imageReadRefusal(action, resources);
+        const refusal = readRefusal(action, resources);
         if (refusal) {
             await this.client()
                 .request("POST", `/api/session/${agent.sessionId}/permission/${req.id}/reply`, { decision: "reject", message: refusal })
@@ -1339,6 +1387,12 @@ export class Team {
         await this.log(project, { from: "symbio", to: coordinator.id, kind: "system", text: note });
         project.updatesSeen = [...(project.updatesSeen ?? []), ...updates.map((u) => u.id)];
         await this.store.update(project);
+        // Some changes ask for action in the projects they apply to: those wake core up with a task.
+        for (const u of updates) {
+            const task = await u.task?.(project).catch(() => null);
+            if (task)
+                await this.system(project, coordinator, task);
+        }
     }
     /** Private docs aren't visible to OpenCode on its own; inject them, but only when they changed. */
     async syncPrivateDocs(project, agent) {
@@ -1554,11 +1608,19 @@ export class Team {
     setStatus(project, agent, status) {
         if (agent.status === status)
             return;
+        // A message arriving while the agent waits on the human (a question, a permission request) is
+        // queued until it's answered. Turning "busy" here hid the question from the chat and let the
+        // watchdog interrupt it as a hang ten minutes later.
+        if (status === "busy" && agent.status === "waiting" && this.waitsOnHuman(project, agent))
+            return;
         agent.status = status;
         agent.lastActivity = Date.now();
         bus.publish({ type: "agent.status", projectId: project.id, agentId: agent.id, status });
         void this.store.update(project);
     }
+    waitsOnHuman(project, agent) {
+        return this.pendingQuestion.has(agent.id) || this.permissionRequests(project).some((p) => p.agentId === agent.id);
+    }
     /** An agent that has been "busy" without any event for too long is hung: interrupt and nudge it. */
     async checkStuck() {
         if (this.runtime.state !== "running")
@@ -1568,6 +1630,14 @@ export class Team {
             for (const agent of project.agents) {
                 if (agent.status !== "busy" || now - agent.lastActivity < STUCK_AFTER_MS)
                     continue;
+                // Silent because it's waiting for the human's answer (an event may have been missed): not a hang.
+                const forms = await this.forms(agent).catch(() => []);
+                if (forms.length) {
+                    if (forms[0]?.id)
+                        this.pendingQuestion.set(agent.id, String(forms[0].id));
+                    this.setStatus(project, agent, "waiting");
+                    continue;
+                }
                 const minutes = Math.round((now - agent.lastActivity) / 60_000);
                 console.warn(`[watchdog] ${project.name}/${agent.name} silent for ${minutes} min, interrupting`);
                 this.setStatus(project, agent, "stuck");

package/dist/server/tools.js

@@ -4,6 +4,8 @@
 import { describeTask, TASK_STATUSES } from "./plan.js";
 import { CONFIRMATIONS, listRules, saveArea, saveRule, saveSource, STATUSES } from "./rules.js";
 import { DEFAULT_IMAGE_SIZE, viewImage } from "./images.js";
+import { readDocument } from "./documents.js";
+import { describeOuterRepository, gitRepoFor } from "./repos.js";
 const str = (description) => ({ type: "string", description });
 function obj(properties, required = []) {
     return { type: "object", properties, required, additionalProperties: false };
@@ -45,7 +47,7 @@ const listTeam = {
     inputSchema: obj({}),
     run(_args, { project }) {
         return project.agents
-            .map((a) => `- ${a.name} (${a.role}${a.status === "stopped" ? ", stopped" : `, ${a.status}`}) — ${a.purpose ?? "coordinates the project"} · model ${a.model}`)
+            .map((a) => `- ${a.name} (${a.role}${a.status === "stopped" ? ", stopped" : `, ${a.status}`}) — ${a.purpose ?? "coordinates the project"}${a.repo ? ` · repository ${a.repo}` : ""} · model ${a.model}`)
             .join("\n");
     },
 };
@@ -102,10 +104,12 @@ const spawnAgent = {
         task: str("Its first task as text (when there is no plan task), or extra instructions for task_id"),
         model: str("Optional provider/model from the allowed list; defaults to your own model"),
         workspace: { type: "string", enum: ["own", "shared"], description: "Where it works (git projects); defaults to the project's setting" },
+        repo: str("In a project made of several repositories: the one it works in (e.g. 'server'); its own copy comes from it"),
     }, ["name", "purpose"]),
     async run(args, { team, project, agent }) {
         return team.spawnWorker(project, agent, {
             workspace: args.workspace === "own" || args.workspace === "shared" ? args.workspace : undefined,
+            repo: args.repo ? String(args.repo) : undefined,
             name: String(args.name),
             purpose: String(args.purpose),
             task: args.task ? String(args.task) : undefined,
@@ -333,19 +337,32 @@ const gitFields = {
     connection: str("GitHub or Azure DevOps connection name"),
     remote: str("Remote name or HTTPS URL (github.com, dev.azure.com) (default: origin)"),
     branch: str("Branch (default: your current branch)"),
+    repo: str("In a project made of several repositories, working in the project folder: which one (e.g. 'server')"),
     reason: reasonField,
 };
 const gitPush = {
     name: "git_push",
     description: "Push committed work from your working folder to GitHub or Azure DevOps (the token is applied by Symbio; plain `git push` may have no credentials).",
     inputSchema: obj(gitFields, ["connection", "reason"]),
-    run: ({ connection, remote, branch, reason }, { team, project, agent }) => team.remote.request(project, agent, { kind: "git_push", connectionId: String(connection), remote: remote ? String(remote) : null, branch: branch ? String(branch) : null }, String(reason)),
+    run: async ({ connection, remote, branch, repo, reason }, { team, project, agent }) => team.remote.request(project, agent, {
+        kind: "git_push",
+        connectionId: String(connection),
+        remote: remote ? String(remote) : null,
+        branch: branch ? String(branch) : null,
+        repo: await gitRepoFor(project, agent, repo ? String(repo) : undefined),
+    }, String(reason)),
 };
 const gitPull = {
     name: "git_pull",
     description: "Pull from GitHub or Azure DevOps into your working folder (merge, no rebase).",
     inputSchema: obj(gitFields, ["connection", "reason"]),
-    run: ({ connection, remote, branch, reason }, { team, project, agent }) => team.remote.request(project, agent, { kind: "git_pull", connectionId: String(connection), remote: remote ? String(remote) : null, branch: branch ? String(branch) : null }, String(reason)),
+    run: async ({ connection, remote, branch, repo, reason }, { team, project, agent }) => team.remote.request(project, agent, {
+        kind: "git_pull",
+        connectionId: String(connection),
+        remote: remote ? String(remote) : null,
+        branch: branch ? String(branch) : null,
+        repo: await gitRepoFor(project, agent, repo ? String(repo) : undefined),
+    }, String(reason)),
 };
 const githubApi = {
     name: "github_api",
@@ -383,6 +400,18 @@ function registerOn(project) {
         throw new Error("This project doesn't keep a rules register (the human can turn it on in the project's Settings).");
 }
 // ---- images
+const readDocumentTool = {
+    name: "read_document",
+    description: "Read the text of a document: PDF (by pages), Word (.docx, .odt), Excel (.xlsx, every sheet as tab-separated rows), " +
+        "PowerPoint (.pptx, by slide) or a long text file. Returns a part at a time and says how to get the next one. " +
+        "Reading PDFs with the read tool is blocked (it would put the whole file in your conversation), and Office files are binary to it.",
+    inputSchema: obj({
+        path: str("The document (absolute, or relative to your folder)"),
+        pages: str('PDF pages to read, e.g. "1-10" or "7" (default: from the first page, as many as fit)'),
+        from: { type: "integer", description: "For other documents: the character to start from (given in the previous answer)" },
+    }, ["path"]),
+    run: (args, { agent }) => readDocument(agent.directory, args),
+};
 const viewImageTool = {
     name: "view_image",
     description: "Look at an image (png, jpg, gif, webp, bmp): returns a scaled-down copy, so it doesn't bloat your conversation. " +
@@ -468,6 +497,7 @@ const saveRuleSourceTool = {
 };
 const COMMON = [
     viewImageTool,
+    readDocumentTool,
     listRulesTool,
     saveRuleTool,
     saveRuleAreaTool,
@@ -491,7 +521,19 @@ const COMMON = [
     listProcesses,
     stopProcess,
 ];
+const subRepositories = {
+    name: "sub_repositories",
+    description: "For a project folder that is a git repository containing other repositories (often created on top of them by an older Symbio): " +
+        "check the situation, switch to working in the inner repositories (use), or back to the outer one (stop). Switching changes nothing on disk.",
+    inputSchema: obj({ action: { type: "string", enum: ["check", "use", "stop"], description: "check (default), use or stop" } }),
+    async run({ action }, { team, project }) {
+        if (action === "use" || action === "stop")
+            return team.useSubRepositories(project, action === "use", "the coordinator");
+        return describeOuterRepository(project);
+    },
+};
 const COORDINATOR_ONLY = [
+    subRepositories,
     submitPlan,
     addTask,
     assignTask,

package/dist/server/updates.js

@@ -3,7 +3,9 @@
 // (it isn't woken up for it), and the human sees the same list in Messages.
 //
 // Add an entry whenever a change affects how agents work: tools, rules, messages they
-// receive, what Symbio does on their behalf. Ids never change; keep the newest last.
+// receive, what Symbio does on their behalf. Ids never change; keep the newest last. An entry
+// whose change asks for action in some projects can add a task: those coordinators are woken with it.
+import { swallowedRepositories } from "./repos.js";
 export const AGENT_UPDATES = [
     {
         id: "2026-10-30-free-assets",
@@ -91,6 +93,37 @@ export const AGENT_UPDATES = [
             "HTTPS), and the new azure_devops_api tool calls its REST API, e.g. to open a pull request after pushing the branch. Reading " +
             "(GET) never needs approval. If a push or a pull request failed for lack of credentials, ask the human to add the connection.",
     },
+    {
+        id: "2026-11-09-attachments",
+        text: "Attachments and documents: the human can now attach files to a message (upload, drag and drop, paste). They arrive as full " +
+            "paths below the message and are kept in the project (.symbio/attachments; the human sees them in the Files tab), so you can " +
+            "come back to them. Look at images with view_image; read documents (PDF, Word, Excel, PowerPoint) with the new read_document " +
+            "tool, which returns their text a part at a time. Reading PDFs with the read tool is now refused like images: it would put the " +
+            "whole file in your conversation.",
+    },
+    {
+        id: "2026-11-09-multi-repo",
+        text: "Folders of several git repositories (e.g. client/ and server/, each with its own remote, in a folder that isn't a repository " +
+            "itself) are now handled as such: spawn_agent takes repo (the helper gets its own copy of that repository, and merge_work merges " +
+            "into it), and git_push / git_pull from the project folder take repo. Never git init the project folder over them.",
+        async task(project) {
+            if (project.subRepositories !== undefined)
+                return null;
+            const { inner, createdBySymbio } = await swallowedRepositories(project.directory);
+            if (!inner.length)
+                return null;
+            return (`Symbio update, for this project: the project folder is a git repository that contains other repositories (${inner.join(", ")}) ` +
+                `without their files${createdBySymbio ? " (Symbio created it on top of them when the project was added)" : ""}. So far helpers' own ` +
+                "copies had those repositories as empty folders, their commits went to the outer repository, and pushes had no remote of their own. " +
+                "Symbio can now work in each inner repository instead.\n\n" +
+                "Look at it with sub_repositories (action check). If the outer repository was created by Symbio and has no remote, switch on " +
+                "your own (action use): nothing on disk changes and it can be switched back. Before switching, bring any unmerged work of helpers " +
+                "with their own copy of the outer repository into the project (merge_work), then move them to the project folder or stop them. " +
+                "Don't interrupt work in progress: if helpers are busy, do it once they've finished. Then tell the human in a sentence or two what " +
+                "changed for them. If instead the outer repository has a remote or wasn't created by Symbio, someone may rely on it: explain the " +
+                "situation to the human briefly and ask whether to switch.");
+        },
+    },
 ];
 /** Entries a project hasn't been told about yet. */
 export function unseenUpdates(seen) {