@parall/daemon 1.29.0 → 1.29.2

package/dist/config.d.ts

@@ -22,6 +22,8 @@ export type ClaudeDaemonConfig = {
     rootClaudeHome: string;
     /** Optional WS URL override for the machine control-plane WebSocket. */
     wsUrl?: string;
+    /** Optional swimlane routing name, e.g. pr-1191. */
+    swimlaneName?: string;
     /** @deprecated Superseded by WS event-driven model; kept for backward compat. */
     pollIntervalMs: number;
     /** @deprecated Superseded by WS event-driven model; kept for backward compat. */
@@ -61,5 +63,5 @@ export declare function sharedClaudeCredentialsFileFor(rootClaudeHome: string):
 export declare function agentClaudeCredentialsFileFor(agentClaudeHome: string): string;
 /** Per-agent workspace dir where the agent runs git commands. */
 export declare function agentWorkspaceDirFor(rootStateDir: string, agentId: string): string;
-export declare function resolveWsUrl(apiUrl: string, explicitWsUrl?: string): string;
+export declare function resolveWsUrl(apiUrl: string, explicitWsUrl?: string, swimlaneName?: string): string;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,0BAA0B,EAAE,MAAM,CAAC;IACnC,6BAA6B,EAAE,MAAM,CAAC;CACvC,CAAC;AA2BF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE7E;AAyBD,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CA4ClG;AASD,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;mEAEmE;AACnE,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,+EAA+E;AAC/E,wBAAgB,8BAA8B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,uEAAuE;AACvE,wBAAgB,6BAA6B,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,0BAA0B,EAAE,MAAM,CAAC;IACnC,6BAA6B,EAAE,MAAM,CAAC;CACvC,CAAC;AA2BF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE7E;AAyBD,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CA6ClG;AASD,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;mEAEmE;AACnE,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,+EAA+E;AAC/E,wBAAgB,8BAA8B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,uEAAuE;AACvE,wBAAgB,6BAA6B,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlG"}

package/dist/config.js

@@ -82,6 +82,7 @@ export function resolveClaudeDaemonConfig(env = process.env) {
         rootStateDir,
         rootClaudeHome,
         wsUrl: env.PRLL_WS_URL?.trim() || undefined,
+        swimlaneName: env.PRLL_SWIMLANE_NAME?.trim() || undefined,
         pollIntervalMs: parseMs(env.PRLL_DAEMON_POLL_INTERVAL_MS, 30_000),
         heartbeatIntervalMs: parseMs(env.PRLL_DAEMON_HEARTBEAT_INTERVAL_MS, 30_000),
         restartBackoffMs: parseMs(env.PRLL_DAEMON_RESTART_BACKOFF_MS, 5_000),
@@ -120,6 +121,11 @@ export function agentClaudeCredentialsFileFor(agentClaudeHome) {
 export function agentWorkspaceDirFor(rootStateDir, agentId) {
     return path.join(rootStateDir, "agents", assertSafeAgentId(agentId), "workspace");
 }
-export function resolveWsUrl(apiUrl, explicitWsUrl) {
-    return explicitWsUrl || `${apiUrl.replace(/\/$/, "").replace(/^http/, "ws")}/ws`;
+export function resolveWsUrl(apiUrl, explicitWsUrl, swimlaneName) {
+    const base = explicitWsUrl || `${apiUrl.replace(/\/$/, "").replace(/^http/, "ws")}/ws`;
+    if (!swimlaneName)
+        return base;
+    const url = new URL(base);
+    url.searchParams.set("swimlane", swimlaneName);
+    return url.toString();
 }

package/dist/index.js

@@ -76,6 +76,7 @@ async function main() {
     const client = new ParallClient({
         baseUrl: config.apiUrl,
         token: config.apiKey,
+        swimlaneName: config.swimlaneName,
     });
     const abortController = new AbortController();
     const onSignal = (sig) => {
@@ -95,7 +96,7 @@ async function main() {
         process.exitCode = 1;
         process.exit(1);
     });
-    config.wsUrl = resolveWsUrl(config.apiUrl, config.wsUrl);
+    config.wsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
     await runForever(config, client, log, abortController.signal);
 }
 const cliArgs = process.argv.slice(2);

package/dist/runtimes.d.ts

@@ -14,6 +14,7 @@ export interface AgentDirs {
     workspaceDir: string;
     claudeHome: string;
 }
+export declare function clearAllProviderCreds(env: NodeJS.ProcessEnv): void;
 export declare function getRuntimeAdapter(runtimeType: string): RuntimeAdapter;
 export declare function assertAgentKey(apiKey: string): void;
 //# sourceMappingURL=runtimes.d.ts.map

package/dist/runtimes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimes.d.ts","sourceRoot":"","sources":["../src/runtimes.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC;CAC/I;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAsHD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAErE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAInD"}
+{"version":3,"file":"runtimes.d.ts","sourceRoot":"","sources":["../src/runtimes.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC;CAC/I;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAeD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,IAAI,CAOlE;AAgGD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAErE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAInD"}

package/dist/runtimes.js

@@ -10,7 +10,7 @@ function llmSource(pc) {
     }
     return "parall";
 }
-function clearAllProviderCreds(env) {
+export function clearAllProviderCreds(env) {
     delete env.ANTHROPIC_AUTH_TOKEN;
     delete env.ANTHROPIC_BASE_URL;
     delete env.ANTHROPIC_API_KEY;

package/dist/supervisor.d.ts

@@ -24,6 +24,10 @@ export declare class DaemonSupervisor {
     private readonly client;
     private readonly log;
     private readonly children;
+    private readonly spawningAgents;
+    private readonly pendingWorkspaceSetup;
+    private readonly workspaceSetupRetryTimers;
+    private readonly cancelledSpawns;
     private ws;
     private running;
     private machineOrgId;
@@ -42,12 +46,17 @@ export declare class DaemonSupervisor {
      * by parsing session state files which embed the agent ID in the runtimeKey.
      */
     private migrateFlatLayout;
+    private fetchAttachedAgent;
     private handleAgentAttached;
     private handleAgentDetached;
+    private handleWorkspaceSetupRequested;
+    private scheduleWorkspaceSetupRetry;
+    private clearWorkspaceSetupRetry;
     private refreshMachineConfig;
     private respawnAllChildren;
     private restartChildNow;
     private spawnAgent;
+    private spawnAgentOnce;
     private startChild;
     private terminateChild;
     private ensureSharedCredentialLink;

package/dist/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAkL,MAAM,aAAa,CAAC;AAC3N,OAAO,EACL,KAAK,kBAAkB,EAMxB,MAAM,aAAa,CAAC;AASrB;;;;GAIG;AACH,iBAAS,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAa3E;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAyB5B;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IASzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAVtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,gBAAgB,CAAoB;IAC5C,OAAO,CAAC,WAAW,CAA6B;gBAG7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,aAAa;IAGrC,yEAAyE;IACnE,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA4E7C,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YA6Bb,kBAAkB;YAqClB,aAAa;IAqD3B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;YA6CX,mBAAmB;YA6BnB,mBAAmB;YAgBnB,oBAAoB;YAcpB,kBAAkB;YAYlB,eAAe;YAcf,UAAU;IAgDxB,OAAO,CAAC,UAAU;YAyEJ,cAAc;IAyB5B,OAAO,CAAC,0BAA0B;CA8BnC"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,YAAY,EAA2N,MAAM,aAAa,CAAC;AACpQ,OAAO,EACL,KAAK,kBAAkB,EAMxB,MAAM,aAAa,CAAC;AAiBrB;;;;GAIG;AACH,iBAAS,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAa3E;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAyB5B;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAazB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAdtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAC3D,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAqC;IAC/E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,gBAAgB,CAAoB;IAC5C,OAAO,CAAC,WAAW,CAA6B;gBAG7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,aAAa;IAGrC,yEAAyE;IACnE,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiF7C,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAiCb,kBAAkB;YAqClB,aAAa;IAqD3B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;YA6CX,kBAAkB;YAqBlB,mBAAmB;YAgBnB,mBAAmB;YAmBnB,6BAA6B;IAqC3C,OAAO,CAAC,2BAA2B;IAYnC,OAAO,CAAC,wBAAwB;YAUlB,oBAAoB;YAcpB,kBAAkB;YAYlB,eAAe;YAcf,UAAU;YAoBV,cAAc;IA2D5B,OAAO,CAAC,UAAU;YA0EJ,cAAc;IAyB5B,OAAO,CAAC,0BAA0B;CA8BnC"}

package/dist/supervisor.js

@@ -4,11 +4,13 @@ import * as path from "node:path";
 import { ParallWs } from "@parall/sdk";
 import { agentClaudeCredentialsFileFor, agentClaudeHomeFor, agentStateDirFor, agentWorkspaceDirFor, sharedClaudeCredentialsFileFor, } from "./config.js";
 import { assertAgentKey, getRuntimeAdapter } from "./runtimes.js";
+import { prepareWorkspace } from "./workspace.js";
 const RUNTIME_PACKAGES = {
     'claude-code': '@parall/claude-agent',
     'codex': '@parall/codex-agent',
     'openclaw': '@parall/openclaw-agent',
 };
+const WORKSPACE_SETUP_RETRY_DELAY_MS = 5_000;
 /**
  * Sleep that wakes early on abort. Returns true if the full delay elapsed,
  * false if aborted. Used by bootstrap retry and the outer keepalive in
@@ -46,6 +48,10 @@ export class DaemonSupervisor {
     client;
     log;
     children = new Map();
+    spawningAgents = new Set();
+    pendingWorkspaceSetup = new Set();
+    workspaceSetupRetryTimers = new Map();
+    cancelledSpawns = new Set();
     ws = null;
     running = false;
     machineOrgId = null;
@@ -107,6 +113,10 @@ export class DaemonSupervisor {
                 void this.respawnAllChildren();
             }
         });
+        this.ws.on("machine.workspace.setup.requested", (data) => {
+            this.log.info(`WS: workspace setup requested for agent ${data.agent_id}`);
+            void this.handleWorkspaceSetupRequested(data.agent_id);
+        });
         this.ws.on("machine.stop", (data) => {
             this.log.info(`WS: machine.stop received (reason=${data.reason ?? "none"})`);
             void this.stop();
@@ -132,6 +142,10 @@ export class DaemonSupervisor {
             this.ws = null;
         }
         const exits = [];
+        for (const timer of this.workspaceSetupRetryTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.workspaceSetupRetryTimers.clear();
         for (const state of this.children.values()) {
             state.shuttingDown = true;
             if (state.restartTimer) {
@@ -277,24 +291,31 @@ export class DaemonSupervisor {
         }
     }
     // ---- WS event handlers (incremental) ----
-    async handleAgentAttached(agentId) {
-        if (this.children.has(agentId))
-            return;
+    async fetchAttachedAgent(agentId) {
         let attached;
         try {
             attached = await this.client.listAttachedAgents();
         }
         catch (err) {
-            this.log.warn(`handleAgentAttached: listAttachedAgents failed: ${String(err)}`);
-            return;
+            this.log.warn(`fetchAttachedAgent: listAttachedAgents failed: ${String(err)}`);
+            return { kind: "retryable" };
         }
         const entry = attached.find((a) => (a.user?.id ?? a.profile.user_id) === agentId);
         if (!entry) {
-            this.log.warn(`handleAgentAttached: agent ${agentId} not found in attached list`);
-            return;
+            this.log.warn(`fetchAttachedAgent: agent ${agentId} not found in attached list`);
+            return { kind: "skip" };
         }
         if (entry.user && entry.user.status !== "active") {
             this.log.info(`agent ${agentId} not active (status=${entry.user.status}) — skipping`);
+            return { kind: "skip" };
+        }
+        return { kind: "found", entry };
+    }
+    async handleAgentAttached(agentId) {
+        if (this.children.has(agentId) || this.spawningAgents.has(agentId))
+            return;
+        const result = await this.fetchAttachedAgent(agentId);
+        if (result.kind !== "found") {
             return;
         }
         const orgId = this.machineOrgId;
@@ -302,9 +323,14 @@ export class DaemonSupervisor {
             this.log.warn(`agent ${agentId}: no org_id available yet; skipping`);
             return;
         }
-        await this.spawnAgent(agentId, orgId, entry);
+        await this.spawnAgent(agentId, orgId, result.entry);
     }
     async handleAgentDetached(agentId) {
+        this.pendingWorkspaceSetup.delete(agentId);
+        this.clearWorkspaceSetupRetry(agentId);
+        if (this.spawningAgents.has(agentId)) {
+            this.cancelledSpawns.add(agentId);
+        }
         const state = this.children.get(agentId);
         if (!state)
             return;
@@ -317,6 +343,61 @@ export class DaemonSupervisor {
         await this.terminateChild(state);
         this.children.delete(agentId);
     }
+    async handleWorkspaceSetupRequested(agentId) {
+        if (this.spawningAgents.has(agentId)) {
+            this.log.info(`agent ${agentId}: workspace setup already in progress; queueing one restart`);
+            this.pendingWorkspaceSetup.add(agentId);
+            return;
+        }
+        const result = await this.fetchAttachedAgent(agentId);
+        if (result.kind === "retryable") {
+            this.pendingWorkspaceSetup.add(agentId);
+            this.scheduleWorkspaceSetupRetry(agentId);
+            return;
+        }
+        if (result.kind === "skip") {
+            this.pendingWorkspaceSetup.delete(agentId);
+            this.clearWorkspaceSetupRetry(agentId);
+            return;
+        }
+        this.clearWorkspaceSetupRetry(agentId);
+        const state = this.children.get(agentId);
+        if (state) {
+            this.log.info(`agent ${agentId}: restarting for workspace setup`);
+            state.shuttingDown = true;
+            if (state.restartTimer) {
+                clearTimeout(state.restartTimer);
+                state.restartTimer = null;
+            }
+            await this.terminateChild(state);
+            this.children.delete(agentId);
+        }
+        const orgId = this.machineOrgId;
+        if (!orgId) {
+            this.log.warn(`agent ${agentId}: no org_id available yet; skipping`);
+            return;
+        }
+        await this.spawnAgent(agentId, orgId, result.entry);
+    }
+    scheduleWorkspaceSetupRetry(agentId) {
+        if (!this.running || this.workspaceSetupRetryTimers.has(agentId))
+            return;
+        const timer = setTimeout(() => {
+            this.workspaceSetupRetryTimers.delete(agentId);
+            if (this.running && this.pendingWorkspaceSetup.has(agentId)) {
+                void this.handleWorkspaceSetupRequested(agentId);
+            }
+        }, WORKSPACE_SETUP_RETRY_DELAY_MS);
+        timer.unref?.();
+        this.workspaceSetupRetryTimers.set(agentId, timer);
+    }
+    clearWorkspaceSetupRetry(agentId) {
+        const timer = this.workspaceSetupRetryTimers.get(agentId);
+        if (timer) {
+            clearTimeout(timer);
+            this.workspaceSetupRetryTimers.delete(agentId);
+        }
+    }
     // ---- Spawn / restart ----
     async refreshMachineConfig() {
         try {
@@ -358,6 +439,26 @@ export class DaemonSupervisor {
         }
     }
     async spawnAgent(agentId, orgId, attached) {
+        if (this.children.has(agentId) || this.spawningAgents.has(agentId)) {
+            return;
+        }
+        this.spawningAgents.add(agentId);
+        let shouldReplaySetupRequest = false;
+        try {
+            await this.spawnAgentOnce(agentId, orgId, attached);
+        }
+        finally {
+            this.spawningAgents.delete(agentId);
+            this.cancelledSpawns.delete(agentId);
+            shouldReplaySetupRequest = this.pendingWorkspaceSetup.delete(agentId);
+        }
+        if (shouldReplaySetupRequest && this.running) {
+            queueMicrotask(() => {
+                void this.handleWorkspaceSetupRequested(agentId);
+            });
+        }
+    }
+    async spawnAgentOnce(agentId, orgId, attached) {
         let credential;
         try {
             credential = await this.client.mintLaunchCredential(agentId);
@@ -367,19 +468,13 @@ export class DaemonSupervisor {
             return;
         }
         const stateDir = agentStateDirFor(this.config.rootStateDir, agentId);
-        const workspaceDir = attached.daemon_config?.workspace_path
-            || agentWorkspaceDirFor(this.config.rootStateDir, agentId);
+        const defaultWorkspaceDir = agentWorkspaceDirFor(this.config.rootStateDir, agentId);
         const isK8s = !!process.env.KUBERNETES_SERVICE_HOST;
         const claudeHome = isK8s
             ? agentClaudeHomeFor(this.config.rootClaudeHome, agentId)
             : this.config.rootClaudeHome;
         try {
             fs.mkdirSync(stateDir, { recursive: true });
-            // Only create workspace dir when using the default isolated path —
-            // user-specified workspace_path should already exist.
-            if (!attached.daemon_config?.workspace_path) {
-                fs.mkdirSync(workspaceDir, { recursive: true });
-            }
             if (isK8s) {
                 fs.mkdirSync(claudeHome, { recursive: true });
                 this.ensureSharedCredentialLink(claudeHome, agentId);
@@ -389,6 +484,24 @@ export class DaemonSupervisor {
             this.log.warn(`mkdir agent dirs (${agentId}) failed: ${String(err)}`);
         }
         const runtimeType = attached.profile.runtime_type ?? "claude-code";
+        let workspaceDir;
+        try {
+            workspaceDir = await prepareWorkspace({
+                client: this.client,
+                attached,
+                agentId,
+                defaultWorkspaceDir,
+                log: this.log,
+            });
+        }
+        catch (err) {
+            this.log.error(`agent ${agentId}: workspace setup failed: ${String(err)}`);
+            return;
+        }
+        if (this.cancelledSpawns.delete(agentId)) {
+            this.log.info(`agent ${agentId}: spawn cancelled after detach during workspace setup`);
+            return;
+        }
         const state = {
             agentId,
             orgId,
@@ -460,11 +573,12 @@ export class DaemonSupervisor {
             settleChild("error", null, null, err);
         });
         child.once("close", (code, signal) => settleChild("close", code, signal));
-        setTimeout(() => {
+        const stableTimer = setTimeout(() => {
             if (state.child === child) {
                 state.restartAttempts = 0;
             }
         }, Math.max(this.config.restartBackoffMs, 30_000));
+        stableTimer.unref?.();
     }
     async terminateChild(state) {
         const child = state.child;

package/dist/workspace.d.ts

@@ -0,0 +1,11 @@
+import type { GatewayLogger } from "@parall/agent-core";
+import type { AttachedAgent, ParallClient } from "@parall/sdk";
+export interface PrepareWorkspaceOpts {
+    client: ParallClient;
+    attached: AttachedAgent;
+    agentId: string;
+    defaultWorkspaceDir: string;
+    log: GatewayLogger;
+}
+export declare function prepareWorkspace(opts: PrepareWorkspaceOpts): Promise<string>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAA4C,YAAY,EAAE,MAAM,aAAa,CAAC;AAiBzG,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,aAAa,CAAC;CACpB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ClF"}