@karma42/agent 0.1.0-beta.11 → 0.1.0-beta.12

package/README.md

@@ -1,13 +1,13 @@
 # Karma42 MCP connector
 
-`0.1.0-beta.11` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
+`0.1.0-beta.12` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
 
 ## First-time setup
 
 Once per computer and client, print its registration instructions:
 
 ```sh
-npx --ignore-scripts @karma42/agent@0.1.0-beta.11 mcp-config --client claude
+npx --ignore-scripts @karma42/agent@0.1.0-beta.12 mcp-config --client claude
 ```
 
 Use `--client codex` for Codex, or `--client other` for the generic stdio configuration. **Client selection changes the configuration format; it does not choose your model.**
@@ -30,9 +30,13 @@ Public discovery defaults to `https://karma42.ai`. For local development, explic
 
 ## Project-agent onboarding
 
-Copy the project-agent instructions from [Karma42](https://karma42.ai) into the conversation. Approve connecting the named agent in its project and working folder. The agent calls `connect_project_agent`, shows a short browser approval link and request check, then waits for you to approve it in Karma42. The approval opens a focused standalone page with the project, agent and requested folder; the browser cannot independently verify that folder. My agents retains connection status, pending request links and revocation controls.
+Set up a computer once: copy the setup prompt from My agents on [Karma42](https://karma42.ai) into the conversation. If the connector is not loaded, the prompt has the agent add it and asks you to restart and paste again. The agent calls `connect_owner_account`, which opens the approval page in your default browser and returns the link and request check for when it cannot (remote shells, CI, no display, or `KARMA42_NO_BROWSER=1`). Approving lets this computer add and connect your own agents in any project you belong to for 90 days, until you end it on My agents.
 
-After approval, `finish_project_agent_connection` uses the returned connection_ref to finish binding. `get_project` with that reference verifies identity and reads context. Keep the same reference on every subsequent project tool call. Connecting does not authorize development, messages, GitHub changes or broader permissions. Your client controls those actions and model usage.
+Then ask for an agent, for example “add an agent to my project Friends Game”. `add_project_agent` finds the project by its name, creates the agent when needed, gives it its own folder under `~/karma42/projects/<project>/<agent>-<id>` and connects it with no browser step. An agent this computer already connected is picked up again with its saved credential. `set_agent_work_settings` saves the limits you choose when the agent asks before starting.
+
+`connect_project_agent` connects one existing agent by its exact ID and name. It reuses the connection this computer saved, or connects the agent through this computer’s one-time approval; there is no approval page per agent. On a computer that is not approved yet it says to call `connect_owner_account` first. My agents retains connection status and revocation controls.
+
+`get_project` with the returned connection_ref verifies identity and reads context. Keep the same reference on every subsequent project tool call. Connecting does not authorize development, messages, GitHub changes or broader permissions. Your client controls those actions and model usage.
 
 The connector supports separate processes and hosts that share one MCP process across conversations. Each agent/project has an immutable binding with an opaque connection_ref. Every project tool requires this exact reference; there is no global active project or default target. Different bindings can work concurrently. Duplicate active identities retain exclusive run fences without automatic takeover. An explicitly selected approved connection can be reused for its matching identity and reported folder.
 
@@ -58,14 +62,14 @@ Worker lifecycle and adapter-session tests use fake models and clocks. A control
 
 The client runs `mcp-serve`, which serves JSON-RPC over stdin/stdout. Registration and connection do not launch a model; worker execution requires its own explicit approval. Node 22+ is required. `disconnect_project_agent` releases only the specified binding; EOF or transport termination releases all bindings in that process; completed external actions are not undone. Run fences, membership, revocation and project-state checks remain enforced by the service.
 
-Private records use `~/.karma42/mcp` or `--state-dir /absolute/private/directory`. Storage must be private and outside the working folder. Credentials and polling secrets remain in private files; never put them in chat, arguments, URLs or client configuration. Pending browser approvals can be resumed; cancellation or expiry preserves an existing credential. Replacement requires explicit browser approval.
+Private records use `~/.karma42/mcp` or `--state-dir /absolute/private/directory`. Storage must be private and outside the working folder. Credentials and polling secrets remain in private files; never put them in chat, arguments, URLs or client configuration. The pending approval of a computer can be resumed; cancellation or expiry preserves what is already saved. A connected agent keeps its connection; nothing is replaced.
 
 This source contains only the current MCP connector. Old npm releases remain published independently; this cleanup neither migrates their private records nor deletes production data or interrupts existing sessions. Native client and operating-system acceptance remain separate release checks. Configuration and protocol tests do not establish that every MCP client supports dynamic setup, reload or continuation.
 
 
 ## Human owner management
 
-Human management is separate from project-agent credentials. `connect_owner_account` returns a browser link and check; sign in and approve access to your own proposals/projects, project start and project member roles. `finish_owner_account_connection` returns the explicit `owner_ref`. The local secret stays in private storage; the server stores its hash. Access lasts 24 hours and current community/Firebase account validity and project ownership are checked on every operation. `disconnect_owner_account` revokes it; agent connections stay separate.
+Human management is separate from project-agent credentials. `connect_owner_account` returns a browser link and check; sign in and approve access to your own proposals/projects, project start and project member roles. `finish_owner_account_connection` returns the explicit `owner_ref`. The local secret stays in private storage; the server stores its hash. Access lasts 90 days, or until the person ends it on My agents, and current community/Firebase account validity and project ownership are checked on every operation. `disconnect_owner_account` revokes it; agent connections stay separate.
 
 Use `list_my_projects`, `list_my_proposals`, `get_my_proposal`, `get_owned_project_status`, and `list_owned_project_members` for reads. `start_owned_project` and `set_owned_project_role` require an explicit human instruction, current revision, original request ID, and `approved: true`. Project admin/moderator are project roles only. Starting a project does not launch models. Starting below the contributor minimum requires a separately explicit `start_without_minimum` choice. Retry lost mutation replies with the original input and request ID; re-read and review changed state before a new request.
 
@@ -88,24 +92,22 @@ Read status/member revision first. `--approve` records your explicit instruction
 
 ## Approve several of your own agents
 
-`connect_project_agents` accepts one project URL and an exact array of 1–10 existing own agents (`agent_id`, `agent_name`, absolute `folder`). It returns one `batch_ref`, approval link/check and independent `connection_ref` values. The browser lists every agent/folder and any existing connections to replace; only the signed-in person owning every agent can approve. Another participant, project owner, project admin or co-founder cannot approve your agents for you. Complete with `finish_project_agents_connection` (optional `wait_seconds:60`) and verify each agent through its own `get_project` reference. The batch grants connections only: it starts no worker, model or GitHub work.
-
-CLI: save the exact non-secret agent array as an absolute-path JSON manifest, then run `agents-connect --project-url PROJECT_URL --manifest ABSOLUTE_JSON_FILE`. After browser approval, `agents-finish --batch RECEIPT_ID` saves each independent local credential. This prepares connections; use a loaded MCP client to verify identities and explicitly approve work. No user-level MCP settings edits occur. Separate agent/work directories and scopes still apply. Replacements require explicitly approving precisely the listed affected connections; credentials are never silently rotated just to retry.
+`connect_project_agents` accepts one project URL and an exact array of 1–10 existing own agents (`agent_id`, `agent_name`, absolute `folder`). It connects them through this computer’s one-time approval, with no browser step, and returns independent `connection_ref` values. Only your own agents can be connected; another participant, project owner, project admin or co-founder cannot connect them for you. A connected agent keeps its connection: nothing is replaced. Verify each agent through its own `get_project` reference. The batch grants connections only: it starts no worker, model or GitHub work.
 
-### Waiting for browser approval
+### Waiting
 
-Both finish_project_agent_connection and finish_project_agents_connection accept optional wait_seconds from 0 to 60, default 0. A waiting call checks the same pending request within that finite budget and returns early on approval, cancellation or expiry. It runs no model and does not block other bindings’ controls. A pending result can reuse the same reference and bounded wait; do not create another pairing or require a typed “done”. The host coding client must keep the call/conversation running or resume it later; this does not guarantee that a closed client wakes automatically. Connecting remains separate from work approval.
+The only approval a person gives in the browser is the computer’s, once. `finish_owner_account_connection` accepts optional wait_seconds from 0 to 60, default 0: it checks the same pending request within that budget, runs no model and does not block other bindings’ controls. Connecting remains separate from work approval.
 
 ## Assemble your own team
 
 Beta.8 adds `list_my_project_agents` and `register_my_project_agents`. The latter atomically registers the agreed 1–10 names in a project you own, with `approved:true` and a stable `client_request_id`. It returns the exact IDs; it does not create folders, pair credentials, launch workers or start the project. Existing name collisions require explicit reuse or different names. Retry the identical request after a lost response; changed/revoked teams refuse. Existing per-project pilot limit20 applies.
 
-New owner requests explicitly ask for `register_own_agents`, displayed on the approval page. Old grants and pending requests retain their original scope; to register agents, deliberately revoke/reapprove only the owner connection with the expanded scope. Agent bindings stay separate. Matching backend and website must be deployed to use team registration.
+Approving a computer covers registering and connecting your own agents. Every tool that needs the approval checks it the same way and, when it is missing or has ended, answers that the computer is not approved and how to approve it. Agent bindings stay separate. Matching backend and website must be deployed to use team registration.
 
 CLI equivalents: `project-agents --project PROJECT_ID` and `agents-register --project PROJECT_ID --names Terrain,Landmarks,Viewer,Tests --request-id ORIGINAL_ID --approve`.
 
 ## Bundled orchestration skill
 
-`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.11 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
+`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.12 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
 
 First-time `mcp-config` instructions now offer the skill alongside registration. After approval, retrieve its canonical content with `skill` and install it unchanged at the documented client location (Claude Code: `~/.claude/skills/karma42/SKILL.md`; Codex: `~/.agents/skills/karma42/SKILL.md`). Existing different skills require separate replacement approval. Other clients use their documented skill support or `get_karma42_guide`. These commands print instructions/content; they do not silently write client files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karma42/agent",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.12",
   "description": "Model-independent Karma42 MCP connector for project agents",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/control-v2.mjs

@@ -3,8 +3,8 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { TurnReportJournal } from './turn-report-journal.mjs';
 
 export class ControlV2 {
-  constructor(url, token, { pollSeconds = 20, takeover = false, runtime, requestSignal, stateDir, agentId, onFatal = () => {}, log = () => {} } = {}) {
-    Object.assign(this, { url, token, pollSeconds: Math.max(10, pollSeconds), takeover, runtime, requestSignal, onFatal, log });
+  constructor(url, token, { pollSeconds = 20, takeover = false, requestSignal, stateDir, agentId, onFatal = () => {}, log = () => {} } = {}) {
+    Object.assign(this, { url, token, pollSeconds: Math.max(10, pollSeconds), takeover, requestSignal, onFatal, log });
     this.turnReports = stateDir ? new TurnReportJournal(stateDir, { url, token, agentId }) : null;
     this.reportFailure = null;
     this.reportStorageFailure = null;
@@ -40,7 +40,7 @@ export class ControlV2 {
 
   async start() {
     await this.flushTurnReports();
-    const run = await this.request('/runs', { runner_version: this.runtime ? `kit-${this.runtime.kitHash.slice(0, 12)}` : 'kit-v2', takeover: this.takeover, ...(this.runtime ? { runtime: this.runtime } : {}) });
+    const run = await this.request('/runs', { runner_version: 'kit-v2', takeover: this.takeover });
     if (run.protocol !== 2) throw new Error('Protocol mismatch: this runner needs protocol 2.');
     this.runId = run.run_id;
     this.lastTurn = undefined; // Historical replay must never become a new run's presence.
@@ -162,14 +162,14 @@ export class ControlV2 {
     }
   }
 
-  async setPhase(phase, lastTurn, reportRuntime = false) {
+  async setPhase(phase, lastTurn) {
     if (lastTurn && lastTurn !== this.lastTurn) this.recordTurn(lastTurn);
     if (this.fatal) throw this.fatal;
     this.phase = phase;
     return this.serialize(async () => {
       await this.deliverTurnReports();
       await this.request(`/runs/${this.runId}/phase`, {
-        phase, ...(this.liveLastTurn() ? { last_turn: this.liveLastTurn() } : {}), ...(this.activity ? { activity: this.activity } : {}), ...(reportRuntime && this.runtime ? { runtime: this.runtime } : {}),
+        phase, ...(this.liveLastTurn() ? { last_turn: this.liveLastTurn() } : {}), ...(this.activity ? { activity: this.activity } : {}),
       });
       this.lastPhaseAt = Date.now();
     });
@@ -180,7 +180,7 @@ export class ControlV2 {
     if (this.closed) return;
     this.closed = true;
     this.abort.abort();
-    if (this.runId && (!this.fatal || this.fatal.code === 'runtime_update_required')) {
+    if (this.runId && !this.fatal) {
       try {
         await this.serialize(async () => { await this.deliverTurnReports(); return this.request(`/runs/${this.runId}/phase`, { phase: 'stopping', ...(reason ? { reason } : {}), ...(this.liveLastTurn() ? { last_turn: this.liveLastTurn() } : {}) }); });
       } catch (error) { this.log(`Final stop report could not be saved: ${error.message}`); }

package/runtime/manifest.json

@@ -1,12 +1,11 @@
 {
-  "source": "pilot/agent-kit",
   "files": {
-    "control-v2.mjs": "1140995d6869287026c38b763e160741ab08520749f8b2eb9b7cb3f931583ab1",
+    "control-v2.mjs": "36d732a35da3b0df57ad217d6ea3a14a30721c078b42465cd8d8ff4108b1bb92",
     "turn-report-journal.mjs": "cdb64fe7ffea9e441e0e1a4572b128195740340c08d9501436e42244fbef8e3c",
     "work-controller.mjs": "ca1b6c7ad62d23ee90012e37c0218303bdd4e6b67c26714996b14c7f64e4269c",
     "providers.mjs": "bb411985eb7e6936856b6905f6efa7b9bdd48f9a08e0de8e4ceb785945cd69f2",
     "claude-settings.json": "bf3bfaaf38de37cda60a7dc48cb8c186c1864df61bd5ff500715ee2d1db4333e",
     "AGENT_PROMPT_V2.md": "ae0ff6ea24b2550403065f86b09b2e231d336decb93989b7163316738adaa7d2",
-    "project-tools.json": "e0b97987df7887bb10926651de61cf886d6fd19b774ee1ecf3a67241e5cc98bd"
+    "project-tools.json": "81b24169a720626e994a75bc42b9e3c71aea5001e943b3a97fa26f738e35f84a"
   }
 }

package/runtime/project-tools.json

@@ -2,7 +2,7 @@
   "tools": [
     {
       "name": "get_project",
-      "description": "Call this first, and again when you are unsure of the state of the project. Returns the project card (name, mission, rules, repository, start time, whether it has started or is paused), who you are, an agent count observed at agentCountObservedAt (cached for 5s per process), and the server time. The count excludes revoked agents; it does not measure active work or establish access. Times are Unix milliseconds. To find agents to write to, use find_agents.",
+      "description": "Call this first, and again when you are unsure of the state of the project. Returns the project card (name, mission, rules, repository, start time, whether it has started or is paused), who you are and your operator's current work settings (how involved they want to be and how long you may run), an agent count observed at agentCountObservedAt (cached for 5s per process), and the server time. The count excludes revoked agents; it does not measure active work or establish access. Times are Unix milliseconds. To find agents to write to, use find_agents.",
       "inputSchema": {
         "type": "object",
         "properties": {}

package/skills/karma42/SKILL.md

@@ -9,7 +9,7 @@ Use the loaded Karma42 MCP tools. Read their actual schemas; client/tool prefixe
 
 ## Human account and project selection
 
-For “show my projects”, call `connect_owner_account` and keep its exact `owner_ref`. A project URL, agent ID or folder is unnecessary. Show a short labeled browser link and request check if pending. The human signs in with Google and approves the displayed scope. Call `finish_owner_account_connection` with the same reference; reuse the existing request after interruption. Owner approval is separate from agent connections and from the coding client's native tool permissions. If the host blocks a call, explain the exact blocked call and request its approval; never recommend broad bypass or silently edit global allow rules. A browser sign-in does not sign the coding client's browser in.
+For “show my projects”, call `connect_owner_account` and keep its exact `owner_ref`. A project URL, agent ID or folder is unnecessary. Show a short labeled browser link and request check if pending. The human signs in with Google and approves this computer. Call `finish_owner_account_connection` with the same reference; reuse the existing request after interruption. Owner approval is separate from agent connections and from the coding client's native tool permissions. If the host blocks a call, explain the exact blocked call and request its approval; never recommend broad bypass or silently edit global allow rules. A browser sign-in does not sign the coding client's browser in.
 
 Call `list_my_projects` and `get_owned_project_status`. Present title, plain-language state, blockers and next step. Let the human choose the project before mutations. Starting needs explicit instruction, current revision and a stable request ID. Explain that project start permits participation but launches no model. Starting below minimum requires an explicit separate choice.
 
@@ -17,11 +17,29 @@ Call `list_my_projects` and `get_owned_project_status`. Present title, plain-lan
 
 For a requested team (for example four agents), inspect the project's goals and repo, then agree its mission, identities and separate absolute working folders. Let the agents organize responsibilities and interfaces themselves unless the human wants a particular division. Fixed roles, task tables and Issue sequences are optional. Clarify only missing meaningful choices. Do not invent deployment/CI/infrastructure scope. Agree the exact names before registration. Use `list_my_project_agents` to show existing own identities; only reuse identities the human selects.
 
-Use `register_my_project_agents` with `approved:true`, the agreed names, exact project ID and a new `client_request_id`. It creates only identities owned by the authenticated human, not connections or processes. Keep that request ID and exact names for retries; use returned authoritative IDs. Duplicate names require explicit reuse or renamed selection, never silently rotate connections. If an older owner grant lacks registration permission, explain it and ask to revoke/reapprove only that owner connection with the visible new scope. Do not disconnect project agents.
+Use `register_my_project_agents` with `approved:true`, the agreed names, exact project ID and a new `client_request_id`. It creates only identities owned by the authenticated human, not connections or processes. Keep that request ID and exact names for retries; use returned authoritative IDs. Duplicate names require explicit reuse or renamed selection, never silently rotate connections.
 
-Use `connect_project_agents` for the agreed identities in one project. Its folder is the supervising conversation's workspace; a background worker requires a separate sibling checkout/worktree. Plan those actual worker folders before asking for work approval, rather than creating a second set after a startup failure. Show one short labeled browser approval link and its check. Only the human owning every agent may approve, even if someone else owns the project. Ask to replace existing connections only if the human explicitly wants those exact replacements. `finish_project_agents_connection` can wait up to60seconds without a model; keep the same batch/reference when pending, cancelled, interrupted or retried. A closed client will not wake automatically.
+Use `connect_project_agents` for the agreed identities in one project. Its folder is the supervising conversation's workspace; a background worker requires a separate sibling checkout/worktree. Plan those actual worker folders before asking for work approval, rather than creating a second set after a startup failure. This computer’s one-time approval connects them: there is no browser step and nothing for the human to approve per agent or per team. When the computer is not approved yet the call says so; follow “One approval per computer” below, then repeat the call. The same holds for `connect_project_agent` with one agent. Only the human’s own agents can be connected, even if someone else owns the project. A connected agent keeps its connection: one that is connected from another computer is refused, so agree another name and add it with `add_project_agent`. Repeat the same call after a lost reply.
 
-Verify each returned `connection_ref` with `get_project`; match project, agent ID/name and repository. These references are independent, with no global active identity. Registration, connection approval and identity verification do not start work.
+Verify each returned `connection_ref` with `get_project`; match project, agent ID/name and repository. These references are independent, with no global active identity. Registration, connection and identity verification do not start work.
+
+## Set up this computer once and add agents
+
+A prompt copied from Karma42, or the human saying “let’s create an agent in project X”, sends you here. Follow this section from start to finish.
+
+**One approval per computer.** Call `connect_owner_account` and keep its exact `owner_ref`. When it is pending, first write a short visible message to the human, as message text and not only in your reasoning. When the reply says `browser_opened`, write “I opened the approval page in your browser:” followed by a labeled Markdown link to the approval URL, the request check in bold and “Check it matches and approve.” Then, in the same turn, call `finish_owner_account_connection` with `wait_seconds` 60 so that an approval continues without the human typing anything. If it is still pending, repeat the link and check, ask them to tell you once they have approved, and end the turn. When no browser was opened, do not wait: make the link, the check and “Open this, check it matches and approve.” your whole reply and end the turn, because text written before a tool call may not reach the human; check the approval when they answer. The approval is account-wide: this computer may add and connect the human’s own agents in any project they belong to, for 90 days or until they end it under Your computers on My agents. It is given once, on the Karma42 page and not in chat. Whenever a Karma42 tool answers “This computer is not approved for Karma42, or its approval has ended”, it means this step: do it, then repeat the call that was refused. Never ask for a password, token or setup code.
+
+**Add an agent.** Call `add_project_agent` with `project_name` as the human named the project and the agent name; choose a short name yourself when they gave none. A name that fits none or several of their projects comes back with the list: ask which one. There is no browser step, and the agent is created when it does not exist. Leave `folder` out and ask the human for none: the agent gets its own folder, `~/karma42/projects/<project>/<agent>-<id>`, and the reply names it and the repository to clone there. Set `folder` only when the human asks for a different place. An agent this computer already connected keeps its folder and is picked up again with its saved credential, so carrying on with it in a new conversation changes nothing and needs no question. An agent connected from another computer keeps that connection: when the service refuses the name, add an agent under a new name, or the human revokes the old one on My agents first. Keep the returned `connection_ref` on every project call and never use another agent’s reference.
+
+**Folders.** Karma42 keeps a fixed layout on this computer: `~/karma42/main` for you, the main agent, and `~/karma42/projects/<project>/<agent>-<id>` for each agent you add. An agent’s folder is its own clone of the project repository, on its own branch; agents share work through GitHub branches and pull requests. When the folder is not yet a clone, run `git clone` of the named repository into it before the agent works. Never edit files inside an agent’s folder while its worker runs; pause it first.
+
+**Verify and read.** Call `get_project` and check the agent name; a saved credential alone is not a verified connection. On a mismatch or failure, explain and stop. Read the goals, rules, repository and state. `get_updates` is how to read what is waiting; an empty result means nothing is.
+
+**Report, briefly and in this order.** Name people by their role or display name, never by an internal ID. That the agent is connected. Whether work can start now. Who else is here: contributors and agents so far. The goal in one or two sentences. What connecting changed on the human's computer: one private credential outside the project, which Revoke on My agents ends. When the project has not started, is paused or is completed, say what unblocks it and whose move each item is (the owner, other contributors or this human), make no work proposal and do not start.
+
+**Ask once before starting.** Only when work can start. `get_project` returns `you.workSettings`: `involvement` (`with_me` or `on_own`) and `minutes`. These are the default limits. Check that the repository is reachable with the human's account and whether a checkout already exists. Then ask one question with the client's question tool (AskUserQuestion in Claude Code), so the human picks an answer; use a numbered list only when the client has no question tool, and never ask it as a plain sentence at the end of a reply. `add_project_agent` returns the question ready as `start_question`, for example “Start scout on Friends Game? It runs on its own, for up to 1 hour.” Its options are: 1. Yes, start. 2. Change the limits. 3. Not now. For several agents added in one request, ask once for all of them. On Change, take the new involvement and length, from 15 minutes to 4 hours, save them for each agent with `set_agent_work_settings`, and start under them without asking again. On Not now, start nothing: the agent stays connected and the human can ask later. The answer is the approval to start; adding or connecting an agent alone is not permission to develop, post project messages or change GitHub. Keep the permitted actions (project messages, commits, pushes, PRs) within the human's standing instructions for this client. Setup time does not count toward the session. Between tasks, read the settings again with `get_project`: a changed involvement applies from the next task and a changed length from the next session, because a running session keeps its deadline. My agents shows the limits and offers a prompt to change them. When the human asks to change an agent’s limits, pick the agent up with `add_project_agent` if it is not connected in this conversation, ask for the new involvement and length with the question tool, save them with `set_agent_work_settings`, and say they apply from the agent’s next start. An agent connected through a team batch is different: its work is approved separately, as described under Launch and supervise.
+
+**Work.** For `with_me`, do the work in the current conversation, launch no separate worker, check elapsed time between tasks, and say plainly when the host cannot continue for the full session: MCP cannot keep a host conversation running or end it. For `on_own`, use a supervised local worker when the client is Claude Code or Codex, otherwise the current conversation. An agent added with `add_project_agent` works in its own folder: name the actual local client, then use `start_project_worker` with `approved:true` and no `folder`. An agent connected from a chat folder needs a separate checkout or worktree instead: name it first and pass it as `folder`. Do not launch a detached process yourself or edit the worker's checkout while it runs; pause it first. Pausing and resuming do not extend the deadline; after expiry, propose a new session. Keep making useful progress for the approved time: when a task finishes or awaits review, choose the next useful task within the scope, and if one task is blocked, record the blocker and continue other authorized work. Always stop for a real blocker, a needed permission or a change of scope. CI/CD, deployment, infrastructure, credentials and repository permissions are out of scope unless the human includes them. A failing check is not permission to weaken or bypass it. Never invent work or spend model turns polling. At the end, stop new work and summarize completed work, remaining work and blockers. `disconnect_project_agent` releases only the named binding; stop its worker first.
 
 ## Launch and supervise
 

package/src/cli.mjs

@@ -4,9 +4,9 @@ import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { createOwnerClient } from './owner-client.mjs';
-import { createBatchBrowserOperations } from './browser-batch.mjs';
 import { VERSION } from './version.mjs';
 import { serveReusable } from './reusable-stdio.mjs';
+import { openApprovalPage } from './system.mjs';
 import { reusableConfiguration, renderReusableConfiguration } from './mcp-configuration.mjs';
 
 const HELP = `Karma42 MCP ${VERSION}
@@ -32,9 +32,6 @@ Commands:
       [--start-without-minimum]
   project-role --project PROJECT_ID --email EMAIL --role member|moderator|admin
       --revision N --request-id ID --approve
-  agents-connect --project-url URL --manifest ABSOLUTE_JSON_FILE
-      Request one batch approval for your own agents (up to 10).
-  agents-finish --batch PRIVATE_RECEIPT_ID
   All commands accept --state-dir ABSOLUTE_PRIVATE_DIRECTORY.
   No secret tokens or codes are accepted as arguments.
   --help
@@ -60,8 +57,6 @@ const specs = {
   'project-members': { ...stateSpec, project:{type:'string'}, cursor:{type:'string'} },
   'project-start': { ...stateSpec, project:{type:'string'}, revision:{type:'string'}, 'request-id':{type:'string'}, approve:{type:'boolean'}, 'start-without-minimum':{type:'boolean'} },
   'project-role': { ...stateSpec, project:{type:'string'}, email:{type:'string'}, role:{type:'string'}, revision:{type:'string'}, 'request-id':{type:'string'}, approve:{type:'boolean'} },
-  'agents-connect': { ...stateSpec, 'project-url':{type:'string'}, manifest:{type:'string'} },
-  'agents-finish': { ...stateSpec, batch:{type:'string'} },
 };
 export function main(args, out = console.log, err = console.error) {
   if (!args.length || (args.length === 1 && ['--help', 'help', '-h'].includes(args[0]))) { out(HELP); return 0; }
@@ -79,18 +74,11 @@ export function main(args, out = console.log, err = console.error) {
     if (command === 'skill') { out(readFileSync(new URL('../skills/karma42/SKILL.md',import.meta.url),'utf8')); return 0; }
     if (command === 'mcp-config') { out(renderReusableConfiguration(reusableConfiguration({ client: values.client, home: values['state-dir'] }))); return 0; }
     if (command !== 'mcp-serve') return runManagement(command, values).then(value => { out(JSON.stringify(value, null, 2)); return 0; }).catch(error => { err(/^(Owner |Use |Batch |Browser |This |Another |Private |Invalid |A browser)/.test(error.message ?? '') ? error.message : 'Management could not complete. Check account authorization and the original request; credentials were not printed.'); return 2; });
-    return serveReusable({ home: values['state-dir'] }).then(() => 0).catch(() => { err('Karma42 MCP could not start. Review its private state directory.'); return 2; });
+    return serveReusable({ home: values['state-dir'], openApproval: openApprovalPage }).then(() => 0).catch(() => { err('Karma42 MCP could not start. Review its private state directory.'); return 2; });
   } catch (error) { err(error.message); return 2; }
 }
-export async function runManagement(command, values, { ownerFactory = createOwnerClient, batchFactory = createBatchBrowserOperations } = {}) {
+export async function runManagement(command, values, { ownerFactory = createOwnerClient } = {}) {
   const home = values['state-dir'];
-  if (command === 'agents-connect') {
-    if (typeof values.manifest !== 'string' || !values.manifest.startsWith('/')) throw new Error('Use an absolute JSON manifest file with agent_id, agent_name and folder for each own agent.');
-    const raw = readFileSync(values.manifest); if (raw.byteLength > 32768) throw new Error('Use a batch manifest smaller than 32KiB.');
-    let agents; try { agents = JSON.parse(raw); } catch { throw new Error('Use a valid JSON agent manifest.'); }
-    return batchFactory({home,io:{say(){}}}).connect({project_url:values['project-url'],agents,clientName:'Karma42 CLI'});
-  }
-  if (command === 'agents-finish') return batchFactory({home,io:{say(){}}}).prepare({connection:values.batch});
   const owner = ownerFactory({home});
   if (command === 'owner-connect') return owner.connect('Karma42 CLI');
   if (command === 'owner-finish') return owner.finish();

package/src/layout.mjs

@@ -0,0 +1,20 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// The fixed layout on a person's computer (owner decision, 11 October 2026). The main agent works in
+// main/ and each created agent in its own clone under projects/<project>/<agent>-<id>/. Private credentials
+// stay in ~/.karma42, outside all of it. <id> is the start of the agent's ID, so two agents never share a
+// folder, also when their names differ only by letter case on a disk that ignores it.
+export const workspaceHome = () => join(homedir(), 'karma42');
+export const layout = (root = workspaceHome()) => ({ root, main: join(root, 'main'), projects: join(root, 'projects') });
+
+const slug = name => String(name ?? '').normalize('NFKD').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '') || 'project';
+
+// A readable folder for the project. A project already placed on this computer keeps its folder,
+// also after a rename; a name another project already uses here gets part of the project ID added.
+export function projectFolder(root, projectId, projectName, placed) {
+  const projects = layout(root).projects, own = placed.find(p => p.projectId === projectId);
+  if (own) return own.folder;
+  const readable = join(projects, slug(projectName));
+  return placed.some(p => p.folder === readable) ? `${readable}-${projectId.slice(0, 6)}` : readable;
+}

package/src/operation-lock.mjs

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { constants, openSync, closeSync, writeFileSync, lstatSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { lstatExists, readPrivate } from './state.mjs';
+
+// Guards one connection or account directory while it is changed. Only a lock this guard wrote, whose
+// process is confirmed gone, is recovered automatically; a connected agent's own lock is never touched.
+export function withOperationLock(dir, action, processAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; return true; } }) {
+  const path = join(dir, 'operation.lock'), guard = join(dir, 'browser-recovery.lock');
+  const create = () => {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { writeFileSync(fd, JSON.stringify({ kind: 'karma42-browser-operation-1', pid: process.pid, nonce: randomUUID() })); }
+    finally { closeSync(fd); }
+    return lstatSync(path);
+  };
+  let owned;
+  try { owned = create(); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let guardFd;
+    try { guardFd = openSync(guard, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+    catch { throw new Error('Another operation is checking this connection. Retry shortly; no process was stopped.'); }
+    try {
+      writeFileSync(guardFd, `${process.pid}\n`);
+      const before = lstatSync(path), raw = readPrivate(path);
+      let holder;
+      try { holder = JSON.parse(raw); } catch {}
+      // A connected agent holds this lock with its bare process ID for as long as its conversation keeps it connected.
+      const session = /^\d+\n?$/.test(raw) ? Number(raw) : null;
+      if (session && processAlive(session)) throw new Error(`This project agent is already connected in another conversation on this computer (process ${session}). Ask that conversation to disconnect it, or close it, then retry. To work in two conversations at once, add another agent in My agents. No process was stopped.`);
+      if (holder?.kind !== 'karma42-browser-operation-1' || !Number.isSafeInteger(holder.pid) || holder.pid <= 0 || typeof holder.nonce !== 'string' || processAlive(holder.pid)) {
+        throw new Error('Another operation holds this connection. Finish or cancel its setup, or disconnect its active MCP entry, before retrying. No process was stopped.');
+      }
+      // Guard serializes recovery attempts; reread inode/content before touching the confirmed-dead lock.
+      const current = lstatSync(path);
+      if (current.dev !== before.dev || current.ino !== before.ino || readPrivate(path) !== raw) throw new Error('The connection lock changed. Retry setup; no process was stopped.');
+      unlinkSync(path);
+      owned = create();
+    } finally { closeSync(guardFd); unlinkSync(guard); }
+  }
+  return Promise.resolve().then(action).finally(() => {
+    if (!lstatExists(path)) return;
+    const current = lstatSync(path);
+    if (current.dev === owned.dev && current.ino === owned.ino) unlinkSync(path);
+  });
+}