agent execution context requires MULTICA_TOKEN to be a…

Error message

agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s

What it means

newAPIClient refuses to build a client in a daemon-managed execution context unless the token is a task-scoped mat_ token. When the only daemon signal is a leftover workdir marker (no MULTICA_AGENT_ID/MULTICA_TASK_ID/MULTICA_DAEMON_PORT), the message appends the exact marker file path so the user can recover instead of hitting an opaque refusal.

Solutions

Delete the marker file named in the error's appended suffix (the message gives the exact path).
Re-run the command from a directory outside the stale marker's tree, or from the repository root above it, to confirm it was directory-scoped.
If this recurs, check why daemon tasks in local_directory workdirs are not cleaning up their markers on failure, and report/fix the cleanup path.

Example fix

# before: error in a repo where a daemon task crashed
multica agent list
# -> agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token ...

# after: remove the stale marker named in the message
rm /path/to/repo/.multica/daemon-task-marker.json
multica agent list

Defensive patterns

Strategy: validation

Validate before calling

# Before running multica in a repo, check for a stale daemon marker and remove it.
find . -name daemon-task-marker.json -path '*/.multica/*' \
  -exec sh -c 'echo "removing stale marker: $1"; rm "$1"' _ {} \;

Try / catch

// In Go code shelling out to multica:
out, err := cmd.CombinedOutput()
if err != nil && strings.Contains(string(out), "task-scoped mat_ token") {
    if i := strings.Index(string(out), "marker"); i >= 0 {
        return fmt.Errorf("stale daemon marker detected; delete the file named in: %s", string(out))
    }
}

Prevention

Add stale-marker cleanup (or at least detection) to post-task teardown for local_directory runs.
When a daemon task crashes, check its workdir for the marker before reuse.
Keep human shells out of directories used as daemon task workdirs.

When it happens

Trigger: inDaemonManagedExecutionContext() is true (marker file found walking up from cwd, or daemon env vars present), resolveToken returned a non-mat_ token (e.g. the human user's token), and leftoverDaemonTaskMarkerPath() found a stale marker file.

Common situations: A daemon task ran in a local_directory, crashed without cleanup, and left its marker file in the user's repository (MUL-6132); every later multica command in that directory tree is then treated as agent-context while the user authenticates as a human.

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/ff16f5524707f062. Report an issue: GitHub.

Appendix: source

Thrown at server/cmd/multica/cmd_agent.go:265

// resolveProfile returns the --profile flag value (empty string means default profile).
func resolveProfile(cmd *cobra.Command) string {
	val, _ := cmd.Flags().GetString("profile")
	return val
}

func newAPIClient(cmd *cobra.Command) (*cli.APIClient, error) {
	taskContext := inDaemonManagedExecutionContext()
	token := resolveToken(cmd)
	if taskContext && !strings.HasPrefix(token, "mat_") {
		// When the ONLY daemon signal is a workdir marker (no MULTICA_AGENT_ID /
		// MULTICA_TASK_ID / MULTICA_DAEMON_PORT), the likeliest cause outside a
		// real task is a leftover marker from a crashed daemon task in a
		// local_directory. Name the exact file so a normal user can recover
		// instead of hitting an opaque "requires mat_ token" error. Shares its
		// wording with requireHumanLocalCommand: same cause, same remedy.
		if markerPath := leftoverDaemonTaskMarkerPath(); markerPath != "" {
			return nil, fmt.Errorf("agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s", leftoverMarkerSuffix(markerPath))
		}
		return nil, fmt.Errorf("agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s", daemonPortOnlyContextHint())
	}

	serverURL := resolveServerURL(cmd)
	workspaceID := resolveWorkspaceID(cmd)
	if serverURL == "" {
		return nil, fmt.Errorf("server URL not set: use --server-url flag, MULTICA_SERVER_URL env, or 'multica config set server_url <url>'")
	}

	client := cli.NewAPIClient(serverURL, workspaceID, token)
	// When running inside a daemon task, attribute actions to the agent.
	if agentID := os.Getenv("MULTICA_AGENT_ID"); agentID != "" {
		client.AgentID = agentID
	}
	if taskID := os.Getenv("MULTICA_TASK_ID"); taskID != "" {
		client.TaskID = taskID
	}

View on GitHub (pinned to 2c0912b6ec)