main
1import { spawnSync } from 'node:child_process'
2import { mkdir, open, readFile, rmdir, stat, unlink } from 'node:fs/promises'
3import { homedir, hostname } from 'node:os'
4import { dirname, join } from 'node:path'
6/**
7 * One writer of the Worker's deployment at a time, across worktrees and agents.
8 *
9 * Two runs overlapped on 2026-11-07: run 2026-11-07T18-30-47-501Z replaced another agent's measurement canary
10 * (b494b751) in the 0% slot. The `pgrep` habit in the runbook was advisory. This lock is not: every command that
11 * writes the deployment (`cd`, `deploy-canary`, `ramp`, `rollback`) takes it before it opens a run directory, and a
12 * second run refuses while the holder is alive.
13 *
14 * The lock is a file created with O_EXCL in the shared state directory (`~/.local/state/ply-cd/deploy.lock`, beside the
15 * ledger, so every worktree sees the same one). It holds the holder's pid, host, cwd, command and start time. A lock whose
16 * pid is gone (or is no longer a `scripts/cd/main.ts` process: a reused pid) on this host is stale and is taken over; the
17 * takeover itself is serialised by a `mkdir` mutex so two runs cannot both steal one stale lock. A lock from another host
18 * cannot be checked and is never taken over.
19 */
21export type LockHolder = {
22 readonly pid: number
23 readonly host: string
24 readonly cwd: string
25 readonly command: string
26 readonly startedAt: string
27}
29export type LockResult =
30 | { readonly ok: true; readonly path: string; readonly holder: LockHolder; readonly tookOver: LockHolder | null; release(): Promise<void> }
31 | { readonly ok: false; readonly path: string; readonly holder: LockHolder | null; readonly reason: string }
33export type LockIo = {
34 /** True while `pid` on this host is a live CD process. */
35 alive(pid: number): boolean
36 host(): string
37 now(): Date
38}
40/** `PLY_CD_LOCK` overrides it. */
41export function defaultLockPath(): string {
42 return join(homedir(), '.local', 'state', 'ply-cd', 'deploy.lock')
43}
45const CD_ENTRY = /scripts\/cd\/main\.ts/
47/** Alive and still a CD process. EPERM from signal 0 is alive (another user's process). */
48export function pidIsCd(pid: number): boolean {
49 if (!Number.isInteger(pid) || pid <= 0) return false
50 try {
51 process.kill(pid, 0)
52 } catch (error) {
53 if ((error as NodeJS.ErrnoException).code !== 'EPERM') return false
54 }
55 const ps = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' })
56 // `ps` unavailable: trust signal 0 rather than steal a live lock.
57 if (ps.error) return true
58 return CD_ENTRY.test(String(ps.stdout))
59}
61export const realLockIo: LockIo = {
62 alive: pidIsCd,
63 host: () => hostname(),
64 now: () => new Date(),
65}
67function parseHolder(text: string): LockHolder | null {
68 try {
69 const value = JSON.parse(text) as Partial<LockHolder>
70 if (typeof value.pid !== 'number' || typeof value.host !== 'string') return null
71 return {
72 pid: value.pid,
73 host: value.host,
74 cwd: typeof value.cwd === 'string' ? value.cwd : '?',
75 command: typeof value.command === 'string' ? value.command : '?',
76 startedAt: typeof value.startedAt === 'string' ? value.startedAt : '?',
77 }
78 } catch {
79 return null
80 }
81}
83async function readHolder(path: string): Promise<{ readonly text: string; readonly holder: LockHolder | null } | null> {
84 try {
85 const text = await readFile(path, 'utf8')
86 return { text, holder: parseHolder(text) }
87 } catch (error) {
88 if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
89 throw error
90 }
91}
93async function create(path: string, holder: LockHolder): Promise<boolean> {
94 try {
95 const handle = await open(path, 'wx', 0o600)
96 try {
97 await handle.writeFile(JSON.stringify(holder) + '\n')
98 } finally {
99 await handle.close()
100 }
101 return true
102 } catch (error) {
103 if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
104 throw error
105 }
106}
108export function describeHolder(holder: LockHolder): string {
109 return `pid ${holder.pid} on ${holder.host}, started ${holder.startedAt}, cwd ${holder.cwd}, command "${holder.command}"`
110}
112/** A takeover mutex older than this was left by a crashed takeover. */
113const STEAL_STALE_MS = 30_000
115async function withStealMutex<T>(path: string, fn: () => Promise<T>): Promise<T | 'busy'> {
116 const mutex = `${path}.steal`
117 try {
118 await mkdir(mutex)
119 } catch (error) {
120 if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
121 const held = await stat(mutex).catch(() => null)
122 const age = held ? Date.now() - held.mtimeMs : Number.POSITIVE_INFINITY
123 if (age <= STEAL_STALE_MS) return 'busy'
124 await rmdir(mutex).catch(() => {})
125 try {
126 await mkdir(mutex)
127 } catch {
128 return 'busy'
129 }
130 }
131 try {
132 return await fn()
133 } finally {
134 await rmdir(mutex).catch(() => {})
135 }
136}
138/**
139 * Take the deployment lock or say who has it. Never waits: a second run is refused, not queued, because the first
140 * one's split is what the second would plan against.
141 */
142export async function acquireLock(
143 path: string,
144 info: { readonly command: string; readonly cwd: string; readonly pid: number },
145 io: LockIo = realLockIo,
146): Promise<LockResult> {
147 await mkdir(dirname(path), { recursive: true })
148 const me: LockHolder = {
149 pid: info.pid,
150 host: io.host(),
151 cwd: info.cwd,
152 command: info.command,
153 startedAt: io.now().toISOString(),
154 }
155 const granted = (tookOver: LockHolder | null): LockResult => ({
156 ok: true,
157 path,
158 holder: me,
159 tookOver,
160 release: async () => {
161 // Remove only our own lock: a holder that was (wrongly) taken over must not delete its successor's.
162 const seen = await readHolder(path).catch(() => null)
163 if (seen && seen.holder && seen.holder.pid === me.pid && seen.holder.host === me.host && seen.holder.startedAt === me.startedAt) {
164 await unlink(path).catch(() => {})
165 }
166 },
167 })
168 if (await create(path, me)) return granted(null)
169 const seen = await readHolder(path)
170 if (seen === null) {
171 // Released between our create and our read: one more try, then refuse rather than loop.
172 if (await create(path, me)) return granted(null)
173 return { ok: false, path, holder: null, reason: `deployment lock ${path} changed hands while it was read; try again` }
174 }
175 const holder = seen.holder
176 if (holder && holder.host !== me.host) {
177 return { ok: false, path, holder, reason: `deployment lock ${path} is held by ${describeHolder(holder)}; another host's pid cannot be checked, so it is not taken over` }
178 }
179 if (holder && io.alive(holder.pid)) {
180 return { ok: false, path, holder, reason: `deployment lock ${path} is held by a live run: ${describeHolder(holder)}` }
181 }
182 // Stale (dead pid, reused pid, or an unreadable body). Take it over under the mutex, re-reading first.
183 const stolen = await withStealMutex(path, async () => {
184 const again = await readHolder(path)
185 if (again !== null && again.text !== seen.text) return false
186 if (again !== null) await unlink(path).catch(() => {})
187 return create(path, me)
188 })
189 if (stolen === true) return granted(holder || { pid: -1, host: '?', cwd: '?', command: 'unreadable lock file', startedAt: '?' })
190 return { ok: false, path, holder, reason: `deployment lock ${path} was stale and another run is taking it over; try again` }
191}
Diagnostics4 git calls · 303 ms
CallStatusSizeTime0303 ms
discover200152 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=152 git.server.agent=gitty/1.0 git.server.object_format=sha1 git.server.caps=agent ls-refs fetch object-format git.server.fetch=shallow filter sideband-all git.protocol.version=2 git.pkt.frames=8 git.pkt.data=6 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=152 git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=3 git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=145 git.pkt.payload.max=76 git.ls_refs.count=2 git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020040 KiB · hit7 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=41349 git.response.cache=HIT git.response.duration_ms=7 git.fetch.filter=blob:none git.fetch.filter.requested=tree:0 git.fetch.filter.fallback=blob:none git.fetch.filter.learned=false git.fetch.wants=526b305930b8ef382f2d7a1f9c0238730a585921 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=6 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=41349 git.pkt.payload.max=41254 git.sideband.band1.bytes=41253 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=61 git.pack.bytes=41253 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c git.pack.full=61Open pack map
fetch2002.7 KiB293 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=293 git.response.bytes=2748 git.response.cache=MISS git.response.duration_ms=293 git.fetch.wants=011e35821de53daddda91845f4a577031d12abd5 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2748 git.pkt.payload.max=2727 git.sideband.band1.bytes=2726 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
- Ref
- refs/heads/main
- Commit
- 526b305930b8ef382f2d7a1f9c0238730a585921
- cf-ray
- a5e2bbf5d9e8cfc3
- Request
- c11877bc…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format