Save‑ShpChat

SYNOPSIS

Writes the running Session chat to a caller-named store as a new checkpoint.

SYNTAX

Save-ShpChat [-Path] <String> [[-Label] <String>] [-Force] [-WhatIf]
 [-Confirm] [<CommonParameters>]

DESCRIPTION

Persists the conversation Invoke-Shp continues by default, so it can be resumed in another session, rolled back to an earlier point, or forked into an alternative line. It implements the tier-2 half of decision 002, and the rules that decision settled are the rules here:

• The path is yours. Nothing is discovered, defaulted, or derived from TEMP, the profile, or the working directory. A conversation is the most sensitive thing this module handles, and a store nobody asked for is one nobody knows to delete.
• Redaction is applied on write. The stored turns are redacted turns. A resumed session therefore replays redacted history, and the model may answer differently than it did the first time. That is stated plainly because it is a visible consequence, not a detail.
• Retention is yours. The store only grows. This cmdlet appends and never prunes, rotates, or reclaims; deciding when a stored conversation stops being wanted is not something the module can do on your behalf.
• A schema version is written from the first save and refused rather than migrated when it is not recognised.

Only a DURABLE checkpoint is written. The Session chat holds completed user/assistant exchanges because Invoke-Shp writes it back only on success, so a checkpoint cannot contain an in-flight Tool call - and a conversation that somehow does is refused rather than stored, because resuming from one would mean replaying a Tool call whose outcome nobody knows.

Side effects whose Turn did NOT complete are recorded on the checkpoint as uncertain, and warned about. They are never replayed on resume; they are named so a person can decide what to do about them.

The store records a revision. A save whose store has moved on since this session last saw it is refused as a conflict, so two shells checkpointing the same file cannot silently overwrite each other's idea of history. Use -Force to append anyway, which branches rather than overwrites.

EXAMPLES

EXAMPLE 1

Save-ShpChat -Path ./review-session.json

Appends the current conversation as a new checkpoint.

EXAMPLE 2

Save-ShpChat -Path ./review-session.json -Label 'before the refactor'

Appends a named checkpoint you can come back to.

PARAMETERS

-Force

Append even when the store has been advanced by another writer since this session last read it. Nothing is overwritten; the new checkpoint is chained to the one this session knows.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Label

A short caller-chosen name for this checkpoint, shown by Get-ShpChatCheckpoint.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Path

The store file to write. Mandatory, always; there is no default.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

A ShellPilot.ChatCheckpoint: CheckpointId, ParentCheckpointId, Label,

Path, Turns, Model, Revision, Sha256 and UncertainSideEffects.

NOTES

RELATED LINKS

Restore-ShpChat

Get-ShpChatCheckpoint

Get-ShpChat

Compress-ShpChat