@markjaquith/agency 1.10.0 → 1.11.1

package/README.md

@@ -104,6 +104,31 @@ Toggle between source branch and emit branch. If on an emit branch (e.g., `foo--
 
 Switch to the source branch for the current emit branch.
 
+### `agency completions <bash|zsh>`
+
+Generate shell completion scripts. The generated scripts are static, so shell startup and tab completion do not call `agency`.
+
+**zsh:**
+
+```bash
+mkdir -p ~/.zsh/completions
+agency completions zsh > ~/.zsh/completions/_agency
+```
+
+Then add this to `~/.zshrc` before `compinit`:
+
+```bash
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit && compinit
+```
+
+**bash:**
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+agency completions bash > ~/.local/share/bash-completion/completions/agency
+```
+
 ## Requirements
 
 - [Bun](https://bun.sh) >= 1.0.0 (recommended)

package/cli.ts

@@ -20,6 +20,10 @@ import { template, help as templateHelp } from "./src/commands/template"
 import { work, help as workHelp } from "./src/commands/work"
 import { loop, help as loopHelp } from "./src/commands/loop"
 import { status, help as statusHelp } from "./src/commands/status"
+import {
+	completions,
+	help as completionsHelp,
+} from "./src/commands/completions"
 import type { Command } from "./src/types"
 import { setColorsEnabled } from "./src/utils/colors"
 import { GitService } from "./src/services/GitService"
@@ -174,7 +178,7 @@ const commands: Record<string, Command> = {
 	},
 	push: {
 		name: "push",
-		description: "Emit, push to remote, return to source",
+		description: "Push the emitted branch or fall through to git push",
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
 				console.log(pushHelp)
@@ -183,9 +187,11 @@ const commands: Record<string, Command> = {
 			await runCommand(
 				push({
 					baseBranch: args[0],
+					gitArgs: args,
 					emit: options.emit || options.branch,
 					silent: options.silent,
 					force: options.force,
+					forceWithLease: options["force-with-lease"],
 					noVerify: options["no-verify"],
 					verbose: options.verbose,
 					pr: options.pr,
@@ -469,6 +475,18 @@ const commands: Record<string, Command> = {
 		},
 		help: loopHelp,
 	},
+	completions: {
+		name: "completions",
+		description: "Generate shell completion scripts",
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(completionsHelp)
+				return
+			}
+			await runCommand(completions(args[0]))
+		},
+		help: completionsHelp,
+	},
 }
 
 function showMainHelp() {
@@ -492,7 +510,7 @@ Commands:
   emit [base-branch]     Emit a branch with backpack files reverted
   emitted                Get the name of the emitted branch
   pr <subcommand>        Run gh pr with the emitted branch name
-  push [base-branch]     Emit, push to remote, return to source
+  push [arguments]       Push the emitted branch or fall through to git push
   pull                   Pull commits from remote emit branch to source
   rebase [base-branch]   Rebase source branch onto base branch
   base                   Get or set the base branch
@@ -502,6 +520,7 @@ Commands:
   source                 Switch to source branch from emitted branch
   merge                  Merge emitted branch into base branch
   status                 Show agency status for this repository
+  completions <shell>    Generate bash or zsh completion scripts
 
 Global Options:
   -h, --help             Show help for a command
@@ -594,6 +613,9 @@ try {
 				type: "boolean",
 				short: "f",
 			},
+			"force-with-lease": {
+				type: "boolean",
+			},
 			"no-verify": {
 				type: "boolean",
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Manages personal agents files",
   "keywords": [
     "agents",

package/src/commands/completions.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { completions } from "./completions"
+
+const captureCompletions = async (shell: string) => {
+	const originalLog = console.log
+	let output = ""
+	console.log = (message: string) => {
+		output += message
+	}
+
+	try {
+		await Effect.runPromise(completions(shell))
+	} finally {
+		console.log = originalLog
+	}
+
+	return output
+}
+
+describe("completions command", () => {
+	test("generates bash completions", async () => {
+		const output = await captureCompletions("bash")
+
+		expect(output).toContain("_agency_completions()")
+		expect(output).toContain("complete -F _agency_completions agency")
+		expect(output).toContain("completions")
+		expect(output).toContain("bash zsh")
+	})
+
+	test("generates zsh completions", async () => {
+		const output = await captureCompletions("zsh")
+
+		expect(output).toContain("#compdef agency")
+		expect(output).toContain("_agency()")
+		expect(output).toContain("agency_commands=(")
+		expect(output).toContain("bash\\:Generate\\ bash\\ completions")
+	})
+
+	test("prints the requested completion script", async () => {
+		const output = await captureCompletions("zsh")
+
+		expect(output).toContain("#compdef agency")
+	})
+
+	test("rejects unsupported shells", async () => {
+		await expect(Effect.runPromise(completions("fish"))).rejects.toThrow(
+			"Usage: agency completions <bash|zsh>",
+		)
+	})
+})

package/src/commands/completions.ts

@@ -0,0 +1,308 @@
+import { Effect } from "effect"
+
+const shells = ["bash", "zsh"] as const
+type Shell = (typeof shells)[number]
+
+const commands = [
+	"init",
+	"task",
+	"tasks",
+	"edit",
+	"work",
+	"template",
+	"emit",
+	"emitted",
+	"pr",
+	"push",
+	"pull",
+	"rebase",
+	"base",
+	"switch",
+	"source",
+	"merge",
+	"status",
+	"clean",
+	"loop",
+	"completions",
+] as const
+
+const templateSubcommands = ["use", "save", "list", "view", "delete"] as const
+const baseSubcommands = ["get", "set"] as const
+const completionSubcommands = shells
+
+const globalOptions = [
+	"--help",
+	"-h",
+	"--version",
+	"-v",
+	"--no-color",
+	"--silent",
+	"-s",
+	"--verbose",
+] as const
+
+const commandOptions: Record<string, readonly string[]> = {
+	init: [
+		"--help",
+		"-h",
+		"--template",
+		"-t",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	emit: [
+		"--help",
+		"-h",
+		"--emit",
+		"--branch",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	push: [
+		"--help",
+		"-h",
+		"--emit",
+		"--branch",
+		"--force",
+		"-f",
+		"--no-verify",
+		"--pr",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	pull: ["--help", "-h", "--remote", "-r", "--silent", "-s", "--verbose", "-v"],
+	rebase: [
+		"--help",
+		"-h",
+		"--emit",
+		"--branch",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	task: [
+		"--help",
+		"-h",
+		"--emit",
+		"--branch",
+		"--task",
+		"--from",
+		"--from-current",
+		"--continue",
+		"--squash",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	tasks: ["--help", "-h", "--json", "--silent", "-s", "--verbose", "-v"],
+	base: ["--help", "-h", "--repo", "--silent", "-s", "--verbose", "-v"],
+	template: [
+		"--help",
+		"-h",
+		"--template",
+		"-t",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	work: [
+		"--help",
+		"-h",
+		"--opencode",
+		"--claude",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	loop: [
+		"--help",
+		"-h",
+		"--min-loops",
+		"--max-loops",
+		"--opencode",
+		"--claude",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	status: ["--help", "-h", "--json", "--silent", "-s", "--verbose", "-v"],
+	clean: [
+		"--help",
+		"-h",
+		"--dry-run",
+		"--merged-into",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	],
+	completions: ["--help", "-h"],
+}
+
+const words = (values: readonly string[]) => values.join(" ")
+
+const bashCase = (command: string, subcommands?: readonly string[]) => {
+	const options = commandOptions[command] ?? [
+		"--help",
+		"-h",
+		"--silent",
+		"-s",
+		"--verbose",
+		"-v",
+	]
+	const completions = subcommands ? [...subcommands, ...options] : options
+	return `\t\t${command})\n\t\t\tCOMPREPLY=( $(compgen -W "${words(completions)}" -- "$cur") )\n\t\t\treturn 0\n\t\t\t;;`
+}
+
+const zshCommandSpec = (command: string, description: string) =>
+	`    '${command}:${description}'`
+
+const generateBashCompletions = () => `# bash completion for agency
+_agency_completions() {
+	local cur prev command
+	COMPREPLY=()
+	cur="\${COMP_WORDS[COMP_CWORD]}"
+	prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+	if [[ $COMP_CWORD -eq 1 ]]; then
+		COMPREPLY=( $(compgen -W "${words([...commands, ...globalOptions])}" -- "$cur") )
+		return 0
+	fi
+
+	command="\${COMP_WORDS[1]}"
+	case "$command" in
+${bashCase("template", templateSubcommands)}
+${bashCase("base", baseSubcommands)}
+${bashCase("completions", completionSubcommands)}
+${commands
+	.filter((command) => !["template", "base", "completions"].includes(command))
+	.map((command) => bashCase(command))
+	.join("\n")}
+	esac
+
+	case "$prev" in
+		--template|-t|--emit|--branch|--task|--from|--remote|-r|--merged-into)
+			return 0
+			;;
+	esac
+}
+
+complete -F _agency_completions agency
+`
+
+const generateZshCompletions = () => `#compdef agency
+# zsh completion for agency
+
+_agency() {
+  local context state line
+  local -a agency_commands
+  typeset -A opt_args
+
+  agency_commands=(
+${zshCommandSpec("init", "Initialize agency with template selection")}
+${zshCommandSpec("task", "Initialize template files on a feature branch")}
+${zshCommandSpec("tasks", "List all task branches")}
+${zshCommandSpec("edit", "Open TASK.md in system editor")}
+${zshCommandSpec("work", "Start working on TASK.md with OpenCode")}
+${zshCommandSpec("template", "Template management commands")}
+${zshCommandSpec("emit", "Emit a branch with backpack files reverted")}
+${zshCommandSpec("emitted", "Get the name of the emitted branch")}
+${zshCommandSpec("pr", "Run gh pr with the emitted branch name")}
+${zshCommandSpec("push", "Emit, push to remote, return to source")}
+${zshCommandSpec("pull", "Pull commits from remote emit branch to source")}
+${zshCommandSpec("rebase", "Rebase source branch onto base branch")}
+${zshCommandSpec("base", "Get or set the base branch")}
+${zshCommandSpec("switch", "Toggle between source and emitted branch")}
+${zshCommandSpec("source", "Switch to source branch from emitted branch")}
+${zshCommandSpec("merge", "Merge emitted branch into base branch")}
+${zshCommandSpec("status", "Show agency status for this repository")}
+${zshCommandSpec("clean", "Delete branches merged into a specified branch")}
+${zshCommandSpec("loop", "Run a Ralph Wiggum loop to complete all tasks")}
+${zshCommandSpec("completions", "Generate shell completion scripts")}
+  )
+
+  _arguments -C \\
+    '(-h --help)'{-h,--help}'[show help]' \\
+    '(-v --version)'{-v,--version}'[show version]' \\
+    '--no-color[disable color output]' \\
+    '(-s --silent)'{-s,--silent}'[suppress output messages]' \\
+    '--verbose[show verbose output]' \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'agency command' agency_commands
+      ;;
+    args)
+      case $line[1] in
+        template)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[show help]' \\
+            '(-t --template)'{-t,--template}'[template name]:template:' \\
+            '(-s --silent)'{-s,--silent}'[suppress output messages]' \\
+            '--verbose[show verbose output]' \\
+            '1:subcommand:((use\\:Set\\ template save\\:Save\\ files list\\:List\\ files view\\:View\\ file delete\\:Delete\\ files))' \\
+            '*:file:_files'
+          ;;
+        base)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[show help]' \\
+            '--repo[use repository-local configuration]' \\
+            '(-s --silent)'{-s,--silent}'[suppress output messages]' \\
+            '--verbose[show verbose output]' \\
+            '1:subcommand:((get\\:Get\\ base\\ branch set\\:Set\\ base\\ branch))' \\
+            '*:branch:'
+          ;;
+        completions)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[show help]' \\
+            '1:shell:((bash\\:Generate\\ bash\\ completions zsh\\:Generate\\ zsh\\ completions))'
+          ;;
+        *)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[show help]' \\
+            '(-s --silent)'{-s,--silent}'[suppress output messages]' \\
+            '--verbose[show verbose output]'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_agency "$@"
+`
+
+export const completions = (shell: string | undefined) =>
+	Effect.gen(function* () {
+		if (!shell || !shells.includes(shell as Shell)) {
+			return yield* Effect.fail(
+				new Error("Usage: agency completions <bash|zsh>"),
+			)
+		}
+
+		console.log(
+			shell === "bash" ? generateBashCompletions() : generateZshCompletions(),
+		)
+	})
+
+export const help = `
+Usage: agency completions <bash|zsh>
+
+Generate shell completion scripts.
+
+Examples:
+  agency completions zsh > ~/.zsh/completions/_agency
+  agency completions bash > ~/.local/share/bash-completion/completions/agency
+`

package/src/commands/push.test.ts

@@ -40,6 +40,21 @@ async function setupBareRemote(): Promise<string> {
 	return remoteDir
 }
 
+async function checkoutNonAgencyBranch(gitRoot: string): Promise<void> {
+	const proc = Bun.spawn(
+		["git", "checkout", "-q", "-b", "plain-feature", "origin/main"],
+		{
+			cwd: gitRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+		},
+	)
+	const exitCode = await proc.exited
+	if (exitCode !== 0) {
+		throw new Error(await new Response(proc.stderr).text())
+	}
+}
+
 describe("push command", () => {
 	let tempDir: string
 	let remoteDir: string
@@ -92,6 +107,114 @@ describe("push command", () => {
 	})
 
 	describe("basic functionality", () => {
+		test("falls back to git push outside agency context", async () => {
+			await checkoutNonAgencyBranch(tempDir)
+			await createCommit(tempDir, "Plain feature work")
+			await Bun.write(join(tempDir, "uncommitted.txt"), "uncommitted\n")
+
+			await runTestEffect(
+				push({
+					gitArgs: ["origin", "plain-feature"],
+					silent: true,
+				}),
+			)
+
+			const localHead = await getGitOutput(tempDir, ["rev-parse", "HEAD"])
+			const remoteHead = await getGitOutput(tempDir, [
+				"rev-parse",
+				"refs/remotes/origin/plain-feature",
+			])
+			expect(remoteHead.trim()).toBe(localHead.trim())
+			expect(await Bun.file(join(tempDir, "uncommitted.txt")).exists()).toBe(
+				true,
+			)
+		})
+
+		test("forwards --no-verify to the git push fallback", async () => {
+			await checkoutNonAgencyBranch(tempDir)
+			await createCommit(tempDir, "Plain feature work")
+
+			await Bun.spawn(
+				["git", "config", "core.hooksPath", join(tempDir, ".git", "hooks")],
+				{
+					cwd: tempDir,
+					stdout: "pipe",
+					stderr: "pipe",
+				},
+			).exited
+			const hookPath = join(tempDir, ".git", "hooks", "pre-push")
+			await Bun.write(hookPath, "#!/bin/sh\nexit 1\n")
+			await Bun.spawn(["chmod", "+x", hookPath], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			}).exited
+
+			await runTestEffect(
+				push({
+					gitArgs: ["origin", "plain-feature"],
+					noVerify: true,
+					silent: true,
+				}),
+			)
+
+			const remoteBranches = await getGitOutput(tempDir, [
+				"ls-remote",
+				"--heads",
+				"origin",
+				"plain-feature",
+			])
+			expect(remoteBranches).toContain("plain-feature")
+		})
+
+		test("forwards force modes to the git push fallback", async () => {
+			await checkoutNonAgencyBranch(tempDir)
+			await createCommit(tempDir, "Initial plain feature work")
+			await Bun.spawn(["git", "push", "-u", "origin", "plain-feature"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			}).exited
+
+			await createCommit(tempDir, "Remote state for lease")
+			await Bun.spawn(["git", "push"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			}).exited
+			await Bun.spawn(["git", "reset", "--hard", "HEAD~1"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			}).exited
+			await createCommit(tempDir, "Lease-protected rewrite")
+
+			await runTestEffect(push({ forceWithLease: true, silent: true }))
+
+			await createCommit(tempDir, "Remote state for force")
+			await Bun.spawn(["git", "push"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			}).exited
+			await Bun.spawn(["git", "reset", "--hard", "HEAD~1"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			}).exited
+			await createCommit(tempDir, "Forced rewrite")
+
+			await runTestEffect(push({ force: true, silent: true }))
+
+			const localHead = await getGitOutput(tempDir, ["rev-parse", "HEAD"])
+			const remoteHead = await getGitOutput(tempDir, [
+				"ls-remote",
+				"origin",
+				"refs/heads/plain-feature",
+			])
+			expect(remoteHead.split("\t")[0]).toBe(localHead.trim())
+		})
+
 		test("fails when there are uncommitted changes", async () => {
 			// Create uncommitted changes
 			await Bun.write(join(tempDir, "uncommitted.txt"), "uncommitted\n")

package/src/commands/push.ts

@@ -2,7 +2,7 @@ import { Effect, Either } from "effect"
 import type { BaseCommandOptions } from "../utils/command"
 import { GitCommandError, GitService } from "../services/GitService"
 import { ConfigService } from "../services/ConfigService"
-import { resolveBranchPairWithAgencyJson } from "../utils/pr-branch"
+import { resolveAgencyBranchPairWithAgencyJson } from "../utils/pr-branch"
 import { emit } from "./emit"
 import highlight, { done } from "../utils/colors"
 import {
@@ -16,14 +16,54 @@ import { spawnProcess } from "../utils/process"
 
 interface PushOptions extends BaseCommandOptions {
 	baseBranch?: string
+	gitArgs?: string[]
 	emit?: string
 	branch?: string // Deprecated: use emit instead
 	force?: boolean
+	forceWithLease?: boolean
 	noVerify?: boolean
 	pr?: boolean
 	skipFilter?: boolean
 }
 
+const getFallbackGitPushArgs = (options: PushOptions): string[] => {
+	const args: string[] = []
+
+	if (options.force) {
+		args.push("--force")
+	}
+	if (options.forceWithLease) {
+		args.push("--force-with-lease")
+	}
+	if (options.noVerify) {
+		args.push("--no-verify")
+	}
+
+	args.push(...(options.gitArgs ?? []))
+	return args
+}
+
+const pushWithGit = (gitRoot: string, options: PushOptions) =>
+	Effect.gen(function* () {
+		const args = ["git", "push", ...getFallbackGitPushArgs(options)]
+		const result = yield* spawnProcess(args, {
+			cwd: gitRoot,
+			stdin: "inherit",
+			stdout: options.silent ? "pipe" : "inherit",
+			stderr: options.silent ? "pipe" : "inherit",
+		})
+
+		if (result.exitCode !== 0) {
+			return yield* Effect.fail(
+				new GitCommandError({
+					command: args.join(" "),
+					exitCode: result.exitCode,
+					stderr: result.stderr,
+				}),
+			)
+		}
+	})
+
 const getPushFailureStderr = (error: unknown): string => {
 	if (error instanceof GitCommandError) {
 		return error.stderr.trim()
@@ -91,7 +131,26 @@ const pushCore = (gitRoot: string, options: PushOptions) =>
 		const git = yield* GitService
 		const configService = yield* ConfigService
 
-		// Check for uncommitted changes
+		// Load config to check emit branch pattern
+		const config = yield* configService.loadConfig()
+
+		// Get current branch
+		let sourceBranch = yield* git.getCurrentBranch(gitRoot)
+
+		// Check if we're already on an emit branch using proper branch resolution
+		const branchInfo = yield* resolveAgencyBranchPairWithAgencyJson(
+			gitRoot,
+			sourceBranch,
+			config.sourceBranchPattern,
+			config.emitBranch,
+		)
+
+		if (!branchInfo) {
+			verboseLog("Outside agency branch context; falling back to git push")
+			return yield* pushWithGit(gitRoot, options)
+		}
+
+		// Agency push performs internal checkouts, so require a clean worktree.
 		const statusOutput = yield* git.getStatus(gitRoot)
 
 		if (statusOutput && statusOutput.trim().length > 0) {
@@ -106,20 +165,6 @@ const pushCore = (gitRoot: string, options: PushOptions) =>
 
 		verboseLog(`Working directory is clean`)
 
-		// Load config to check emit branch pattern
-		const config = yield* configService.loadConfig()
-
-		// Get current branch
-		let sourceBranch = yield* git.getCurrentBranch(gitRoot)
-
-		// Check if we're already on an emit branch using proper branch resolution
-		const branchInfo = yield* resolveBranchPairWithAgencyJson(
-			gitRoot,
-			sourceBranch,
-			config.sourceBranchPattern,
-			config.emitBranch,
-		)
-
 		// If we're on an emit branch, switch to the source branch first
 		if (branchInfo.isOnEmitBranch) {
 			const actualSourceBranch = branchInfo.sourceBranch
@@ -188,13 +233,15 @@ const pushCore = (gitRoot: string, options: PushOptions) =>
 			withSpinner(
 				pushBranchToRemoteEffect(gitRoot, emitBranchName, remote, {
 					force: options.force,
+					forceWithLease: options.forceWithLease,
 					noVerify: options.noVerify,
 					verbose: options.verbose,
 				}),
 				{
-					text: options.force
-						? `Pushing to ${highlight.remote(remote)} (forced)`
-						: `Pushing to ${highlight.remote(remote)}`,
+					text:
+						options.force || options.forceWithLease
+							? `Pushing to ${highlight.remote(remote)} (forced)`
+							: `Pushing to ${highlight.remote(remote)}`,
 					enabled: !options.silent && !options.verbose,
 				},
 			),
@@ -246,13 +293,14 @@ const pushBranchToRemoteEffect = (
 	remote: string,
 	options: {
 		readonly force?: boolean
+		readonly forceWithLease?: boolean
 		readonly noVerify?: boolean
 		readonly verbose?: boolean
 	},
 ) =>
 	Effect.gen(function* () {
 		const git = yield* GitService
-		const { force = false, noVerify = false } = options
+		const { force = false, forceWithLease = false, noVerify = false } = options
 
 		// Try pushing without force first
 		const pushResult = yield* git
@@ -276,12 +324,13 @@ const pushBranchToRemoteEffect = (
 			// Check if this is a force-push-needed error
 			const needsForce = pushFailureNeedsForce(stderr)
 
-			if (needsForce && force) {
-				// User provided --force flag, retry with force
+			if (needsForce && (force || forceWithLease)) {
+				// Retry using the force mode explicitly requested by the user.
 				const forceResult = yield* git
 					.push(gitRoot, remote, branchName, {
 						setUpstream: true,
-						force: true,
+						force,
+						forceWithLease,
 						noVerify,
 					})
 					.pipe(
@@ -303,7 +352,7 @@ const pushBranchToRemoteEffect = (
 				}
 
 				usedForce = true
-			} else if (needsForce && !force) {
+			} else if (needsForce) {
 				// User didn't provide --force but it's needed
 				return yield* Effect.fail(
 					formatPushFailure(
@@ -386,9 +435,10 @@ const openGitHubPR = (
 	})
 
 export const help = `
-Usage: agency push [base-branch] [options]
+Usage: agency push [arguments] [options]
 
-Create a emit branch, push it to remote, and return to the source branch.
+Create an emit branch, push it to remote, and return to the source branch.
+Outside agency branch context, fall through to plain 'git push'.
 
 This command is a convenience wrapper that runs operations in sequence:
   1. agency emit [base-branch]  - Create emit branch with backpack files reverted
@@ -404,31 +454,29 @@ Base Branch Selection:
   Same as 'agency emit' - see 'agency emit --help' for details
 
 Prerequisites:
-  - git-filter-repo must be installed: brew install git-filter-repo
-  - Remote 'origin' must be configured
+  - Agency branch pushes require git-filter-repo: brew install git-filter-repo
+  - A Git remote must be configured
 
 Arguments:
-  base-branch       Base branch to compare against (e.g., origin/main)
-                    If not provided, will use saved config or auto-detect
+  arguments         In agency context, the first argument is the base branch.
+                    Otherwise, arguments are passed to git push as remote/refspecs.
 
 Options:
   --emit            Custom name for emit branch (defaults to pattern from config)
-	--branch          (Deprecated: use --emit) Custom name for emit branch
-	-f, --force       Force push to remote if branch has diverged
-	--no-verify      Bypass git pre-push hooks
-	--pr              Open GitHub PR in browser after pushing (requires gh CLI)
+  --branch          (Deprecated: use --emit) Custom name for emit branch
+  -f, --force       Force push to remote if branch has diverged
+  --force-with-lease  Force push only if the remote branch is unchanged
+  --no-verify       Bypass git pre-push hooks
+  --pr              Open GitHub PR in browser after pushing (requires gh CLI)
 
 Examples:
-  agency push                          # Create PR, push, return to source
-	agency push origin/main              # Explicitly use origin/main as base
-	agency push --force                  # Force push if branch has diverged
-	agency push --no-verify              # Push without running pre-push hooks
-	agency push --pr                     # Push and open GitHub PR in browser
+  agency push                       # Push the emitted branch or current branch
+  agency push origin/main           # Use an explicit base in agency context
+  agency push origin feature        # Pass remote/refspec outside agency context
 
 Notes:
-  - Must be run from a source branch (not a emit branch)
-  - Creates or recreates the emit branch
-  - Pushes with -u flag to set up tracking
-  - Automatically returns to source branch after pushing
+  - Outside agency context, positional arguments and --force, --force-with-lease, and --no-verify are passed to git push
+  - In agency context, creates or recreates the emit branch and pushes it with -u
+  - In agency context, automatically returns to the source branch after pushing
   - If any step fails, the command stops and reports the error
 `

package/src/services/GitService.ts

@@ -1046,6 +1046,7 @@ export class GitService extends Effect.Service<GitService>()("GitService", {
 			options?: {
 				readonly setUpstream?: boolean
 				readonly force?: boolean
+				readonly forceWithLease?: boolean
 				readonly noVerify?: boolean
 			},
 		) => {
@@ -1056,6 +1057,9 @@ export class GitService extends Effect.Service<GitService>()("GitService", {
 			if (options?.force) {
 				args.push("--force")
 			}
+			if (options?.forceWithLease) {
+				args.push("--force-with-lease")
+			}
 			if (options?.noVerify) {
 				args.push("--no-verify")
 			}