feat(unix): centralize Unix integration service in @agor/core

Moves Unix user/group/symlink management to packages/core for shared use by
CLI and daemon. Introduces CommandExecutor abstraction for privilege escalation.

Key changes:
- Add CommandExecutor interface with DirectExecutor, SudoCliExecutor, NoOpExecutor
- Add UnixIntegrationService with worktree groups, user management, symlinks
- Add user-manager.ts with Unix user utilities and command strings
- Add symlink-manager.ts with symlink utilities for worktree access
- Refactor daemon to use core service via factory pattern
- Wire up hooks in worktree-owners for auto group membership
- Wire up hooks in users service for auto Unix user creation
- Add CLI admin commands: ensure-user, delete-user, create/remove-symlink, sync-user-symlinks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Claude Code

apps/agor-cli/src/commands/admin/create-symlink.ts

@@ -0,0 +1,95 @@
+/**
+ * Admin Command: Create Worktree Symlink
+ *
+ * PRIVILEGED OPERATION - Must be called via sudo
+ *
+ * Creates a symlink in a user's ~/agor/worktrees directory pointing to a worktree.
+ * This command is designed to be called by the daemon via `sudo agor admin create-symlink`.
+ *
+ * @see context/guides/rbac-and-unix-isolation.md
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  AGOR_HOME_BASE,
+  getWorktreeSymlinkPath,
+  isValidUnixUsername,
+  SymlinkCommands,
+} from '@agor/core/unix';
+import { Command, Flags } from '@oclif/core';
+
+export default class CreateSymlink extends Command {
+  static override description = 'Create a worktree symlink in user home directory (admin only)';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %> --username alice --worktree-name my-feature --worktree-path /var/agor/worktrees/abc123',
+  ];
+
+  static override flags = {
+    username: Flags.string({
+      char: 'u',
+      description: 'Unix username (owner of symlink)',
+      required: true,
+    }),
+    'worktree-name': Flags.string({
+      char: 'n',
+      description: 'Worktree name/slug (symlink name)',
+      required: true,
+    }),
+    'worktree-path': Flags.string({
+      char: 'p',
+      description: 'Absolute path to worktree directory (symlink target)',
+      required: true,
+    }),
+    'home-base': Flags.string({
+      description: 'Base directory for home directories',
+      default: AGOR_HOME_BASE,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(CreateSymlink);
+    const { username } = flags;
+    const worktreeName = flags['worktree-name'];
+    const worktreePath = flags['worktree-path'];
+    const homeBase = flags['home-base'];
+
+    // Validate username
+    if (!isValidUnixUsername(username)) {
+      this.error(`Invalid Unix username format: ${username}`);
+    }
+
+    // Validate worktree path is absolute
+    if (!worktreePath.startsWith('/')) {
+      this.error(`Worktree path must be absolute: ${worktreePath}`);
+    }
+
+    const linkPath = getWorktreeSymlinkPath(username, worktreeName, homeBase);
+
+    // Check if symlink already exists and points to same target
+    try {
+      const existingTarget = execSync(SymlinkCommands.readSymlink(linkPath), {
+        encoding: 'utf-8',
+      }).trim();
+
+      if (existingTarget === worktreePath) {
+        this.log(`✅ Symlink already exists: ${linkPath} -> ${worktreePath}`);
+        return;
+      }
+      // Symlink exists but points elsewhere - will be replaced
+      this.log(`ℹ️  Updating symlink (was: ${existingTarget})`);
+    } catch {
+      // Symlink doesn't exist, will create
+    }
+
+    // Create symlink with proper ownership
+    try {
+      execSync(SymlinkCommands.createSymlinkWithOwnership(worktreePath, linkPath, username), {
+        stdio: 'inherit',
+      });
+      this.log(`✅ Created symlink: ${linkPath} -> ${worktreePath}`);
+    } catch (error) {
+      this.error(`Failed to create symlink: ${error}`);
+    }
+  }
+}

apps/agor-cli/src/commands/admin/delete-user.ts

@@ -0,0 +1,67 @@
+/**
+ * Admin Command: Delete Unix User
+ *
+ * PRIVILEGED OPERATION - Must be called via sudo
+ *
+ * Deletes a Unix user. Optionally removes their home directory.
+ * This command is designed to be called by the daemon via `sudo agor admin delete-user`.
+ *
+ * @see context/guides/rbac-and-unix-isolation.md
+ */
+
+import { execSync } from 'node:child_process';
+import { isValidUnixUsername, UnixUserCommands } from '@agor/core/unix';
+import { Command, Flags } from '@oclif/core';
+
+export default class DeleteUser extends Command {
+  static override description = 'Delete a Unix user (admin only)';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %> --username agor_03b62447',
+    '<%= config.bin %> <%= command.id %> --username agor_03b62447 --delete-home',
+  ];
+
+  static override flags = {
+    username: Flags.string({
+      char: 'u',
+      description: 'Unix username to delete',
+      required: true,
+    }),
+    'delete-home': Flags.boolean({
+      description: 'Also delete the user home directory',
+      default: false,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(DeleteUser);
+    const { username } = flags;
+    const deleteHome = flags['delete-home'];
+
+    // Validate username format
+    if (!isValidUnixUsername(username)) {
+      this.error(`Invalid Unix username format: ${username}`);
+    }
+
+    // Check if user exists
+    try {
+      execSync(UnixUserCommands.userExists(username), { stdio: 'ignore' });
+    } catch {
+      this.log(`✅ Unix user ${username} does not exist (nothing to do)`);
+      return;
+    }
+
+    // Delete the user
+    try {
+      if (deleteHome) {
+        execSync(UnixUserCommands.deleteUserWithHome(username), { stdio: 'inherit' });
+        this.log(`✅ Deleted Unix user ${username} and home directory`);
+      } else {
+        execSync(UnixUserCommands.deleteUser(username), { stdio: 'inherit' });
+        this.log(`✅ Deleted Unix user ${username} (home directory preserved)`);
+      }
+    } catch (error) {
+      this.error(`Failed to delete user ${username}: ${error}`);
+    }
+  }
+}

apps/agor-cli/src/commands/admin/ensure-user.ts

@@ -0,0 +1,76 @@
+/**
+ * Admin Command: Ensure Unix User Exists
+ *
+ * PRIVILEGED OPERATION - Must be called via sudo
+ *
+ * Creates a Unix user if it doesn't exist, with home directory and ~/agor/worktrees setup.
+ * This command is designed to be called by the daemon via `sudo agor admin ensure-user`.
+ *
+ * @see context/guides/rbac-and-unix-isolation.md
+ */
+
+import { execSync } from 'node:child_process';
+import { AGOR_HOME_BASE, isValidUnixUsername, UnixUserCommands } from '@agor/core/unix';
+import { Command, Flags } from '@oclif/core';
+
+export default class EnsureUser extends Command {
+  static override description = 'Ensure a Unix user exists with proper Agor setup (admin only)';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %> --username agor_03b62447',
+    '<%= config.bin %> <%= command.id %> --username alice --home-base /home',
+  ];
+
+  static override flags = {
+    username: Flags.string({
+      char: 'u',
+      description: 'Unix username to create/ensure',
+      required: true,
+    }),
+    'home-base': Flags.string({
+      description: 'Base directory for home directories',
+      default: AGOR_HOME_BASE,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(EnsureUser);
+    const { username } = flags;
+    const homeBase = flags['home-base'];
+
+    // Validate username format
+    if (!isValidUnixUsername(username)) {
+      this.error(`Invalid Unix username format: ${username}`);
+    }
+
+    // Check if user already exists
+    try {
+      execSync(UnixUserCommands.userExists(username), { stdio: 'ignore' });
+      this.log(`✅ Unix user ${username} already exists`);
+
+      // Ensure ~/agor/worktrees directory exists
+      try {
+        execSync(UnixUserCommands.setupWorktreesDir(username, homeBase), { stdio: 'inherit' });
+        this.log(`✅ Ensured ~/agor/worktrees directory for ${username}`);
+      } catch (error) {
+        this.warn(`Failed to setup worktrees directory: ${error}`);
+      }
+
+      return;
+    } catch {
+      // User doesn't exist, create it
+    }
+
+    // Create the user
+    try {
+      execSync(UnixUserCommands.createUser(username, '/bin/bash', homeBase), { stdio: 'inherit' });
+      this.log(`✅ Created Unix user: ${username}`);
+
+      // Setup ~/agor/worktrees directory
+      execSync(UnixUserCommands.setupWorktreesDir(username, homeBase), { stdio: 'inherit' });
+      this.log(`✅ Created ~/agor/worktrees directory for ${username}`);
+    } catch (error) {
+      this.error(`Failed to create user ${username}: ${error}`);
+    }
+  }
+}

apps/agor-cli/src/commands/admin/remove-symlink.ts

@@ -0,0 +1,74 @@
+/**
+ * Admin Command: Remove Worktree Symlink
+ *
+ * PRIVILEGED OPERATION - Must be called via sudo
+ *
+ * Removes a symlink from a user's ~/agor/worktrees directory.
+ * This command is designed to be called by the daemon via `sudo agor admin remove-symlink`.
+ *
+ * @see context/guides/rbac-and-unix-isolation.md
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  AGOR_HOME_BASE,
+  getWorktreeSymlinkPath,
+  isValidUnixUsername,
+  SymlinkCommands,
+} from '@agor/core/unix';
+import { Command, Flags } from '@oclif/core';
+
+export default class RemoveSymlink extends Command {
+  static override description = 'Remove a worktree symlink from user home directory (admin only)';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %> --username alice --worktree-name my-feature',
+  ];
+
+  static override flags = {
+    username: Flags.string({
+      char: 'u',
+      description: 'Unix username (owner of symlink)',
+      required: true,
+    }),
+    'worktree-name': Flags.string({
+      char: 'n',
+      description: 'Worktree name/slug (symlink name)',
+      required: true,
+    }),
+    'home-base': Flags.string({
+      description: 'Base directory for home directories',
+      default: AGOR_HOME_BASE,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(RemoveSymlink);
+    const { username } = flags;
+    const worktreeName = flags['worktree-name'];
+    const homeBase = flags['home-base'];
+
+    // Validate username
+    if (!isValidUnixUsername(username)) {
+      this.error(`Invalid Unix username format: ${username}`);
+    }
+
+    const linkPath = getWorktreeSymlinkPath(username, worktreeName, homeBase);
+
+    // Check if symlink exists
+    try {
+      execSync(SymlinkCommands.symlinkExists(linkPath), { stdio: 'ignore' });
+    } catch {
+      this.log(`✅ Symlink does not exist: ${linkPath} (nothing to do)`);
+      return;
+    }
+
+    // Remove symlink
+    try {
+      execSync(SymlinkCommands.removeSymlink(linkPath), { stdio: 'inherit' });
+      this.log(`✅ Removed symlink: ${linkPath}`);
+    } catch (error) {
+      this.error(`Failed to remove symlink: ${error}`);
+    }
+  }
+}

apps/agor-cli/src/commands/admin/sync-user-symlinks.ts

@@ -0,0 +1,66 @@
+/**
+ * Admin Command: Sync User Symlinks
+ *
+ * PRIVILEGED OPERATION - Must be called via sudo
+ *
+ * Cleans up broken symlinks in a user's ~/agor/worktrees directory.
+ * This command is designed to be called by the daemon via `sudo agor admin sync-user-symlinks`.
+ *
+ * @see context/guides/rbac-and-unix-isolation.md
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  AGOR_HOME_BASE,
+  getUserWorktreesDir,
+  isValidUnixUsername,
+  SymlinkCommands,
+} from '@agor/core/unix';
+import { Command, Flags } from '@oclif/core';
+
+export default class SyncUserSymlinks extends Command {
+  static override description = 'Clean up broken symlinks in user worktrees directory (admin only)';
+
+  static override examples = ['<%= config.bin %> <%= command.id %> --username alice'];
+
+  static override flags = {
+    username: Flags.string({
+      char: 'u',
+      description: 'Unix username',
+      required: true,
+    }),
+    'home-base': Flags.string({
+      description: 'Base directory for home directories',
+      default: AGOR_HOME_BASE,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(SyncUserSymlinks);
+    const { username } = flags;
+    const homeBase = flags['home-base'];
+
+    // Validate username
+    if (!isValidUnixUsername(username)) {
+      this.error(`Invalid Unix username format: ${username}`);
+    }
+
+    const worktreesDir = getUserWorktreesDir(username, homeBase);
+
+    // Check if directory exists
+    try {
+      execSync(SymlinkCommands.pathExists(worktreesDir), { stdio: 'ignore' });
+    } catch {
+      this.log(`✅ Worktrees directory does not exist: ${worktreesDir} (nothing to do)`);
+      return;
+    }
+
+    // Remove broken symlinks
+    try {
+      execSync(SymlinkCommands.removeBrokenSymlinks(worktreesDir), { stdio: 'inherit' });
+      this.log(`✅ Cleaned up broken symlinks in: ${worktreesDir}`);
+    } catch (error) {
+      this.error(`Failed to sync symlinks: ${error}`);
+    }
+  }
+}