How OfficeCLI Avoids File Locks When Using Resident Mode: Single-Process Ownership with Named-Pipe IPC

OfficeCLI prevents file lock conflicts by delegating all document access to a long-running background process that holds the OS file lock exclusively, while client commands communicate via named-pipe IPC instead of touching the file directly.

When processing Office documents in automated workflows, concurrent access attempts usually trigger "file in use" errors that break CI/CD pipelines. The iOfficeAI/OfficeCLI repository solves this through resident mode—an architecture where a ResidentServer process maintains exclusive ownership of the document, eliminating race conditions while allowing controlled read access for other processes.

The Resident Mode Architecture

Resident mode centralizes document handling in a background process launched via officecli open <file>. This process lives for the duration of the editing session and maintains a single open file handle via DocumentHandlerFactory.Open.

Single Owner of the File

The ResidentServer class acquires the file lock once and retains it until shutdown. In src/officecli/ResidentServer.cs (lines 15–30), the server stores the document handler in a private _handler field immediately after launching:

// ResidentServer.cs - Initialization
_handler = DocumentHandlerFactory.Open(filePath, editable: true);
// _handler remains alive for the entire process lifetime

By preventing multiple processes from opening the same file directly, this approach ensures that only the resident process interacts with the underlying document on disk.

Five Lock-Avoidance Techniques

The resident implementation combines several defensive mechanisms to maintain lock integrity across asynchronous operations.

Ping-Liveness Invariant

Clients verify resident availability through a dedicated ping pipe before sending commands. The resident only responds to __ping__ requests while actively holding the lock. In ResidentServer.cs (lines 49–52), the ping responder returns the file path exclusively during valid lock tenure:

// ResidentServer.cs - Ping handling
if (request.Command == "__ping__")
{
    var response = MakeResponse(0, _filePath, "");
    await WriteLineToPipeAsync(accepted, response, token);
}

If the resident is shutting down, it cancels the ping responder only after disposing _handler, ensuring that a successful ping guarantees lock ownership.

Separate Cancellation Tokens

The server maintains two distinct cancellation token sources: _mainCts for the command loop and _pingCts for the watchdog. As shown in ResidentServer.cs (lines 37–44), the shutdown sequence cancels _mainCts first, disposes the handler to release the OS lock, and only then cancels _pingCts. This ordering prevents clients from receiving "alive" signals after the lock is released.

Pre-Creating Named Pipes

To eliminate race windows where no listener exists, the server creates the next NamedPipeServerStream before handling the current connection. In ResidentServer.cs (lines 12–22 and 300–321), the NewMainServer() method instantiates the subsequent pipe immediately after accepting a client:

// From ResidentServer.cs lines 300-321 (conceptual)
var nextServer = NewMainServer();  // Create next pipe BEFORE processing
await currentServer.WaitForConnectionAsync();
// Handle current request while next pipe is already waiting

This pattern applies to both the main command pipe and the ping pipe, preventing clients from falling back to direct file access due to connection timeouts.

Command-Level Serialization

Concurrent operations could corrupt documents or create deadlocks. A SemaphoreSlim _commandLock serializes all mutations in ResidentServer.cs (lines 54–62 and 335–345). The HandleClientWithLockAsync method acquires this semaphore before invoking any document operation, ensuring atomic save operations even under high client concurrency.

Idle Autosave and Graceful Shutdown

The resident flushes changes through RunIdleWatchdogAsync (ResidentServer.cs lines 86–108) without releasing the file handle. When the user executes officecli close or the idle timeout expires, ShutdownAsync disposes _handler before terminating the ping responder, guaranteeing that the OS lock persists until all cleanup completes.

Client-Server Communication Flow

Understanding the interaction pattern clarifies how external processes avoid lock contention:

1. Resident Launch: officecli open <file> creates a ResidentServer process (see Program.cs).
2. Lock Acquisition: The server opens the document via _handler = DocumentHandlerFactory.Open and holds the exclusive OS lock.
3. IPC Probe: Client commands use ResidentClient.TryConnect to send a __ping__ request over the ping pipe. If successful, the client knows the resident holds the lock.
4. Command Dispatch: The client sends the actual operation over the main named pipe; the resident executes via _commandLock-protected methods.
5. Fallback Handling: Failed pings indicate no resident exists, prompting clients to open the file directly with editable: false for read-only access.

Code Example: Detecting Resident Availability

The ResidentClient class encapsulates the ping-check logic. In src/officecli/ResidentClient.cs (lines 13–23), TryConnect probes the pipe without acquiring file locks:

// ResidentClient.cs - Connection probing
var resident = new ResidentClient(filePath);
if (resident.TryConnect(100))               // 100ms timeout
{
    // Resident holds lock; send command via IPC
    var response = resident.SendCommand("{\"command\":\"get\",\"path\":\"/body\"}");
    Console.WriteLine(response);
}
else
{
    // No resident; fall back to direct file handling
    var handler = DocumentHandlerFactory.Open(filePath, editable: false);
    var result = handler.Get("/body");
    Console.WriteLine(result);
}

This separation allows read-only tools (e.g., python-docx, Excel) to open the file simultaneously while the resident maintains write access.

Summary

• Single-process ownership: ResidentServer holds the exclusive file lock via DocumentHandlerFactory.Open for the entire session duration.
• Named-pipe IPC: All CLI commands route through ResidentClient.TryConnect and named pipes, avoiding direct file access that would trigger lock conflicts.
• Liveness guarantees: The __ping__ protocol ensures clients only communicate when the lock is definitively held.
• Ordered shutdown: Cancellation tokens dispose the handler before terminating IPC, preventing premature lock release.
• Concurrent safety: SemaphoreSlim serialization prevents overlapping save operations that could deadlock the file.

Frequently Asked Questions

How does OfficeCLI prevent "file in use" errors during batch processing?

By delegating all document operations to a ResidentServer process that holds the OS file lock continuously while exposing a named-pipe API for client commands. This architecture ensures only one process touches the file on disk, while other processes communicate via IPC rather than attempting direct access.

What happens if the resident process crashes while holding a file lock?

The resident implements a ping-liveness invariant where the ping responder (ResidentServer.cs lines 49–52) only returns success while the handler exists. If the process crashes, the OS automatically releases the file lock, and subsequent ResidentClient.TryConnect calls fail, allowing clients to fall back to direct file access without hanging.

Can multiple clients modify the same document simultaneously through the resident?

No. While multiple clients can connect via named pipes, the ResidentServer uses a SemaphoreSlim _commandLock (ResidentServer.cs lines 54–62) to serialize all mutation commands. Only one save operation executes at a time, preventing corruption and deadlocks.

Why does the resident pre-create named pipes before handling connections?

Pre-creating the next NamedPipeServerStream in NewMainServer() (ResidentServer.cs lines 300–321) eliminates the microsecond window where no server is listening. Without this protection, a client timeout might incorrectly assume the resident is dead and attempt direct file access, creating a race condition with the existing lock holder.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}