happy-imou-cloud 2.1.28 → 2.1.30

package/dist/{api-ChV_1TP7.cjs → api-DK1gyZAZ.cjs}

@@ -38,7 +38,7 @@ function _interopNamespaceDefault(e) {
 var z__namespace = /*#__PURE__*/_interopNamespaceDefault(z);
 
 var name = "happy-imou-cloud";
-var version = "2.1.28";
+var version = "2.1.30";
 var description = "hicloud - Imou 企业定制版。关键是 happy！移动端远程 AI 编程工具，支持 Claude Code、Codex 和 Gemini CLI";
 var author = "long.zhu";
 var license = "MIT";
@@ -1230,7 +1230,9 @@ const HappyOrgTaskContextSchema = z.z.object({
   taskId: z.z.string().min(1),
   organizationId: z.z.string().min(1),
   memberAgentId: z.z.string().min(1),
-  supervisorAgentId: z.z.string().min(1)
+  supervisorAgentId: z.z.string().min(1),
+  positionId: z.z.string().min(1).optional().nullable(),
+  responsibilityId: z.z.string().min(1).optional().nullable()
 });
 const HappyOrgTaskControlSchema = z.z.object({
   action: z.z.enum(["terminate", "reopen"]),
@@ -1242,7 +1244,9 @@ const HappyOrgTaskControlSchema = z.z.object({
 const HappyOrgReplyContextSchema = z.z.object({
   dispatchId: z.z.string().min(1),
   scope: z.z.string().min(1),
-  replyTo: z.z.string().min(1)
+  replyTo: z.z.string().min(1),
+  positionId: z.z.string().min(1).optional().nullable(),
+  responsibilityId: z.z.string().min(1).optional().nullable()
 });
 const HappyOrgDispatchBusinessAckStatusSchema = z.z.enum([
   "accepted",
@@ -1595,6 +1599,15 @@ const AgentMessageSchema = z.z.object({
 const MessageContentSchema = z.z.union([UserMessageSchema, AgentMessageSchema]);
 
 const HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION = "1.7.3-local-repo-v1";
+const HAPPY_ORG_WRITER_LOCK_SCHEMA_VERSION = "1.7.3-writer-lock-v1";
+const WRITER_LOCK_LEASE_DURATION_SECONDS = 900;
+const WRITER_LOCK_RENEW_BEFORE_SECONDS = 300;
+const WRITER_LOCK_CEO_TAKEOVER_AFTER_SECONDS = 1800;
+const WRITER_LOCK_RENEW_INTERVAL_MS = Math.max(
+  (WRITER_LOCK_LEASE_DURATION_SECONDS - WRITER_LOCK_RENEW_BEFORE_SECONDS) * 1e3,
+  1e3
+);
+let writerLockSequence = 0;
 const TaskStatusSchema = z.z.enum([
   "draft",
   "ready",
@@ -1678,10 +1691,46 @@ const UpdateTaskRequestSchema = BaseRequestSchema.extend({
   expectedRevision: z.z.number().nullable(),
   nextState: TaskUpdatePayloadSchema
 });
+const AgentUpsertPayloadSchema = z.z.object({
+  id: z.z.string().min(1),
+  slug: z.z.string().min(1),
+  role: z.z.string().min(1),
+  name: z.z.string().min(1),
+  sessionId: z.z.string().min(1),
+  sessionTitle: z.z.string().min(1),
+  runtimePath: z.z.string().nullable(),
+  workingDirectoryRelativePath: z.z.string().nullable().optional(),
+  machineId: z.z.string().nullable(),
+  backend: z.z.string().nullable(),
+  supervisorAgentId: z.z.string().nullable(),
+  createdAt: z.z.number(),
+  updatedAt: z.z.number()
+});
+const PositionUpsertPayloadSchema = z.z.object({
+  positionId: z.z.string().min(1),
+  slug: z.z.string().min(1),
+  label: z.z.string().min(1),
+  role: z.z.string().nullable(),
+  workingDirectoryRelativePath: z.z.string().nullable(),
+  agentId: z.z.string().nullable(),
+  agentName: z.z.string().nullable(),
+  supervisorAgentId: z.z.string().nullable(),
+  responsibilityIds: z.z.array(z.z.string()),
+  occupancyStatus: z.z.enum(["occupied", "vacancy", "assigned", "active"]),
+  createdAt: z.z.number(),
+  updatedAt: z.z.number()
+});
+const UpsertAgentRequestSchema = BaseRequestSchema.extend({
+  requestType: z.z.literal("upsert_agent"),
+  agent: AgentUpsertPayloadSchema,
+  position: PositionUpsertPayloadSchema,
+  expectedRevision: z.z.number().nullable()
+});
 const RequestSchema = z.z.discriminatedUnion("requestType", [
   ReplaceGoalRequestSchema,
   CreateTaskRequestSchema,
-  UpdateTaskRequestSchema
+  UpdateTaskRequestSchema,
+  UpsertAgentRequestSchema
 ]);
 const RevisionEnvelopeSchema = (value) => z.z.object({
   schemaVersion: z.z.literal(HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION),
@@ -1694,16 +1743,23 @@ const PositionValueSchema = z.z.object({
   positionId: z.z.string(),
   slug: z.z.string(),
   label: z.z.string(),
-  role: z.z.string(),
-  agentId: z.z.string(),
-  agentName: z.z.string(),
+  role: z.z.string().nullable().optional(),
+  workingDirectoryRelativePath: z.z.string().nullable().optional(),
+  agentId: z.z.string().nullable().optional(),
+  agentName: z.z.string().nullable().optional(),
   supervisorAgentId: z.z.string().nullable(),
   responsibilityIds: z.z.array(z.z.string()),
-  occupancyStatus: z.z.enum(["occupied", "vacancy"]),
+  occupancyStatus: z.z.enum(["occupied", "vacancy", "assigned", "active"]),
   truthPath: z.z.string(),
   createdAt: z.z.number(),
   updatedAt: z.z.number()
 });
+const WorkspaceValueSchema = z.z.object({
+  positionId: z.z.string(),
+  slug: z.z.string(),
+  relativePath: z.z.string().nullable(),
+  updatedAt: z.z.number()
+});
 const ResponsibilityValueSchema = z.z.object({
   responsibilityId: z.z.string(),
   title: z.z.string(),
@@ -1713,6 +1769,7 @@ const ResponsibilityValueSchema = z.z.object({
   status: z.z.enum(["vacancy", "assigned", "in_progress"]),
   memberAgentId: z.z.string().nullable(),
   memberName: z.z.string().nullable(),
+  role: z.z.string().nullable().optional(),
   activeTaskId: z.z.string().nullable(),
   createdAt: z.z.number(),
   updatedAt: z.z.number()
@@ -1795,11 +1852,45 @@ const LogValueSchema = z.z.object({
 });
 const GoalEnvelopeSchema = RevisionEnvelopeSchema(GoalSchema);
 const PositionEnvelopeSchema = RevisionEnvelopeSchema(PositionValueSchema);
+const WorkspaceEnvelopeSchema = RevisionEnvelopeSchema(WorkspaceValueSchema);
 const ResponsibilityEnvelopeSchema = RevisionEnvelopeSchema(z.z.array(ResponsibilityValueSchema));
 const TaskEnvelopeSchema = RevisionEnvelopeSchema(TaskValueSchema);
 const WorkflowEnvelopeSchema = RevisionEnvelopeSchema(WorkflowValueSchema);
 const ResultEnvelopeSchema = RevisionEnvelopeSchema(ResultValueSchema);
 const LogEnvelopeSchema = RevisionEnvelopeSchema(LogValueSchema);
+const WriterLockRecordSchema = z.z.object({
+  schemaVersion: z.z.literal(HAPPY_ORG_WRITER_LOCK_SCHEMA_VERSION),
+  lockId: z.z.string().min(1),
+  target: z.z.string().min(1),
+  holderType: z.z.literal("cli-writer"),
+  holderId: z.z.string().min(1),
+  requestId: z.z.string().min(1),
+  pid: z.z.number().int().nonnegative(),
+  acquiredAt: z.z.number().int().nonnegative(),
+  renewedAt: z.z.number().int().nonnegative(),
+  expiresAt: z.z.number().int().nonnegative(),
+  leaseDurationSeconds: z.z.literal(WRITER_LOCK_LEASE_DURATION_SECONDS),
+  renewBeforeSeconds: z.z.literal(WRITER_LOCK_RENEW_BEFORE_SECONDS),
+  ceoTakeoverAfterSeconds: z.z.literal(WRITER_LOCK_CEO_TAKEOVER_AFTER_SECONDS),
+  takeoverOf: z.z.object({
+    lockId: z.z.string().min(1),
+    holderId: z.z.string().min(1),
+    requestId: z.z.string().min(1),
+    renewedAt: z.z.number().int().nonnegative()
+  }).nullable()
+});
+class WriterLockConflictError extends Error {
+  state;
+  target;
+  existing;
+  constructor(state, target, message, existing = null) {
+    super(message);
+    this.name = "WriterLockConflictError";
+    this.state = state;
+    this.target = target;
+    this.existing = existing;
+  }
+}
 function normalizePortablePath(value) {
   const trimmed = value?.trim();
   if (!trimmed) {
@@ -1807,14 +1898,37 @@ function normalizePortablePath(value) {
   }
   return trimmed.replace(/\\/g, "/").replace(/\/{2,}/g, "/").replace(/\/$/, "");
 }
+function normalizeRelativePath(value) {
+  const segments = (value ?? "").split(/[\\/]+/).map((segment) => segment.trim()).filter(Boolean).filter((segment) => segment !== "." && segment !== "..");
+  return segments.length > 0 ? segments.join("/") : null;
+}
+function resolveRelativePath(rootPath, relativePath) {
+  const normalizedRelativePath = normalizeRelativePath(relativePath);
+  if (!normalizedRelativePath) {
+    return null;
+  }
+  return path.join(rootPath, ...normalizedRelativePath.split("/"));
+}
+function normalizeOccupancyStatus(value) {
+  switch (value) {
+    case "vacancy":
+      return "vacancy";
+    case "active":
+      return "active";
+    case "assigned":
+    case "occupied":
+    default:
+      return "assigned";
+  }
+}
 function normalizeAdviceRoute(value) {
   return value === "gm" || value === "lead" || value === "user" ? value : null;
 }
 function buildResponsibilityId(slug) {
   return `responsibility-${slug}`;
 }
-function buildPositionId(slug) {
-  return `position-${slug}`;
+function buildPositionRoot(rootPath, slug) {
+  return path.join(rootPath, "positions", slug);
 }
 function toTaskSlug(taskId, title) {
   const slug = title.trim().toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "-").replace(/^-+|-+$/g, "");
@@ -1859,6 +1973,74 @@ function buildRequestFilePath(rootPath, requestId) {
 function buildTaskRoot(rootPath, taskId) {
   return path.join(rootPath, "tasks", taskId);
 }
+function nextWriterLockId() {
+  writerLockSequence += 1;
+  return `writer-lock-${process.pid}-${Date.now().toString(36)}-${writerLockSequence.toString(36)}`;
+}
+function normalizeWriterLockTarget(target) {
+  return target.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "writer-lock";
+}
+function buildWriterLockPath(rootPath, target) {
+  return path.join(rootPath, ".runtime", "locks", `${normalizeWriterLockTarget(target)}.lock.json`);
+}
+function buildWriterLockRecord(params) {
+  const now = params.now ?? Date.now();
+  return {
+    schemaVersion: HAPPY_ORG_WRITER_LOCK_SCHEMA_VERSION,
+    lockId: nextWriterLockId(),
+    target: params.target,
+    holderType: "cli-writer",
+    holderId: params.holderId,
+    requestId: params.requestId,
+    pid: process.pid,
+    acquiredAt: now,
+    renewedAt: now,
+    expiresAt: now + WRITER_LOCK_LEASE_DURATION_SECONDS * 1e3,
+    leaseDurationSeconds: WRITER_LOCK_LEASE_DURATION_SECONDS,
+    renewBeforeSeconds: WRITER_LOCK_RENEW_BEFORE_SECONDS,
+    ceoTakeoverAfterSeconds: WRITER_LOCK_CEO_TAKEOVER_AFTER_SECONDS,
+    takeoverOf: params.takeoverOf ? {
+      lockId: params.takeoverOf.lockId,
+      holderId: params.takeoverOf.holderId,
+      requestId: params.takeoverOf.requestId,
+      renewedAt: params.takeoverOf.renewedAt
+    } : null
+  };
+}
+function getWriterLockAgeMs(lock, now) {
+  return Math.max(now - Math.max(lock.renewedAt, lock.acquiredAt), 0);
+}
+async function removeWriterLockFile(lockPath) {
+  await promises.unlink(lockPath).catch(async () => {
+    await promises.rm(lockPath, { force: true });
+  });
+}
+async function readWriterLockRecord(lockPath) {
+  const payload = await readJson(lockPath);
+  const parsed = WriterLockRecordSchema.safeParse(payload);
+  return parsed.success ? parsed.data : null;
+}
+function isFileExistsError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+function isFileNotFoundError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function getWriterLockTargetsForRequest(request) {
+  if (request.requestType === "replace_goal") {
+    return ["goal"];
+  }
+  if (request.requestType === "upsert_agent") {
+    return [`position-${request.position.positionId}`, "responsibilities"];
+  }
+  if (request.requestType === "create_task") {
+    return ["task-create", "responsibilities"];
+  }
+  return [`task-${request.taskId}`, "responsibilities"];
+}
+function getWriterLockTargetsForTurnReport(taskId) {
+  return [`task-${taskId}`, "responsibilities"];
+}
 async function loadTaskEnvelope(rootPath, taskId) {
   const taskRoot = buildTaskRoot(rootPath, taskId);
   const task = await readEnvelope(path.join(taskRoot, "TASK.json"), TaskEnvelopeSchema);
@@ -1883,15 +2065,52 @@ async function nextTaskId(rootPath) {
   const nextNumber = taskIds.map((taskId) => Number.parseInt(taskId.replace(/^T-/, ""), 10)).filter((value) => Number.isFinite(value)).reduce((max, value) => Math.max(max, value), 0) + 1;
   return `T-${String(nextNumber).padStart(3, "0")}`;
 }
-async function listPositionEnvelopes(rootPath) {
+async function listPositionEntries(rootPath) {
   try {
     const entries = await promises.readdir(path.join(rootPath, "positions"), { withFileTypes: true });
-    const envelopes = await Promise.all(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => readEnvelope(path.join(rootPath, "positions", entry.name), PositionEnvelopeSchema)));
-    return envelopes.filter((entry) => entry !== null);
+    const positionEntries = await Promise.all(entries.map(async (entry) => {
+      if (entry.isDirectory()) {
+        const positionRoot = path.join(rootPath, "positions", entry.name);
+        const position = await readEnvelope(path.join(positionRoot, "POSITION.json"), PositionEnvelopeSchema);
+        if (!position) {
+          return null;
+        }
+        const workspace = await readEnvelope(path.join(positionRoot, "WORKSPACE.json"), WorkspaceEnvelopeSchema);
+        return {
+          position,
+          workspace,
+          source: "directory"
+        };
+      }
+      if (entry.isFile() && entry.name.endsWith(".json")) {
+        const position = await readEnvelope(path.join(rootPath, "positions", entry.name), PositionEnvelopeSchema);
+        if (!position) {
+          return null;
+        }
+        return {
+          position,
+          workspace: null,
+          source: "legacy-file"
+        };
+      }
+      return null;
+    }));
+    const deduped = /* @__PURE__ */ new Map();
+    for (const entry of positionEntries.filter((value) => value !== null)) {
+      const key = entry.position.value.positionId;
+      const existing = deduped.get(key) ?? null;
+      if (!existing || existing.source === "legacy-file" && entry.source === "directory") {
+        deduped.set(key, entry);
+      }
+    }
+    return [...deduped.values()];
   } catch {
     return [];
   }
 }
+async function listPositionEnvelopes(rootPath) {
+  return (await listPositionEntries(rootPath)).map((entry) => entry.position);
+}
 async function readResponsibilities(rootPath) {
   return await readEnvelope(path.join(rootPath, "RESPONSIBILITIES.json"), ResponsibilityEnvelopeSchema);
 }
@@ -1924,16 +2143,18 @@ async function rebuildResponsibilities(rootPath) {
   const existing = await readResponsibilities(rootPath);
   const previousRevision = existing?.revision ?? 0;
   const responsibilities = positions.map((position) => {
-    const activeTask = normalizedTasks.filter((task) => task.ownerAgentId === position.value.agentId && task.status !== "done" && task.status !== "terminated").sort((left, right) => right.updatedAt - left.updatedAt)[0] ?? null;
+    const responsibilityId = position.value.responsibilityIds[0] ?? buildResponsibilityId(position.value.slug);
+    const activeTask = normalizedTasks.filter((task) => task.status !== "done" && task.status !== "terminated").filter((task) => task.responsibilityId === responsibilityId || (position.value.agentId ? task.ownerAgentId === position.value.agentId : false)).sort((left, right) => right.updatedAt - left.updatedAt)[0] ?? null;
     return {
-      responsibilityId: buildResponsibilityId(position.value.slug),
-      title: `${position.value.agentName} responsibility`,
+      responsibilityId,
+      title: position.value.label || position.value.agentName || `${position.value.slug} responsibility`,
       summary: activeTask?.summary ?? null,
-      positionId: buildPositionId(position.value.slug),
-      participantType: "agent",
-      status: activeTask ? "in_progress" : "assigned",
-      memberAgentId: position.value.agentId,
-      memberName: position.value.agentName,
+      positionId: position.value.positionId,
+      participantType: position.value.agentId ? "agent" : "vacancy",
+      status: position.value.agentId ? activeTask ? "in_progress" : "assigned" : "vacancy",
+      memberAgentId: position.value.agentId ?? null,
+      memberName: position.value.agentName ?? null,
+      role: position.value.role ?? null,
       activeTaskId: activeTask?.taskId ?? null,
       createdAt: position.value.createdAt,
       updatedAt: Math.max(position.value.updatedAt, activeTask?.updatedAt ?? 0)
@@ -2004,12 +2225,104 @@ async function applyReplaceGoalRequest(rootPath, request) {
     message: "goal updated"
   };
 }
+async function applyUpsertAgentRequest(rootPath, request) {
+  const positionEntries = await listPositionEntries(rootPath);
+  const existingPosition = positionEntries.find((entry) => entry.position.value.positionId === request.position.positionId || entry.position.value.slug === request.position.slug || entry.position.value.agentId === request.agent.id) ?? null;
+  if (request.expectedRevision !== null && existingPosition?.position.revision !== request.expectedRevision) {
+    const message = existingPosition ? `Position revision mismatch: expected ${request.expectedRevision}, got ${existingPosition.position.revision}` : `Position ${request.position.positionId} not found for expected revision ${request.expectedRevision}`;
+    await updateRequestRecord(rootPath, request, {
+      requestState: "recovery_required",
+      processedAt: Date.now(),
+      resultMessage: message
+    });
+    return {
+      outcome: "recovery_required",
+      requestId: request.requestId,
+      taskId: null,
+      message
+    };
+  }
+  const positionRoot = buildPositionRoot(rootPath, request.position.slug);
+  const now = Date.now();
+  const positionValue = {
+    positionId: request.position.positionId,
+    slug: request.position.slug,
+    label: request.position.label,
+    role: request.position.role ?? request.agent.role,
+    workingDirectoryRelativePath: normalizeRelativePath(
+      request.position.workingDirectoryRelativePath ?? request.agent.workingDirectoryRelativePath
+    ),
+    agentId: request.position.agentId ?? request.agent.id,
+    agentName: request.position.agentName ?? request.agent.name,
+    supervisorAgentId: request.position.supervisorAgentId ?? request.agent.supervisorAgentId,
+    responsibilityIds: request.position.responsibilityIds.length > 0 ? request.position.responsibilityIds : [buildResponsibilityId(request.position.slug)],
+    occupancyStatus: normalizeOccupancyStatus(request.position.occupancyStatus),
+    truthPath: `positions/${request.position.slug}/POSITION.json`,
+    createdAt: request.position.createdAt,
+    updatedAt: request.agent.updatedAt
+  };
+  const existingWorkspace = existingPosition?.workspace ?? null;
+  const workspaceValue = {
+    positionId: request.position.positionId,
+    slug: request.position.slug,
+    relativePath: normalizeRelativePath(
+      request.position.workingDirectoryRelativePath ?? request.agent.workingDirectoryRelativePath
+    ),
+    updatedAt: request.agent.updatedAt
+  };
+  const runtimeValue = {
+    agentId: request.agent.id,
+    slug: request.agent.slug,
+    role: request.agent.role,
+    sessionId: request.agent.sessionId,
+    sessionTitle: request.agent.sessionTitle,
+    runtimePath: request.agent.runtimePath,
+    assignedWorkingDirectoryRelativePath: workspaceValue.relativePath,
+    assignedWorkingDirectoryPath: resolveRelativePath(rootPath, workspaceValue.relativePath),
+    machineId: request.agent.machineId,
+    backend: request.agent.backend,
+    updatedAt: request.agent.updatedAt
+  };
+  await ensureDir(positionRoot);
+  await writeEnvelope(path.join(positionRoot, "POSITION.json"), {
+    schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
+    revision: existingPosition && JSON.stringify(existingPosition.position.value) === JSON.stringify(positionValue) ? existingPosition.position.revision : (existingPosition?.position.revision ?? 0) + 1,
+    updatedAt: now,
+    updatedBy: request.agent.id,
+    value: positionValue
+  });
+  await writeEnvelope(path.join(positionRoot, "WORKSPACE.json"), {
+    schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
+    revision: existingWorkspace && JSON.stringify(existingWorkspace.value) === JSON.stringify(workspaceValue) ? existingWorkspace.revision : (existingWorkspace?.revision ?? 0) + 1,
+    updatedAt: now,
+    updatedBy: request.agent.id,
+    value: workspaceValue
+  });
+  await writeJson(path.join(rootPath, ".runtime", "agents", `${request.agent.slug}.json`), runtimeValue);
+  if (existingPosition?.source === "legacy-file") {
+    await promises.rm(path.join(rootPath, "positions", `${existingPosition.position.value.positionId}.json`), { force: true });
+  }
+  await rebuildResponsibilities(rootPath);
+  await updateRequestRecord(rootPath, request, {
+    requestState: "applied",
+    processedAt: now,
+    resultMessage: `upserted ${request.agent.id}`
+  });
+  return {
+    outcome: "applied",
+    requestId: request.requestId,
+    taskId: null,
+    message: `upserted ${request.agent.id}`
+  };
+}
 async function applyCreateTaskRequest(rootPath, request) {
   const taskId = await nextTaskId(rootPath);
   const taskRoot = buildTaskRoot(rootPath, taskId);
   const createdAt = Date.now();
   const title = request.title.trim();
   const position = (await listPositionEnvelopes(rootPath)).find((entry) => entry.value.agentId === request.ownerAgentId) ?? null;
+  const responsibilityId = position?.value.responsibilityIds[0] ?? (position ? buildResponsibilityId(position.value.slug) : null);
+  const responsibilityLabel = position?.value.label ?? `${request.ownerName} responsibility`;
   const taskValue = {
     taskId,
     slug: toTaskSlug(taskId, title),
@@ -2017,8 +2330,8 @@ async function applyCreateTaskRequest(rootPath, request) {
     ownerAgentId: request.ownerAgentId,
     ownerName: request.ownerName,
     ownerSessionId: request.ownerSessionId,
-    responsibilityId: position ? buildResponsibilityId(position.value.slug) : null,
-    responsibilityLabel: position ? `${position.value.agentName} responsibility` : `${request.ownerName} responsibility`,
+    responsibilityId,
+    responsibilityLabel,
     activeOwnerAgentId: null,
     hasActiveOwner: false,
     path: request.path,
@@ -2236,19 +2549,127 @@ async function applyUpdateTaskRequest(rootPath, request) {
     message: `updated ${request.taskId}`
   };
 }
-async function acquireWriterLock(rootPath) {
-  const lockPath = path.join(rootPath, ".runtime", "writer.lock.json");
+async function renewSingleWriterLock(lockPath, lockId) {
+  const existing = await readWriterLockRecord(lockPath);
+  if (!existing || existing.lockId !== lockId) {
+    return;
+  }
+  const now = Date.now();
+  await writeJson(lockPath, {
+    ...existing,
+    renewedAt: now,
+    expiresAt: now + WRITER_LOCK_LEASE_DURATION_SECONDS * 1e3
+  });
+}
+async function acquireSingleWriterLock(params) {
+  const lockPath = buildWriterLockPath(params.rootPath, params.target);
   await ensureDir(path.dirname(lockPath));
-  const handle = await promises.open(lockPath, "wx");
-  await handle.writeFile(JSON.stringify({
-    acquiredAt: Date.now(),
-    pid: process.pid
-  }, null, 2), "utf8");
-  await handle.close();
-  return async () => {
-    await promises.unlink(lockPath).catch(async () => {
-      await promises.rm(lockPath, { force: true });
+  let takeoverOf = null;
+  while (true) {
+    const now = Date.now();
+    const record = buildWriterLockRecord({
+      target: params.target,
+      holderId: params.holderId,
+      requestId: params.requestId,
+      takeoverOf,
+      now
     });
+    try {
+      const handle = await promises.open(lockPath, "wx");
+      await handle.writeFile(JSON.stringify(record, null, 2), "utf8");
+      await handle.close();
+      const renewTimer = setInterval(() => {
+        void renewSingleWriterLock(lockPath, record.lockId);
+      }, WRITER_LOCK_RENEW_INTERVAL_MS);
+      renewTimer.unref?.();
+      return async () => {
+        clearInterval(renewTimer);
+        const existing = await readWriterLockRecord(lockPath);
+        if (!existing || existing.lockId !== record.lockId) {
+          return;
+        }
+        await removeWriterLockFile(lockPath);
+      };
+    } catch (error) {
+      if (!isFileExistsError(error)) {
+        throw error;
+      }
+      const existing = await readWriterLockRecord(lockPath);
+      if (!existing) {
+        try {
+          const info = await promises.stat(lockPath);
+          const ageMs2 = Math.max(now - info.mtimeMs, 0);
+          if (ageMs2 >= WRITER_LOCK_CEO_TAKEOVER_AFTER_SECONDS * 1e3) {
+            await removeWriterLockFile(lockPath);
+            takeoverOf = null;
+            continue;
+          }
+        } catch (statError) {
+          if (isFileNotFoundError(statError)) {
+            takeoverOf = null;
+            continue;
+          }
+        }
+        throw new WriterLockConflictError(
+          "invalid",
+          params.target,
+          `Lock ${params.target} exists but is unreadable; mark recovery before retrying.`
+        );
+      }
+      const ageMs = getWriterLockAgeMs(existing, now);
+      if (ageMs >= WRITER_LOCK_CEO_TAKEOVER_AFTER_SECONDS * 1e3) {
+        await removeWriterLockFile(lockPath);
+        takeoverOf = existing;
+        continue;
+      }
+      if (ageMs >= WRITER_LOCK_LEASE_DURATION_SECONDS * 1e3) {
+        throw new WriterLockConflictError(
+          "stale",
+          params.target,
+          `Lock ${params.target} is stale for ${Math.floor(ageMs / 1e3)}s and requires CEO recovery before takeover.`,
+          existing
+        );
+      }
+      throw new WriterLockConflictError(
+        "active",
+        params.target,
+        `Lock ${params.target} is still held by ${existing.holderId} for request ${existing.requestId}.`,
+        existing
+      );
+    }
+  }
+}
+async function acquireWriterLocks(params) {
+  const holderId = `cli-writer:${process.pid}`;
+  const releaseSteps = [];
+  const orderedTargets = [...new Set(params.targets)].sort();
+  try {
+    for (const target of orderedTargets) {
+      releaseSteps.push(await acquireSingleWriterLock({
+        rootPath: params.rootPath,
+        target,
+        holderId,
+        requestId: params.requestId
+      }));
+    }
+  } catch (error) {
+    while (releaseSteps.length > 0) {
+      const release = releaseSteps.pop();
+      if (!release) {
+        continue;
+      }
+      await release();
+    }
+    throw error;
+  }
+  return async () => {
+    while (releaseSteps.length > 0) {
+      const release = releaseSteps.pop();
+      if (!release) {
+        continue;
+      }
+      await release();
+    }
   };
 }
 async function processSingleRequest(rootPath, request) {
@@ -2261,11 +2682,38 @@ async function processSingleRequest(rootPath, request) {
       message: request.resultMessage
     };
   }
-  const release = await acquireWriterLock(rootPath);
+  let lockConflictMessage = null;
+  const release = await acquireWriterLocks({
+    rootPath,
+    targets: getWriterLockTargetsForRequest(request),
+    requestId: request.requestId
+  }).catch(async (error) => {
+    if (error instanceof WriterLockConflictError) {
+      lockConflictMessage = error.message;
+      await updateRequestRecord(rootPath, request, {
+        requestState: "recovery_required",
+        processedAt: Date.now(),
+        resultMessage: error.message
+      });
+      return null;
+    }
+    throw error;
+  });
+  if (!release) {
+    return {
+      outcome: "recovery_required",
+      requestId: request.requestId,
+      taskId: "taskId" in request ? request.taskId : null,
+      message: lockConflictMessage
+    };
+  }
   try {
     if (request.requestType === "replace_goal") {
       return await applyReplaceGoalRequest(rootPath, request);
     }
+    if (request.requestType === "upsert_agent") {
+      return await applyUpsertAgentRequest(rootPath, request);
+    }
     if (request.requestType === "create_task") {
       return await applyCreateTaskRequest(rootPath, request);
     }
@@ -2306,99 +2754,125 @@ function nextStatusFromTurnReport(report) {
   return "active";
 }
 async function recordHappyOrgTurnReport(options) {
-  const bundle = await loadTaskEnvelope(options.rootPath, options.report.taskId);
-  if (!bundle) {
+  const requestId = `turn-report:${options.report.taskId}`;
+  let lockConflictMessage = null;
+  const release = await acquireWriterLocks({
+    rootPath: options.rootPath,
+    targets: getWriterLockTargetsForTurnReport(options.report.taskId),
+    requestId
+  }).catch((error) => {
+    if (error instanceof WriterLockConflictError) {
+      lockConflictMessage = error.message;
+      return null;
+    }
+    throw error;
+  });
+  if (!release) {
     return {
       outcome: "recovery_required",
-      requestId: `turn-report:${options.report.taskId}`,
+      requestId,
       taskId: options.report.taskId,
-      message: `Task ${options.report.taskId} not found`
+      message: lockConflictMessage ?? `Turn report blocked by writer lock for ${options.report.taskId}`
     };
   }
-  const now = Date.now();
-  const nextStatus = nextStatusFromTurnReport(options.report);
-  const nextTaskValue = {
-    ...bundle.task.value,
-    status: nextStatus,
-    summary: options.report.summary,
-    resultSummary: options.report.turnStatus === "task_complete" ? options.report.summary : bundle.task.value.resultSummary,
-    blocker: nextStatus === "blocked" ? options.report.summary || options.report.blockerCode : null,
-    decisionNeeded: nextStatus === "waiting_decision" ? options.report.decisionNeeded ?? options.report.summary : null,
-    updatedAt: now,
-    lastUpdatedBy: options.report.memberAgentId,
-    activeOwnerAgentId: options.report.memberAgentId,
-    hasActiveOwner: nextStatus === "active",
-    path: options.report.targetArtifact ?? bundle.task.value.path,
-    portablePath: normalizePortablePath(options.report.targetArtifact ?? bundle.task.value.path)
-  };
-  await writeEnvelope(path.join(buildTaskRoot(options.rootPath, options.report.taskId), "TASK.json"), {
-    ...bundle.task,
-    revision: bundle.task.revision + 1,
-    updatedAt: now,
-    updatedBy: options.report.memberAgentId,
-    value: nextTaskValue
-  });
-  await writeEnvelope(path.join(buildTaskRoot(options.rootPath, options.report.taskId), "WORKFLOW.json"), {
-    schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
-    revision: (bundle.workflow?.revision ?? 0) + 1,
-    updatedAt: now,
-    updatedBy: options.report.memberAgentId,
-    value: {
-      taskId: options.report.taskId,
+  try {
+    const bundle = await loadTaskEnvelope(options.rootPath, options.report.taskId);
+    if (!bundle) {
+      return {
+        outcome: "recovery_required",
+        requestId,
+        taskId: options.report.taskId,
+        message: `Task ${options.report.taskId} not found`
+      };
+    }
+    const now = Date.now();
+    const nextStatus = nextStatusFromTurnReport(options.report);
+    const nextTaskValue = {
+      ...bundle.task.value,
       status: nextStatus,
       summary: options.report.summary,
-      blocker: nextStatus === "blocked" ? options.report.blockerCode ?? options.report.summary : null,
+      resultSummary: options.report.turnStatus === "task_complete" ? options.report.summary : bundle.task.value.resultSummary,
+      blocker: nextStatus === "blocked" ? options.report.summary || options.report.blockerCode : null,
       decisionNeeded: nextStatus === "waiting_decision" ? options.report.decisionNeeded ?? options.report.summary : null,
-      adviceRoute: null,
-      adviceSummary: null,
-      lastRequestId: null,
       updatedAt: now,
-      updatedBy: options.report.memberAgentId
-    }
-  });
-  await writeEnvelope(path.join(buildTaskRoot(options.rootPath, options.report.taskId), "RESULT.json"), {
-    schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
-    revision: (bundle.result?.revision ?? 0) + 1,
-    updatedAt: now,
-    updatedBy: options.report.memberAgentId,
-    value: {
-      taskId: options.report.taskId,
-      resultSummary: options.report.turnStatus === "task_complete" ? options.report.summary : bundle.result?.value.resultSummary ?? bundle.task.value.resultSummary,
-      reviewSummary: bundle.result?.value.reviewSummary ?? null,
-      assetCaptureStatus: bundle.result?.value.assetCaptureStatus ?? null,
-      assetCaptureSummary: bundle.result?.value.assetCaptureSummary ?? null,
-      assetReference: options.report.targetArtifact ?? bundle.result?.value.assetReference ?? null,
-      closedAt: nextStatus === "waiting_close" ? now : bundle.result?.value.closedAt ?? null,
+      lastUpdatedBy: options.report.memberAgentId,
+      activeOwnerAgentId: options.report.memberAgentId,
+      hasActiveOwner: nextStatus === "active",
+      path: options.report.targetArtifact ?? bundle.task.value.path,
+      portablePath: normalizePortablePath(options.report.targetArtifact ?? bundle.task.value.path)
+    };
+    const taskRoot = buildTaskRoot(options.rootPath, options.report.taskId);
+    await writeEnvelope(path.join(taskRoot, "TASK.json"), {
+      ...bundle.task,
+      revision: bundle.task.revision + 1,
       updatedAt: now,
-      updatedBy: options.report.memberAgentId
-    }
-  });
-  await writeEnvelope(path.join(buildTaskRoot(options.rootPath, options.report.taskId), "LOG.json"), {
-    schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
-    revision: (bundle.log?.revision ?? 0) + 1,
-    updatedAt: now,
-    updatedBy: options.report.memberAgentId,
-    value: {
+      updatedBy: options.report.memberAgentId,
+      value: nextTaskValue
+    });
+    await writeEnvelope(path.join(taskRoot, "WORKFLOW.json"), {
+      schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
+      revision: (bundle.workflow?.revision ?? 0) + 1,
+      updatedAt: now,
+      updatedBy: options.report.memberAgentId,
+      value: {
+        taskId: options.report.taskId,
+        status: nextStatus,
+        summary: options.report.summary,
+        blocker: nextStatus === "blocked" ? options.report.blockerCode ?? options.report.summary : null,
+        decisionNeeded: nextStatus === "waiting_decision" ? options.report.decisionNeeded ?? options.report.summary : null,
+        adviceRoute: null,
+        adviceSummary: null,
+        lastRequestId: null,
+        updatedAt: now,
+        updatedBy: options.report.memberAgentId
+      }
+    });
+    await writeEnvelope(path.join(taskRoot, "RESULT.json"), {
+      schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
+      revision: (bundle.result?.revision ?? 0) + 1,
+      updatedAt: now,
+      updatedBy: options.report.memberAgentId,
+      value: {
+        taskId: options.report.taskId,
+        resultSummary: options.report.turnStatus === "task_complete" ? options.report.summary : bundle.result?.value.resultSummary ?? bundle.task.value.resultSummary,
+        reviewSummary: bundle.result?.value.reviewSummary ?? null,
+        assetCaptureStatus: bundle.result?.value.assetCaptureStatus ?? null,
+        assetCaptureSummary: bundle.result?.value.assetCaptureSummary ?? null,
+        assetReference: options.report.targetArtifact ?? bundle.result?.value.assetReference ?? null,
+        closedAt: nextStatus === "waiting_close" ? now : bundle.result?.value.closedAt ?? null,
+        updatedAt: now,
+        updatedBy: options.report.memberAgentId
+      }
+    });
+    await writeEnvelope(path.join(taskRoot, "LOG.json"), {
+      schemaVersion: HAPPY_ORG_LOCAL_REPO_SCHEMA_VERSION,
+      revision: (bundle.log?.revision ?? 0) + 1,
+      updatedAt: now,
+      updatedBy: options.report.memberAgentId,
+      value: {
+        taskId: options.report.taskId,
+        entries: [
+          ...bundle.log?.value.entries ?? [],
+          buildTaskLogEntry(
+            "turn_report",
+            `Recorded ${options.report.turnStatus} from ${options.report.memberAgentId}`,
+            options.report.summary,
+            options.report.memberAgentId,
+            now
+          )
+        ]
+      }
+    });
+    await rebuildResponsibilities(options.rootPath);
+    return {
+      outcome: "applied",
+      requestId,
       taskId: options.report.taskId,
-      entries: [
-        ...bundle.log?.value.entries ?? [],
-        buildTaskLogEntry(
-          "turn_report",
-          `Recorded ${options.report.turnStatus} from ${options.report.memberAgentId}`,
-          options.report.summary,
-          options.report.memberAgentId,
-          now
-        )
-      ]
-    }
-  });
-  await rebuildResponsibilities(options.rootPath);
-  return {
-    outcome: "applied",
-    requestId: `turn-report:${options.report.taskId}`,
-    taskId: options.report.taskId,
-    message: `recorded turn report for ${options.report.taskId}`
-  };
+      message: `recorded turn report for ${options.report.taskId}`
+    };
+  } finally {
+    await release();
+  }
 }
 
 function buildSessionRuntimeIndex(metadata) {
@@ -3346,6 +3820,9 @@ const PROTOCOL_V3_CHANGES_PAGE_LIMIT = 200;
 const PROTOCOL_V3_CAPABILITIES_WAIT_MS = 250;
 const COMMITTED_SESSION_WRITE_ACK_TIMEOUT_MS = 5e3;
 const RELIABLE_SESSION_MESSAGE_RETRY_DELAY_MS = 250;
+const LEGACY_CONTROL_ACK_HEADER$1 = Object.freeze({
+  "x-happy-legacy-control-ack": "happy-org-1.7.3-legacy-write"
+});
 function normalizeHappyOrgOptionalText(value) {
   if (typeof value !== "string") {
     return null;
@@ -3383,6 +3860,12 @@ function buildHappyOrgTurnReportSubmissionKey(messageId, report) {
     report.summary.trim()
   ].join(":");
 }
+function withLegacyControlAck$1(headers) {
+  return {
+    ...headers ?? {},
+    ...LEGACY_CONTROL_ACK_HEADER$1
+  };
+}
 function parseHappyOrgFallbackEnvelope(rawEnvelope) {
   try {
     const parsed = JSON.parse(rawEnvelope);
@@ -3403,7 +3886,9 @@ function parseHappyOrgFallbackEnvelope(rawEnvelope) {
       replyTo,
       organizationId: typeof parsed.organization_id === "string" ? parsed.organization_id.trim() : null,
       memberAgentId: typeof parsed.member_agent_id === "string" ? parsed.member_agent_id.trim() : null,
-      supervisorAgentId: typeof parsed.supervisor_agent_id === "string" ? parsed.supervisor_agent_id.trim() : null
+      supervisorAgentId: typeof parsed.supervisor_agent_id === "string" ? parsed.supervisor_agent_id.trim() : null,
+      positionId: typeof parsed.position_id === "string" ? parsed.position_id.trim() : null,
+      responsibilityId: typeof parsed.responsibility_id === "string" ? parsed.responsibility_id.trim() : null
     };
   } catch {
     return null;
@@ -3420,13 +3905,17 @@ function buildHappyOrgFallbackUserMessage(rawEnvelope) {
         taskId: envelope.taskId,
         organizationId: envelope.organizationId,
         memberAgentId: envelope.memberAgentId,
-        supervisorAgentId: envelope.supervisorAgentId
+        supervisorAgentId: envelope.supervisorAgentId,
+        ...envelope.positionId ? { positionId: envelope.positionId } : {},
+        ...envelope.responsibilityId ? { responsibilityId: envelope.responsibilityId } : {}
       }
     } : {},
     replyContext: {
       dispatchId: envelope.dispatchId,
       scope: envelope.scope,
-      replyTo: envelope.replyTo
+      replyTo: envelope.replyTo,
+      ...envelope.positionId ? { positionId: envelope.positionId } : {},
+      ...envelope.responsibilityId ? { responsibilityId: envelope.responsibilityId } : {}
     }
   };
   return {
@@ -4215,10 +4704,10 @@ class ApiSessionClient extends node_events.EventEmitter {
           url,
           body: payload,
           signRequest: true,
-          headers: {
+          headers: withLegacyControlAck$1({
             "Content-Type": "application/json",
             "x-happy-organization-id": report.organizationId
-          }
+          })
         }),
         timeout: 1e4
       });
@@ -4318,10 +4807,10 @@ class ApiSessionClient extends node_events.EventEmitter {
           url,
           body: payload,
           signRequest: true,
-          headers: {
+          headers: withLegacyControlAck$1({
             "Content-Type": "application/json",
             "x-happy-organization-id": candidate.organizationId
-          }
+          })
         }),
         timeout: 1e4
       });
@@ -5560,6 +6049,15 @@ async function deriveKey(master, usage, path) {
 }
 
 const SESSION_DATA_KEY_USAGE = "Happy Session Data Key";
+const LEGACY_CONTROL_ACK_HEADER = Object.freeze({
+  "x-happy-legacy-control-ack": "happy-org-1.7.3-legacy-write"
+});
+function withLegacyControlAck(headers) {
+  return {
+    ...headers ?? {},
+    ...LEGACY_CONTROL_ACK_HEADER
+  };
+}
 class ApiClient {
   static async create(credential) {
     return new ApiClient(credential);
@@ -5656,9 +6154,11 @@ class ApiClient {
         allowed_paths: opts.allowedPaths,
         forbidden_paths: opts.forbiddenPaths ?? [],
         cross_scope_policy: "ask-first",
+        position_id: opts.positionId ?? null,
+        responsibility_id: opts.responsibilityId ?? null,
         note: opts.note ?? null
       },
-      headers: { "x-happy-organization-id": opts.organizationId },
+      headers: withLegacyControlAck({ "x-happy-organization-id": opts.organizationId }),
       timeout: 1e4
     });
     return response.data.receipt;
@@ -5684,7 +6184,7 @@ class ApiClient {
         status: opts.status,
         note: opts.note ?? null
       },
-      headers: { "x-happy-organization-id": opts.organizationId },
+      headers: withLegacyControlAck({ "x-happy-organization-id": opts.organizationId }),
       timeout: 1e4
     });
     return response.data.receipt;