Merge pull request 'fix(cli): assign-schedule-type dispatch at top level' (#8) from fix/assign-schedule-type-dispatch into main

`assign-schedule-type` is registered in CommandSurface() as a Group, so
the default branch of main()'s switch picks it up via findGroup() and
hands it to handleGroup. handleGroup then treats args[0] (the agent-id)
as a subcommand name, fails findSubCommand, and errors:

    unknown assign-schedule-type subcommand: <agent-id>

The group has no subcommands — it's a leaf — so the call never reaches
handleAssignScheduleType. Add an explicit top-level case before the
default branch so the leaf bypasses the group dispatcher.

Pre-fix repro:
    $ AGENT_ID=ard hf assign-schedule-type analyst1 standard
    unknown assign-schedule-type subcommand: analyst1

Post-fix:
    $ AGENT_ID=ard CLAW_IDENTIFIER=server-t2 hf assign-schedule-type analyst1 standard
    Assigned schedule type 'standard' to agent 'analyst1'

Surfaced during recruitment workflow Step 5 on prod (sherlock/agent-resource-director).

cmd/hf/main.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/commands"
 	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/help"
@@ -54,6 +55,24 @@ func main() {
 			discordID = filtered[1]
 		}
 		commands.RunUserUpdateDiscordID(filtered[0], discordID, tokenFlag)
+	case "agent":
+		// `hf agent <sub>` — currently only `status` is implemented (wraps
+		// `POST /calendar/agent/status`, identifies caller via
+		// AGENT_ID/CLAW_IDENTIFIER env, no token needed).
+		if len(args) < 2 {
+			output.Error("usage: hf agent status --set <idle|busy|on_call|exhausted|offline>")
+		}
+		switch args[1] {
+		case "status":
+			commands.RunAgentStatus(args[2:])
+		default:
+			output.Errorf("unknown agent subcommand: %s", args[1])
+		}
+	case "assign-schedule-type":
+		// Leaf command (no subcommands) — args are <agent-id> <type-name>.
+		// Must dispatch at top level because handleGroup treats args[0] as
+		// a subcommand name and would error "unknown ... subcommand: <agent-id>".
+		handleAssignScheduleType(args[1:])
 	default:
 		if group, ok := findGroup(args[0]); ok {
 			handleGroup(group, args[1:])
@@ -224,6 +243,12 @@ func handleGroup(group help.Group, args []string) {
 	case "monitor":
 		handleMonitorCommand(sub.Name, remaining)
 		return
+	case "schedule-type":
+		handleScheduleTypeCommand(sub.Name, remaining)
+		return
+	case "assign-schedule-type":
+		handleAssignScheduleType(remaining)
+		return
 	}
 
 	if len(args) > 0 && args[0] == "update-discord-id" {
@@ -286,6 +311,7 @@ func handleUserCommand(subCmd string, args []string) {
 		commands.RunUserGet(filtered[0], tokenFlag)
 	case "create":
 		username, password, email, fullName, discordUserID := "", "", "", "", ""
+		agentID, clawID := "", ""
 		for i := 0; i < len(filtered); i++ {
 			switch filtered[i] {
 			case "--user":
@@ -313,14 +339,54 @@ func handleUserCommand(subCmd string, args []string) {
 					i++
 					discordUserID = filtered[i]
 				}
+			case "--agent-id":
+				if i+1 < len(filtered) {
+					i++
+					agentID = filtered[i]
+				}
+			case "--claw-identifier":
+				if i+1 < len(filtered) {
+					i++
+					clawID = filtered[i]
+				}
 			default:
 				output.Errorf("unknown flag: %s", filtered[i])
 			}
 		}
 		if username == "" {
-			output.Error("usage: hf user create --user <username>")
+			output.Error("usage: hf user create --user <username> [--agent-id <id> --claw-identifier <id>]")
 		}
-		commands.RunUserCreate(username, password, email, fullName, discordUserID, accMgrTokenFlag)
+		commands.RunUserCreate(username, password, email, fullName, discordUserID, agentID, clawID, accMgrTokenFlag)
+	case "bind-agent":
+		// `hf user bind-agent <username> [--agent-id <id>] [--claw-identifier <id>]`
+		// Backfills the agents row for an existing user. Pcexec env
+		// (AGENT_ID + `openclaw config get plugins.harbor-forge.identifier`)
+		// covers the flags when run from a pcexec session.
+		username, agentID, clawID := "", "", ""
+		for i := 0; i < len(filtered); i++ {
+			switch filtered[i] {
+			case "--agent-id":
+				if i+1 < len(filtered) {
+					i++
+					agentID = filtered[i]
+				}
+			case "--claw-identifier":
+				if i+1 < len(filtered) {
+					i++
+					clawID = filtered[i]
+				}
+			default:
+				if username == "" && !strings.HasPrefix(filtered[i], "--") {
+					username = filtered[i]
+				} else {
+					output.Errorf("unknown flag: %s", filtered[i])
+				}
+			}
+		}
+		if username == "" {
+			output.Error("usage: hf user bind-agent <username> [--agent-id <id>] [--claw-identifier <id>]")
+		}
+		commands.RunUserBindAgent(username, agentID, clawID, accMgrTokenFlag)
 	case "update":
 		if len(filtered) < 1 {
 			output.Error("usage: hf user update <username> [--email ...] [--full-name ...] [--pass ...] [--active ...]")
@@ -1138,3 +1204,47 @@ func handleMonitorAPIKeyCommand(args []string, tokenFlag string) {
 		output.Errorf("unknown monitor api-key subcommand: %s", subCmd)
 	}
 }
+
+func handleScheduleTypeCommand(subCmd string, args []string) {
+	tokenFlag := ""
+	var filtered []string
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--token":
+			if i+1 < len(args) {
+				i++
+				tokenFlag = args[i]
+			}
+		default:
+			filtered = append(filtered, args[i])
+		}
+	}
+
+	switch subCmd {
+	case "list":
+		commands.RunScheduleTypeList(tokenFlag)
+	case "create":
+		commands.RunScheduleTypeCreate(filtered, tokenFlag)
+	case "delete":
+		commands.RunScheduleTypeDelete(filtered, tokenFlag)
+	default:
+		output.Errorf("hf schedule-type %s is not implemented yet", subCmd)
+	}
+}
+
+func handleAssignScheduleType(args []string) {
+	tokenFlag := ""
+	var filtered []string
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--token":
+			if i+1 < len(args) {
+				i++
+				tokenFlag = args[i]
+			}
+		default:
+			filtered = append(filtered, args[i])
+		}
+	}
+	commands.RunAssignScheduleType(filtered, tokenFlag)
+}

internal/client/client.go

@@ -19,14 +19,34 @@ type Client struct {
 }
 
 // New creates a Client with the given base URL and optional auth token.
+//
+// The token is sent as Authorization: Bearer when it looks like a JWT
+// (eyJ-prefixed, three dot-separated segments). Anything else is treated as
+// an API key and sent via X-API-Key. This lets call sites that historically
+// passed an api-key as a "token" (e.g. the value returned by passmgr.GetToken
+// in padded-cell mode) authenticate correctly without per-callsite churn.
 func New(baseURL, token string) *Client {
-	return &Client{
+	c := &Client{
 		BaseURL: strings.TrimRight(baseURL, "/"),
-		Token:   token,
 		HTTPClient: &http.Client{
 			Timeout: 30 * time.Second,
 		},
 	}
+	if isLikelyJWT(token) {
+		c.Token = token
+	} else if token != "" {
+		c.APIKey = token
+	}
+	return c
+}
+
+// isLikelyJWT returns true for tokens that look like a JSON Web Token:
+// "eyJ"-prefixed (base64-encoded JSON header opening with `{"`) and exactly
+// two dots separating header.payload.signature. API keys minted by the HF
+// backend are hex (`/users/{id}/apikey` returns a 64-hex-char `key`); fabric
+// keys use a `fak_` prefix. None of those match this shape.
+func isLikelyJWT(token string) bool {
+	return strings.HasPrefix(token, "eyJ") && strings.Count(token, ".") == 2
 }
 
 // NewWithAPIKey creates a Client that authenticates using X-API-Key.

internal/client/client_test.go

@@ -0,0 +1,104 @@
+package client
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestIsLikelyJWT(t *testing.T) {
+	cases := []struct {
+		in   string
+		want bool
+		why  string
+	}{
+		// Real JWT minted by an HS256 signer (header `{"alg":"HS256","typ":"JWT"}`).
+		{"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIn0.signature", true, "valid JWT shape"},
+		// HF backend api-keys are 64-char hex from /users/{id}/apikey.
+		{"f654c3ff0bbc09e6a22294dfbbbff371a4550366849f59de68ddf064742831a0", false, "hex api-key"},
+		// Fabric api-keys carry a fak_ prefix.
+		{"fak_30791357ca11ac2ff963999bf265f6a5f240593eb01c06fc", false, "fabric api-key"},
+		// eyJ prefix without three segments isn't a JWT.
+		{"eyJabc", false, "prefix only"},
+		{"eyJabc.def", false, "two segments"},
+		// Empty / nonsense.
+		{"", false, "empty"},
+		{"....", false, "dots only"},
+	}
+	for _, c := range cases {
+		if got := isLikelyJWT(c.in); got != c.want {
+			t.Errorf("isLikelyJWT(%q) = %v, want %v (%s)", c.in, got, c.want, c.why)
+		}
+	}
+}
+
+func TestNewAutoSelectsAuthHeader(t *testing.T) {
+	// Capture which auth header reaches the server for each token shape.
+	var lastReq *http.Request
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		lastReq = r
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "{}")
+	}))
+	defer srv.Close()
+
+	// api-key path: should go via X-API-Key, NOT Authorization.
+	apiKey := "f654c3ff0bbc09e6a22294dfbbbff371a4550366849f59de68ddf064742831a0"
+	if _, err := New(srv.URL, apiKey).Get("/anything"); err != nil {
+		t.Fatalf("api-key call failed: %v", err)
+	}
+	if got := lastReq.Header.Get("X-API-Key"); got != apiKey {
+		t.Errorf("api-key not sent as X-API-Key (got %q)", got)
+	}
+	if got := lastReq.Header.Get("Authorization"); got != "" {
+		t.Errorf("api-key leaked into Authorization header (got %q)", got)
+	}
+
+	// JWT path: should go via Authorization: Bearer, NOT X-API-Key.
+	jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIn0.signature"
+	if _, err := New(srv.URL, jwt).Get("/anything"); err != nil {
+		t.Fatalf("jwt call failed: %v", err)
+	}
+	if got := lastReq.Header.Get("Authorization"); !strings.HasPrefix(got, "Bearer ") || !strings.HasSuffix(got, jwt) {
+		t.Errorf("jwt not sent as Bearer (got %q)", got)
+	}
+	if got := lastReq.Header.Get("X-API-Key"); got != "" {
+		t.Errorf("jwt leaked into X-API-Key header (got %q)", got)
+	}
+
+	// Empty token: neither header set.
+	if _, err := New(srv.URL, "").Get("/anything"); err != nil {
+		t.Fatalf("empty-token call failed: %v", err)
+	}
+	if got := lastReq.Header.Get("Authorization"); got != "" {
+		t.Errorf("empty token set Authorization (got %q)", got)
+	}
+	if got := lastReq.Header.Get("X-API-Key"); got != "" {
+		t.Errorf("empty token set X-API-Key (got %q)", got)
+	}
+}
+
+func TestNewWithAPIKeyAlwaysUsesAPIKeyHeader(t *testing.T) {
+	// Even if someone passes a JWT-shaped string via NewWithAPIKey, it must
+	// still go via X-API-Key — the explicit constructor wins.
+	var lastReq *http.Request
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		lastReq = r
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "{}")
+	}))
+	defer srv.Close()
+
+	jwtShape := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIn0.signature"
+	if _, err := NewWithAPIKey(srv.URL, jwtShape).Get("/anything"); err != nil {
+		t.Fatalf("call failed: %v", err)
+	}
+	if got := lastReq.Header.Get("X-API-Key"); got != jwtShape {
+		t.Errorf("NewWithAPIKey didn't use X-API-Key (got %q)", got)
+	}
+	if got := lastReq.Header.Get("Authorization"); got != "" {
+		t.Errorf("NewWithAPIKey set Authorization (got %q)", got)
+	}
+}

internal/commands/agent.go

@@ -0,0 +1,140 @@
+// Package commands — agent runtime-status command (`hf agent status`).
+//
+// Wraps the plugin-facing `POST /calendar/agent/status` endpoint so agents
+// driven from `pcexec` (which sets AGENT_ID/CLAW_IDENTIFIER env) can report
+// their status from a workflow without writing curl in the middle of a
+// `flow.md` procedure.
+//
+// The endpoint itself is unauthenticated at the HTTP layer — it identifies
+// the agent purely from X-Agent-ID + X-Claw-Identifier headers — so this
+// command does NOT call `ResolveToken`. Calling it from outside a pcexec
+// session will fail because AGENT_ID/CLAW_IDENTIFIER won't be set.
+package commands
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/config"
+	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/output"
+)
+
+// RunAgentStatus implements `hf agent status --set <status>`.
+//
+// Supported statuses (mirrors backend `AgentStatus` enum):
+//   idle | busy | on_call | exhausted | offline
+//
+// For `exhausted`, an optional `--reason <rate_limit|billing>` and
+// `--recovery-at <ISO-8601>` can be provided.
+func RunAgentStatus(args []string) {
+	target := ""
+	reason := ""
+	recoveryAt := ""
+
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--set":
+			if i+1 >= len(args) {
+				output.Error("usage: hf agent status --set <idle|busy|on_call|exhausted|offline> [--reason <rate_limit|billing>] [--recovery-at <iso>]")
+			}
+			target = args[i+1]
+			i++
+		case "--reason":
+			if i+1 >= len(args) {
+				output.Error("--reason requires a value")
+			}
+			reason = args[i+1]
+			i++
+		case "--recovery-at":
+			if i+1 >= len(args) {
+				output.Error("--recovery-at requires an ISO-8601 timestamp")
+			}
+			recoveryAt = args[i+1]
+			i++
+		default:
+			output.Errorf("unknown flag: %s", args[i])
+		}
+	}
+
+	if target == "" {
+		output.Error("--set <status> is required")
+	}
+
+	agentID := strings.TrimSpace(os.Getenv("AGENT_ID"))
+	clawID := strings.TrimSpace(os.Getenv("CLAW_IDENTIFIER"))
+	if clawID == "" {
+		// Match the plugin convention: hostname fallback when CLAW_IDENTIFIER
+		// is unset. Most pcexec callers won't have it set in env.
+		if h, err := os.Hostname(); err == nil {
+			clawID = h
+		}
+	}
+	if agentID == "" {
+		output.Error("AGENT_ID env is not set — run via pcexec or export AGENT_ID first")
+	}
+	if clawID == "" {
+		output.Error("CLAW_IDENTIFIER env not set and hostname() failed — set CLAW_IDENTIFIER explicitly")
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		output.Errorf("config error: %v", err)
+	}
+
+	body := map[string]interface{}{
+		"agent_id":         agentID,
+		"claw_identifier":  clawID,
+		"status":           target,
+	}
+	if reason != "" {
+		body["exhaust_reason"] = reason
+	}
+	if recoveryAt != "" {
+		body["recovery_at"] = recoveryAt
+	}
+
+	payload, err := json.Marshal(body)
+	if err != nil {
+		output.Errorf("cannot marshal payload: %v", err)
+	}
+
+	url := strings.TrimRight(cfg.BaseURL, "/") + "/calendar/agent/status"
+	req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(payload))
+	if err != nil {
+		output.Errorf("cannot build request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Agent-ID", agentID)
+	req.Header.Set("X-Claw-Identifier", clawID)
+
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		output.Errorf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode/100 != 2 {
+		buf := new(bytes.Buffer)
+		_, _ = buf.ReadFrom(resp.Body)
+		output.Errorf("backend returned %d: %s", resp.StatusCode, buf.String())
+	}
+
+	if output.JSONMode {
+		buf := new(bytes.Buffer)
+		_, _ = buf.ReadFrom(resp.Body)
+		fmt.Println(buf.String())
+		return
+	}
+	output.PrintKeyValue(
+		"agent_id", agentID,
+		"claw_identifier", clawID,
+		"status", target,
+		"ok", "true",
+	)
+}

internal/commands/schedule_type.go

@@ -0,0 +1,165 @@
+package commands
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+
+	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/client"
+	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/config"
+	"git.hangman-lab.top/zhi/HarborForge.Cli/internal/output"
+)
+
+type scheduleTypeResponse struct {
+	ID                int    `json:"id"`
+	Name              string `json:"name"`
+	WorkFrom          int    `json:"work_from"`
+	WorkTo            int    `json:"work_to"`
+	EntertainmentFrom int    `json:"entertainment_from"`
+	EntertainmentTo   int    `json:"entertainment_to"`
+}
+
+// RunScheduleTypeList implements `hf schedule-type list`.
+func RunScheduleTypeList(tokenFlag string) {
+	token := ResolveToken(tokenFlag)
+	cfg, err := config.Load()
+	if err != nil {
+		output.Errorf("config error: %v", err)
+	}
+	c := client.New(cfg.BaseURL, token)
+	data, err := c.Get("/schedule-types/")
+	if err != nil {
+		output.Errorf("failed to list schedule types: %v", err)
+	}
+
+	var types []scheduleTypeResponse
+	if err := json.Unmarshal(data, &types); err != nil {
+		output.Errorf("invalid response: %v", err)
+	}
+
+	if output.JSONMode {
+		output.PrintJSON(types)
+		return
+	}
+
+	if len(types) == 0 {
+		fmt.Println("No schedule types defined.")
+		return
+	}
+
+	fmt.Printf("%-4s %-20s %-12s %-12s\n", "ID", "Name", "Work", "Entertainment")
+	fmt.Printf("%-4s %-20s %-12s %-12s\n", "----", "--------------------", "------------", "------------")
+	for _, t := range types {
+		fmt.Printf("%-4d %-20s %02d:00-%02d:00  %02d:00-%02d:00\n",
+			t.ID, t.Name, t.WorkFrom, t.WorkTo, t.EntertainmentFrom, t.EntertainmentTo)
+	}
+}
+
+// RunScheduleTypeCreate implements `hf schedule-type create <name> --work <from>-<to> --entertainment <from>-<to>`.
+func RunScheduleTypeCreate(args []string, tokenFlag string) {
+	token := ResolveToken(tokenFlag)
+
+	if len(args) < 1 {
+		output.Error("usage: hf schedule-type create <name> --work <from>-<to> --entertainment <from>-<to>")
+	}
+
+	name := args[0]
+	workFrom, workTo, entFrom, entTo := -1, -1, -1, -1
+
+	for i := 1; i < len(args); i++ {
+		switch args[i] {
+		case "--work":
+			if i+1 < len(args) {
+				i++
+				fmt.Sscanf(args[i], "%d-%d", &workFrom, &workTo)
+			}
+		case "--entertainment":
+			if i+1 < len(args) {
+				i++
+				fmt.Sscanf(args[i], "%d-%d", &entFrom, &entTo)
+			}
+		}
+	}
+
+	if workFrom < 0 || workTo < 0 || entFrom < 0 || entTo < 0 {
+		output.Error("usage: hf schedule-type create <name> --work <from>-<to> --entertainment <from>-<to>\n  e.g.: hf schedule-type create standard --work 8-18 --entertainment 19-23")
+	}
+
+	body := map[string]any{
+		"name":               name,
+		"work_from":          workFrom,
+		"work_to":            workTo,
+		"entertainment_from": entFrom,
+		"entertainment_to":   entTo,
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		output.Errorf("config error: %v", err)
+	}
+
+	jsonBody, _ := json.Marshal(body)
+	c := client.New(cfg.BaseURL, token)
+	data, err := c.Post("/schedule-types/", bytes.NewReader(jsonBody))
+	if err != nil {
+		output.Errorf("failed to create schedule type: %v", err)
+	}
+
+	var resp scheduleTypeResponse
+	json.Unmarshal(data, &resp)
+	fmt.Printf("Created schedule type: %s (id=%d, work=%02d:00-%02d:00, entertainment=%02d:00-%02d:00)\n",
+		resp.Name, resp.ID, resp.WorkFrom, resp.WorkTo, resp.EntertainmentFrom, resp.EntertainmentTo)
+}
+
+// RunScheduleTypeDelete implements `hf schedule-type delete <id>`.
+func RunScheduleTypeDelete(args []string, tokenFlag string) {
+	token := ResolveToken(tokenFlag)
+
+	if len(args) < 1 {
+		output.Error("usage: hf schedule-type delete <id>")
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		output.Errorf("config error: %v", err)
+	}
+
+	c := client.New(cfg.BaseURL, token)
+	_, err = c.Delete("/schedule-types/" + args[0])
+	if err != nil {
+		output.Errorf("failed to delete schedule type: %v", err)
+	}
+	fmt.Printf("Deleted schedule type %s\n", args[0])
+}
+
+// RunAssignScheduleType implements `hf assign-schedule-type <agent-id> <schedule-type-name>`.
+func RunAssignScheduleType(args []string, tokenFlag string) {
+	token := ResolveToken(tokenFlag)
+
+	if len(args) < 2 {
+		output.Error("usage: hf assign-schedule-type <agent-id> <schedule-type-name>")
+	}
+
+	agentID := args[0]
+	scheduleName := args[1]
+
+	body := map[string]string{
+		"schedule_type_name": scheduleName,
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		output.Errorf("config error: %v", err)
+	}
+
+	jsonBody, _ := json.Marshal(body)
+	c := client.New(cfg.BaseURL, token)
+	data, err := c.Put("/schedule-types/agent/"+agentID+"/assign", bytes.NewReader(jsonBody))
+	if err != nil {
+		output.Errorf("failed to assign schedule type: %v", err)
+	}
+
+	var resp map[string]any
+	json.Unmarshal(data, &resp)
+	fmt.Printf("Assigned schedule type '%s' to agent '%s'\n", scheduleName, agentID)
+}

internal/commands/user.go

@@ -141,6 +141,60 @@ type userCreatePayload struct {
 	FullName *string `json:"full_name,omitempty"`
 	Password *string `json:"password,omitempty"`
 	DiscordUserID *string `json:"discord_user_id,omitempty"`
+	// Agent binding — both fields go together or both stay nil.
+	// Backend rejects (400) if only one is set.
+	AgentID *string `json:"agent_id,omitempty"`
+	ClawIdentifier *string `json:"claw_identifier,omitempty"`
+}
+
+// userBindAgentPayload is the JSON body for PATCH /users/{id}/bind-agent.
+type userBindAgentPayload struct {
+	AgentID string `json:"agent_id"`
+	ClawIdentifier string `json:"claw_identifier"`
+}
+
+// resolveAgentBinding picks the final (agent_id, claw_identifier) pair
+// to send to the backend.
+//
+// Explicit flags win. If either is empty, fall back to the pcexec env
+// (AGENT_ID) and to `openclaw config get plugins.harbor-forge.identifier`
+// for the claw — same convention as the openclaw plugin's heartbeat.
+//
+// Honours the backend's "both or neither" invariant: if only one side
+// can be resolved, returns (nil, nil) — caller's intent of creating a
+// non-agent user is preserved instead of producing a 400. When the
+// caller actually NEEDS the binding (e.g. `hf user bind-agent` is the
+// whole point of the command), set `requireBoth=true` to fail loudly
+// instead.
+func resolveAgentBinding(explicitAgentID, explicitClawID string, requireBoth bool) (*string, *string) {
+	agentID := strings.TrimSpace(explicitAgentID)
+	clawID := strings.TrimSpace(explicitClawID)
+
+	if agentID == "" {
+		agentID = strings.TrimSpace(os.Getenv("AGENT_ID"))
+	}
+	if clawID == "" {
+		if v, err := exec.Command("openclaw", "config", "get", "plugins.harbor-forge.identifier").Output(); err == nil {
+			clawID = strings.TrimSpace(string(v))
+		}
+	}
+
+	if agentID == "" && clawID == "" {
+		if requireBoth {
+			output.Error("--agent-id and --claw-identifier required (AGENT_ID env and `openclaw config get plugins.harbor-forge.identifier` both empty)")
+		}
+		return nil, nil
+	}
+	if agentID == "" || clawID == "" {
+		if requireBoth {
+			output.Errorf(
+				"could not resolve agent binding pair: agent_id=%q claw_identifier=%q (need both)",
+				agentID, clawID,
+			)
+		}
+		return nil, nil
+	}
+	return &agentID, &clawID
 }
 
 func maybeResolveDiscordUserID(explicit string, requireEnv bool) (string, bool, error) {
@@ -174,7 +228,12 @@ func maybeResolveDiscordUserID(explicit string, requireEnv bool) (string, bool,
 }
 
 // RunUserCreate implements `hf user create`.
-func RunUserCreate(username, password, email, fullName, discordUserID, accMgrTokenFlag string) {
+//
+// Agent binding: if `agentIDFlag` + `clawIDFlag` are both set (or both
+// resolvable from env), the backend creates the matching agents row in
+// the same transaction. Partial pair → treated as "neither" so callers
+// who didn't want a binding still get a normal user.
+func RunUserCreate(username, password, email, fullName, discordUserID, agentIDFlag, clawIDFlag, accMgrTokenFlag string) {
 	// Resolve account-manager token
 	var accMgrToken string
 	if mode.IsPaddedCell() {
@@ -224,6 +283,12 @@ func RunUserCreate(username, password, email, fullName, discordUserID, accMgrTok
 		payload.FullName = &fullName
 	}
 
+	// Agent binding — resolve from flags + pcexec env fallback.
+	if agentID, clawID := resolveAgentBinding(agentIDFlag, clawIDFlag, false); agentID != nil && clawID != nil {
+		payload.AgentID = agentID
+		payload.ClawIdentifier = clawID
+	}
+
 	body, err := json.Marshal(payload)
 	if err != nil {
 		output.Errorf("cannot marshal payload: %v", err)
@@ -447,3 +512,82 @@ func RunUserResetAPIKey(username, tokenFlag, accMgrTokenFlag string) {
 		"message", r.Message,
 	)
 }
+
+// RunUserBindAgent implements `hf user bind-agent <username>`.
+//
+// Backfills the agents row for an existing user that was created via
+// the old `hf user create` (which did not accept --agent-id /
+// --claw-identifier). Hits PATCH /users/{username}/bind-agent.
+//
+// Uses an account-manager token like `hf user create` does — same
+// permission surface (`account.create`).
+func RunUserBindAgent(username, agentIDFlag, clawIDFlag, accMgrTokenFlag string) {
+	if username == "" {
+		output.Error("usage: hf user bind-agent <username> [--agent-id <id>] [--claw-identifier <id>]")
+	}
+
+	// Resolve account-manager token (same as RunUserCreate).
+	var accMgrToken string
+	if mode.IsPaddedCell() {
+		if accMgrTokenFlag != "" {
+			output.Error("padded-cell installed, --acc-mgr-token flag disabled, use command directly")
+		}
+		tok, err := passmgr.GetAccountManagerToken()
+		if err != nil {
+			output.Error("--acc-mgr-token <token> required or execute with pcexec")
+		}
+		accMgrToken = tok
+	} else {
+		if accMgrTokenFlag == "" {
+			output.Error("--acc-mgr-token <token> required or execute with pcexec")
+		}
+		accMgrToken = accMgrTokenFlag
+	}
+
+	// Resolve agent binding — REQUIRED for this command (errors out on partial).
+	agentID, clawID := resolveAgentBinding(agentIDFlag, clawIDFlag, true)
+	if agentID == nil || clawID == nil {
+		output.Error("--agent-id and --claw-identifier could not be resolved (bug — requireBoth should have errored already)")
+	}
+
+	payload := userBindAgentPayload{
+		AgentID:        *agentID,
+		ClawIdentifier: *clawID,
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		output.Errorf("cannot marshal payload: %v", err)
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		output.Errorf("config error: %v", err)
+	}
+	c := client.NewWithAPIKey(cfg.BaseURL, accMgrToken)
+	data, err := c.Patch("/users/"+username+"/bind-agent", bytes.NewReader(body))
+	if err != nil {
+		output.Errorf("failed to bind agent: %v", err)
+	}
+
+	if output.JSONMode {
+		var raw json.RawMessage
+		if err := json.Unmarshal(data, &raw); err != nil {
+			output.Errorf("invalid JSON response: %v", err)
+		}
+		output.PrintJSON(raw)
+		return
+	}
+
+	var u userResponse
+	if err := json.Unmarshal(data, &u); err != nil {
+		fmt.Printf("agent bound to %s (agent_id=%s, claw=%s)\n", username, *agentID, *clawID)
+		return
+	}
+	output.PrintKeyValue(
+		"username", u.Username,
+		"user_id", fmt.Sprint(u.ID),
+		"agent_id", *agentID,
+		"claw_identifier", *clawID,
+		"message", "agent binding written",
+	)
+}

internal/help/surface.go

@@ -29,6 +29,13 @@ func CommandSurface() []Group {
 		{Name: "version", Description: "Show CLI version", Permitted: true},
 		{Name: "health", Description: "Check API health", Permitted: true},
 		{Name: "config", Description: "View and manage CLI configuration", Permitted: true},
+		{
+			Name:        "agent",
+			Description: "Runtime status reporting for the calling agent (uses AGENT_ID/CLAW_IDENTIFIER env)",
+			SubCommands: []Command{
+				{Name: "status", Description: "Report runtime status: hf agent status --set <idle|busy|on_call|exhausted|offline>", Permitted: true},
+			},
+		},
 		{
 			Name:        "user",
 			Description: "Manage users",
@@ -41,6 +48,7 @@ func CommandSurface() []Group {
 				{Name: "deactivate", Description: "Deactivate a user", Permitted: has(perms, "user.manage")},
 				{Name: "delete", Description: "Delete a user", Permitted: has(perms, "user.manage")},
 				{Name: "reset-apikey", Description: "Reset a user's API key", Permitted: true},
+				{Name: "bind-agent", Description: "Backfill the agents row for an existing user (acc-mgr token; use --agent-id / --claw-identifier or AGENT_ID env)", Permitted: true},
 			},
 		},
 		{
@@ -68,7 +76,7 @@ func CommandSurface() []Group {
 			SubCommands: []Command{
 				{Name: "list", Description: "List projects", Permitted: has(perms, "project.read")},
 				{Name: "get", Description: "Show a project by code", Permitted: has(perms, "project.read")},
-				{Name: "create", Description: "Create a project", Permitted: has(perms, "project.write")},
+				{Name: "create", Description: "Create a project", Permitted: has(perms, "project.create")},
 				{Name: "update", Description: "Update a project", Permitted: has(perms, "project.write")},
 				{Name: "delete", Description: "Delete a project", Permitted: has(perms, "project.delete")},
 				{Name: "members", Description: "List project members", Permitted: has(perms, "project.read")},
@@ -181,6 +189,16 @@ func CommandSurface() []Group {
 				{Name: "api-key", Description: "Manage monitor API keys", Permitted: has(perms, "monitor.manage")},
 			},
 		},
+		{
+			Name:        "schedule-type",
+			Description: "Manage work/entertainment schedule types",
+			SubCommands: []Command{
+				{Name: "list", Description: "List schedule types", Permitted: has(perms, "schedule_type.read")},
+				{Name: "create", Description: "Create a schedule type", Permitted: has(perms, "schedule_type.manage")},
+				{Name: "delete", Description: "Delete a schedule type", Permitted: has(perms, "schedule_type.manage")},
+			},
+		},
+		{Name: "assign-schedule-type", Description: "Assign a schedule type to an agent: assign-schedule-type <agent-id> <type-name>", Permitted: has(perms, "schedule_type.manage")},
 	}
 
 	for i := range groups {
@@ -206,7 +224,12 @@ func loadPermissionState(token string) permissionState {
 		return permissionState{Known: false, Permissions: map[string]struct{}{}}
 	}
 
-	c := client.New(cfg.BaseURL, token)
+	// passmgr.GetToken() returns an api-key in padded-cell mode (provisioned
+	// by scripts/provision-hf-accounts.sh via `hf user reset-apikey`), so go
+	// through the X-API-Key path explicitly. client.New also auto-detects this
+	// nowadays, but the explicit call keeps the introspection path independent
+	// of that heuristic.
+	c := client.NewWithAPIKey(cfg.BaseURL, token)
 	data, err := c.Get("/auth/me/permissions")
 	if err != nil {
 		return permissionState{Known: false, Permissions: map[string]struct{}{}}