feat: resolve agent workspace from session/project/fallback

Heartbeat service resolves cwd from task session, project primary
workspace, or agent home directory (~/.paperclip/instances/.../workspaces/).
Adapters receive workspace context and forward it as env vars and
session params. cwd is now optional in adapter config.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/src/home-paths.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 
 const DEFAULT_INSTANCE_ID = "default";
 const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
 
 function expandHomePrefix(value: string): string {
   if (value === "~") return os.homedir();
@@ -48,6 +49,14 @@ export function resolveDefaultStorageDir(): string {
   return path.resolve(resolvePaperclipInstanceRoot(), "data", "storage");
 }
 
+export function resolveDefaultAgentWorkspaceDir(agentId: string): string {
+  const trimmed = agentId.trim();
+  if (!PATH_SEGMENT_RE.test(trimmed)) {
+    throw new Error(`Invalid agent id for workspace path '${agentId}'.`);
+  }
+  return path.resolve(resolvePaperclipInstanceRoot(), "workspaces", trimmed);
+}
+
 export function resolveHomeAwarePath(value: string): string {
   return path.resolve(expandHomePrefix(value));
 }