docs: add HumanLayer research note

docs/superpowers/plans/2026-09-18-humanlayer-research-note.md

@@ -0,0 +1,27 @@
+# HumanLayer Research Note Implementation Plan
+
+> **For agentic workers:** Execute this plan inline with validation checkpoints.
+
+**Goal:** Add and publish a sourced research note on HumanLayer's externalized agent sessions and disposable execution model.
+
+**Architecture:** Describe the HumanLayer API/control plane, local/remote daemons, tasks, sessions, artifacts, diffs, worktrees, and streamed events. Separate durable collaboration state from host-bound execution context, then map the thesis to CF's durable state, disposable Diego processes, identity, and event streams.
+
+**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI.
+
+---
+
+### Task 1: Write `research/humanlayer.md`
+
+- [ ] Add frontmatter with title `HumanLayer: Externalized Agent Sessions and Disposable Execution`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[durable-execution, orchestration, observability-governance, ecosystem-survey]`, `cf_areas: [capi, diego, loggregator]`, `status: draft`, ratings, and HumanLayer repository/website/remote-daemon sources.
+- [ ] Describe HumanLayer as a multiplayer coding-agent workspace with API, web/desktop/mobile interfaces, local/remote daemons, tasks, sessions, artifacts, plans, diffs, and worktrees.
+- [ ] Explain the stateless-at-the-process-layer thesis: collaboration/session state and events are externalized, while daemons and agent processes can be restarted or replaced.
+- [ ] Distinguish documented API event streaming and daemon reconnection from unproven live in-memory process migration between containers.
+- [ ] Cover host-bound capabilities: code, tools, credentials, private services, worktrees, filesystem, and persistent daemon authentication storage.
+- [ ] Assess CF relevance for CAPI/Diego, durable state stores, disposable processes, session ownership, identity, workspace persistence, and Loggregator.
+- [ ] Add open questions about process migration, state completeness, worktree portability, credential rehydration, event ordering, and failure recovery.
+
+### Task 2: Validate and publish
+
+- [ ] Run `devbox run validate`, `devbox run test`, and `git diff --check`.
+- [ ] Stage only the note and approved spec/plan, commit `docs: add HumanLayer research note`, push `research/humanlayer`, and open a checklist-complete PR targeting `main`.
+- [ ] Verify PR metadata and CI with `gh pr view`.

docs/superpowers/specs/2026-09-18-humanlayer-research-note-design.md

@@ -0,0 +1,31 @@
+# HumanLayer Research Note Design
+
+## Goal
+
+Add a sourced research note on HumanLayer's multiplayer agent workspace and its support for
+stateless-at-the-process-layer agent execution.
+
+## Scope
+
+The note will describe HumanLayer's API/control-plane and local or remote daemon model, task
+grouping, sessions, artifacts, plans, diffs, worktrees, event streaming, and multi-user access.
+It will assess the thesis that durable collaboration/session state can be externalized while
+agent processes and hosts remain replaceable.
+
+The note will explicitly distinguish documented daemon reconnection and externalized events from
+unproven live process migration between containers. It will discuss host-bound capabilities such
+as code, credentials, tools, private network access, worktrees, and persistent daemon storage.
+Cloud Foundry analysis will cover CAPI/Diego, durable state stores, disposable processes, identity,
+workspaces, and Loggregator.
+
+## Structure and evidence
+
+Create `research/humanlayer.md` with the required four sections and frontmatter. Use the
+HumanLayer repository, current website, remote daemon guide, remote daemon architecture docs,
+and related public documentation. Clearly distinguish current product claims from architectural
+inference.
+
+## Validation
+
+Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on
+`research/humanlayer`, push, and open a PR targeting `main` without unrelated artifacts.

research/humanlayer.md

@@ -0,0 +1,111 @@
+---
+title: "HumanLayer: Externalized Agent Sessions and Disposable Execution"
+author: Ruben Koster (@rkoster)
+date: 2026-09-18
+tags: [durable-execution, orchestration, observability-governance, ecosystem-survey]
+cf_areas: [capi, diego, loggregator]
+status: draft
+ratings:
+  platform-impact:
+    value: 84
+    note: "HumanLayer illustrates a control plane where agent collaboration state is externalized while execution hosts remain replaceable."
+  maturity:
+    value: 62
+    note: "The current product has local and remote daemons, multi-client collaboration, and documented persistence behavior, while the public architecture does not establish live process migration."
+  novelty:
+    value: 78
+    note: "The combination of multiplayer task/artifact collaboration, full session visibility, remote daemons, and host-independent control is a distinctive platform pattern."
+  actionability:
+    value: 80
+    note: "The architecture gives CF concrete questions about durable sessions, disposable processes, worktrees, identity, event streams, and host-bound capabilities."
+sources:
+  - https://github.com/humanlayer/humanlayer
+  - https://humanlayer.com
+  - https://docs.humanlayer.com/guide/remote-daemons
+  - https://docs.humanlayer.com/explanation/remote-daemons
+---
+
+## Summary
+
+HumanLayer is a multiplayer coding-agent workspace and cloud control plane that brings agent
+sessions, plans, artifacts, worktrees, and code diffs together for teams. Its API coordinates
+local or remote daemons, while daemons launch the actual coding-agent sessions on hosts with
+the required code, tools, credentials, and private-network access. This supports a thesis of
+agents becoming stateless at the process layer: collaboration and session events live outside
+the process, while the daemon or process can be restarted or replaced, although public docs do
+not establish migration of a live in-memory process between arbitrary containers.
+
+## Key findings
+
+- **HumanLayer separates control plane from execution host.** Web, desktop, and mobile clients
+  request work through an API. A connected local or remote daemon receives the work, launches
+  Claude or Codex sessions, and sends session events back through the API to each interface.
+- **Tasks group the durable collaboration surface.** Tasks group sessions, artifacts, plans,
+  designs, diffs, and worktrees so multiple humans and agents can collaborate on one unit of
+  work. This external object model is more durable and shareable than the memory of a single
+  agent process.
+- **The product exposes full session visibility.** The website describes visibility into
+  thinking messages, subagent tool calls, code changes, and real-time topology across daemons
+  and clients. The event stream gives clients a way to reconnect to ongoing work without being
+  attached to the agent process's terminal.
+- **Remote daemons move execution, not necessarily process memory.** A remote daemon can run on
+  a cloud VM, workstation, or private-network machine while the user controls sessions through
+  the browser. The host provides access to code, tools, credentials, and private services. The
+  public architecture supports dispatch and event streaming through the API, but does not prove
+  that a live Claude/Codex process can be serialized and resumed in a different container.
+- **Execution context remains host-bound.** Worktrees, filesystem state, installed tools,
+  private network routes, credentials, and agent processes belong to the daemon host. Moving or
+  replacing a process therefore requires either preserving that host context or reconstructing
+  it from external state and repository history.
+- **Authentication persistence is explicit.** Interactive login stores a session under
+  `~/.humanlayer/riptide/`, and the daemon can reuse it after restart or host reboot if the same
+  user and directory remain intact. Containers require persistent storage for those credentials;
+  removing and recreating the container loses them unless the storage is mounted.
+- **The statelessness thesis is layered.** HumanLayer externalizes task metadata, artifacts,
+  plans, diffs, session events, and control-plane access. It does not imply that prompts,
+  in-memory model context, shell state, process trees, or credentials are automatically portable
+  across hosts. The practical model is stateless or replaceable orchestration around a potentially
+  stateful execution environment.
+- **Git is the change-transfer boundary.** The public product centers code diffs and worktrees,
+  while the open repository documents that the older public code is largely deprecated and points
+  to the current product. Git history and artifacts can make work portable even when the original
+  runtime host cannot be reproduced exactly.
+- **HumanLayer is multi-user by design.** Teammates can observe and interact with sessions from
+  different interfaces, comment on artifacts, and send work to agents. That requires identity,
+  access control, event fan-out, and protection for sensitive session content.
+
+## CF relevance
+
+HumanLayer provides a useful reference architecture for Cloud Foundry agents that should not
+depend on one long-lived Diego process. CAPI could own tasks and session metadata, while Diego
+hosts disposable agent processes whose durable state is stored externally. A replacement process
+could rehydrate a task from conversation/event history, repository/worktree state, plans, and
+artifacts rather than requiring the original process memory to survive.
+
+The difficult boundary is completeness of rehydration. CF would need durable session and event
+stores, stable workspace or worktree storage, identity and credential reissuance, session
+ownership/fencing, and a way to reconstruct tool and private-network access. Loggregator could
+stream process, tool, session, and collaboration events, but a durable control-plane history
+would still be needed for reconnecting clients and recovering work after process replacement.
+
+This model could reduce the need for stateful, permanently running agent containers while
+preserving a rich interactive experience. It does not eliminate state; it moves state into
+platform-managed records, repositories, artifacts, durable stores, and host capability
+descriptions. The platform must decide which state is authoritative and how much execution
+context is reproducible before claiming an agent is portable across Diego instances.
+
+## Open questions
+
+- Which parts of an agent session must be externalized for safe rehydration: conversation,
+  model context, tool state, shell state, worktree, environment, artifacts, or all of them?
+- Can a CF agent process be replaced during a turn, or only between explicit event boundaries?
+- How should CAPI and Diego coordinate session ownership, fencing, draining, and recovery to avoid
+  two processes acting on one task simultaneously?
+- How should worktrees, uncommitted files, installed dependencies, credentials, and private
+  network access be reconstructed on a replacement instance?
+- Which user, agent, task, and daemon identities should authorize session access and tool calls?
+- What event ordering, replay, retention, and privacy guarantees should Loggregator and the
+  durable control plane provide?
+- When does externalized state become sufficiently complete that process migration is practical,
+  and when is it more honest to treat a new process as a continuation with a reconstructed
+  context?